This repository contains the server for the ShoppingList.

Link to the Android client repository: https://github.com/cquintana92/shoppinglist-android

You can go to the releases section of this project and download the binary for your system (only Mac and Linux are supported (64 bit architectures) due to the sqlite3 dependency, which makes it hard to cross-compile).

This project has a Makefile that provides an easy way to run standard commands. You can run make help to see which options are available. In order to build it, you can just run make build.

You can find a Docker image in Docker hub.

Once you have your binary, you are ready to go!

In order to explore the different options, you can run $ shopping-list --help to inspect them.

$ shopping-list --help
GLOBAL OPTIONS:
   --loglevel value        Log Level [TRACE, DEBUG, INFO, WARN, ERROR] (default: "INFO") [$LOGLEVEL]
   --dbUrl value           Database URL connection (either sqlite3://PATH_TO_DB or PostgreSQL connection string) [$DB_PATH]
   --secretEndpoint value  Secret endpoint without authorization (useful for 3rd party integrations) [$SECRET_ENDPOINT]
   --secretBearer value    Secret bearer authorization in order to secure your server (Header: Authorization: Bearer YOUR_SECRET [$SECRET_BEARER]
   --port value            Port where the server will listen (default: 5454) [$PORT]
   --help, -h              show help
   --version, -v           print the version

As you can see, the binary has sensible defaults, but you can easily override them via command line flags or environment variables.

If you want to use an sqlite database, you will need to set --dbUrl sqlite3://PATH_TO_THE_DATABASE. In case the database does not exist, it will be created and initialized.

The server can receive a secretBearer parameter which will be used in order to prevent undesired access to your shopping list.

It must be passed to the server in the HTTP requests by setting the Authorization header to the following value:

Authorization: Bearer YOUR_SECRET_BEARER

That means, if your secret bearer is "ILikeTrains", your HTTP requests must contain the header:

Authorization: Bearer ILikeTrains

However, there are some third party integrations that do not support setting headers to your requests (such as IFTTT). In order to support these integrations, you can define a secret creation endpoint which does not need any authorization. It can be configured with the secretEndpoint parameter.

That means, if you have set your secret bearer to ILikeTrains and your secret endpoint to iliketrains, you will be able to create new items by either:

• Sending a POST request with the Authorization: Bearer ILikeTrains header (POST /).
• Sending a POST request without authorization (POST /iliketrains).

You can use a docker-compose like the following:

version: '3'
services:
  shopping:
    image: cquintana92/shoppinglist:latest
    ports:
      - "5454:5454"
    volumes:
      - "./data:/data"
    environment:
      LOGLEVEL: INFO
      DB_URL: "sqlite3:///data/shopping.sqlite"
      PORT: 5454
      SECRET_ENDPOINT: super_secret_endpoint
      SECRET_BEARER: my_super_secret
    restart: always

Or for deploying with postgresql:

version: '3'
services:
  # PostgreSQL database
  postgresql:
    image: postgres:12-alpine
    environment:
      POSTGRES_USER: postgresuser
      POSTGRES_PASSWORD: postgrespassword
      POSTGRES_DB: shoppinglistdb
    volumes:
      - "postgres_data:/var/lib/postgresql"
    restart: always

  # Shopping list server
  shopping:
    image: cquintana92/shoppinglist:latest
    ports:
      - "5454:5454"
    volumes:
      - "./data:/data"
    environment:
      LOGLEVEL: INFO
      DB_URL: "postgresql://postgresuser:postgrespassword@postgresql:5432/shoppinglistdb?sslmode=disable"
      PORT: 5454
      SECRET_ENDPOINT: super_secret_endpoint
      SECRET_BEARER: my_super_secret
    restart: always

volumes:
  postgres_data:

Sometimes, if you are using this server via a smart speaker, there are some words that are not spelt properly (such as names). There is an option, configured via the --replacements flag or the REPLACEMENTS env variable, that allows you to fix these kind of mistakes.

The format is the following:

export REPLACEMENTS="source=dest,other=word"

The source will be tested case-insensitively, while the replacement will be applied as-is.

In case you want to use the Todoist webhook endpoint (such as, integrating it with you Alexa shopping list via the Todoist integration) you can do so y defining the following parameters / env variables:

• todoistAppId / TODOIST_APP_ID: AppId of your Todoist app. Will be used for verifying the requests.
• todoistEndpoint / TODOIST_ENDPOINT: Path to the endpoint you want to use for receiving Todoist requests.