Docker

Running Sal on Docker

This guide assumes you have installed Docker as per the instructions on their site, and that you have a working knowledge of the basics of Docker. The Docker user guide is an excellent place to start.

Basic setup

This will get you going with a default Sal installation, with a Postgres database. All commands below should be run as root.

Database

# This is where the database data will live. Adjust to your taste
$ mkdir -p /usr/local/sal_data/db
$ docker run -d --name="postgres-sal" \
  -v /usr/local/sal_data/db:/var/lib/postgresql/data \
  -e DB_NAME=sal \
  -e DB_USER=admin \
  -e DB_PASS=password \
  --restart="always" \
  grahamgilbert/postgres:9.4.5

Set the database details according to your preferences.

Running Sal

Assuming you've not changed the default database username and password:

$ docker run -d --name="sal"\
  -p 80:8000 \
  --link postgres-sal:db \
  -e ADMIN_PASS=pass \
  -e DB_NAME=sal \
  -e DB_USER=admin \
  -e DB_PASS=password \
  macadmins/sal:3.0.3

This will allow you to log in with the username admin and the password pass (which I suggest you change!).

RDS Database

If you want to link to an RDS database, you simply put the variables in the docker run. RDS by default uses 5432.

docker run -d --name="sal" \
-p 80:8000 \
-e ADMIN_PASS=pass \
-e DB_HOST=yourname.id.us-east-1.rds.amazonaws.com \
-e DB_PORT=5432 \
-e DB_PASS=password \
-e DB_NAME=sal \
-e DB_USER=admin \
--restart="always" macadmins/sal:3.0.3

Upgrading

Upgrading using Docker is simple:

$ docker pull macadmins/sal  
$ docker stop sal  
$ docker rm sal  
$ docker run -d --name="sal" \
  -p 80:8000 \
  --link postgres-sal:db \
  -e ADMIN_PASS=pass \
  -e DB_NAME=sal \
  -e DB_USER=admin \
  -e DB_PASS=password \
  macadmins/sal:someversion

You should select the latest version number to install, located on the Docker Hub image registry. Substitute the tagged version number you'd find here for 'someversion' above to select what exact version you're upgrading to. These docs may not always have the most current version of each image, but should reflect the last tested-stable tagged version.

Other options and plugins

For other options that can be set via environment variables, and for how to use advanced options such as plugins, see the repo on the Docker Hub.

Development / Testing Images / More Docker Background

It is not recommended to run unreleased versions in production, but images built from the latest commit on the Sal app itself may be fetched by changing the last line of the Sal run command, substituting macadmins/sal:latest, with quay.io/macadmins/sal:latest

While not specific to Sal, these slides on using Docker give an overview of a testing workflow, and the tools can be installed quickly by running autopkg install DockerToolbox.

Upgrading Database

With the database container you wish to upgrade running, do the following:

Display your container's IP Address:

$ docker inspect postgres-sal | grep “IPAddress”

Note: For the following commands replace $IPADRESS with your container's IP Address.

Backup your current sal database with:

$ sudo -u postgres psql -h $IPADRESS saldbname
ALTER USER usersaldb WITH SUPERUSER;
\q
$ psql -h $IPADRESS -U usersaldb saldbname > sal-db-dump

Pull the latest grahamgilbert/postgres container from Dockerhub and stop sal containers:

$ docker pull grahamgilbert/postgres
$ docker stop postgres-sal sal
$ docker rm postgres-sal sal

Run your updated grahamgilbert/postgres container: Run your Database Container!

Note: Your postgres container could have a new IP Address. Make changes if needed.

Now restore your database with:

$ docker inspect postgres-sal | grep “IPAddress”
$ sudo -u postgres psql -h $IPADRESS saldbname
ALTER USER usersaldb WITH SUPERUSER;
\q
$ psql -h $IPADRESS -U usersaldb saldbname < sal-db-dump

You should have successfully upgraded your postgres-sal container.

Lastly, remember to start your Sal container: Run your Sal container.