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 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
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
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:/dbvolume mount your home directory's
/tmpsubdirectory on the host side as
/dbon the container side.
-e SQLITE_FILEPATH=/db/db.sqlite: set the environment variable
SQLITE_FILEPATHto 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
--helpinstead 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:3000expose 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.
To connect to a PostgreSQL database instead, set the environment variable DATABASE_URL or PGUSER, PGHOST, PGPORT, PGPASSWORD and PGDATABASE (same as
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
trueto 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.