Deploy with Docker

Docker images are available from the Docker Hub and can be used for deploying Saltcorn. The repository is saltcorn/saltcorn and at least two tags are available: latest and dev.

latest images are based on the latest released versions. This is the recommended images to use. To download, run:

docker pull saltcorn/saltcorn:latest

dev images are the bleeding edge from GitHub, download with:

docker pull saltcorn/saltcorn:dev

SQLite database

The images need to be run with environment variables that indicate how Saltcorn should connect to a database. To use the SQLite database (testing and development only, not recommended production deployment), set the SQLITE_FILEPATH variable to indicate the path to the SQLite database file to use, as seen from inside the docker container. You almost certainly want to make this a mounted volume or some other persistent filesystem.

You should also choose a session secret. This act like a password and encrypt your cookies and session storage. You can pick any short string of random characters. Here we will use the example s3cr3t. This should be assigned to the environment variable SALTCORN_SESSION_SECRET.

Before you can run Saltcorn against a SQLite database, you need to install the database schema first. For instance, if you intend to use a file tmp/db.sqlite in your home directory's tmp subdirectory as the database, you can install this schema (this will create the database file if it does not exist) by running in a shell:

docker run -it -v ~/tmp:/db -e SQLITE_FILEPATH=/db/db.sqlite -e SALTCORN_SESSION_SECRET=s3cr3t saltcorn reset-schema

Here is a breakdown of the parts of the command:

  • docker: invokes the docker command
  • run: tells docker to create a new container and run a command in it
  • -it: we will be interacting with this command on the terminal
  • -v ~/tmp:/db volume mount your home directory's /tmp subdirectory on the host side as /db on the container side.
  • -e SQLITE_FILEPATH=/db/db.sqlite: set the environment variable SQLITE_FILEPATH to point to the location of the database file in the container side. Saltcorn knows to look in this environment variable for a SQLite database file.
  • -e SALTCORN_SESSION_SECRET=s3cr3t: set the environment variable with the session secret
  • saltcorn: this is the image name to use for the new container
  • reset-schema: the command given to the Saltcorn commandline interface. Other commands are available, call with --help instead of the last argument to list them.

After resetting the database, you can then run the Saltcorn server with:

docker run -d -v ~/tmp:/db -e SQLITE_FILEPATH=/db/db.sqlite -p 3000:3000 saltcorn serve

The difference with the above command are:

  • -d: run this command in the background, not interactively
  • -p 3000:3000 expose port 3000
  • serve: this is the subcommand to start the server

You should now be able to visit port 3000 on the server. If you visit / you should be redirected to where you can create the admin user.

PostgreSQL database

To connect to a PostgreSQL database instead, set the environment variable DATABASE_URL or PGUSER, PGHOST, PGPORT, PGPASSWORD and PGDATABASE (same as psql)

You will again need to reset the database as above.

Additional environment variables

  • SALTCORN_SESSION_SECRET: set this to a random string used to encrypt session cookies (there is a default key but using it is not safe as it is openly readable in the Saltcorn code base)
  • SALTCORN_MULTI_TENANT: set to true to enable multi-tenancy (default false, multi-tenancy disabled)
  • SALTCORN_FILE_STORE: point to a directory to use for storing uploaded files. (Defaults to your platform's application datastore, ie XDG data on Linux and AppData on Windows)

Building the images

The definition of the images are given here: https://github.com/saltcorn/saltcorn/blob/master/Dockerfile.dev and https://github.com/saltcorn/saltcorn/blob/master/Dockerfile.release.

The 2 images should be functionally similar The dev images are built from source whereas release uses the npm packages.