Running Serpico From Docker

Scenarios

There are a few different scenarios when running Serpico via Docker. Hopefully this wiki has one that fits your use case. If not, please create an issue or notify us in the Slack channel (e-mail support to access Slack).

0. Help Me, I am scared of Docker
1. Install Serpico for the first time
2. Updating Serpico from an existing container
3. Updating Serpico from an existing developer build
4. Updating Serpico from an existing binary installation
5. I want to delete my existing Serpico data and start over (i.e. Developer play)
6. Configure existing Serpico
7. Building a branded Serpico for your company
8. More Detailed Docker Info
9. Backing up your data

Scared

It's OK, I was you once. Docker is an incredible technology and worth understanding at least the basics of. Luckily to run Serpico you need to know very little Docker. The only prerequisite is that you have Docker installed on your system:

https://docs.docker.com/install/

There are a few commands to keep in mind.

To check if your current Docker Serpico instance is running:

docker ps | grep -i serpico

If you don't see Serpico running (and you have already pulled the instance from DockerHub), restart it with:

docker start serpico

That is it for now, we can add more as people need help.

Install Serpico for the first time

1. Create a working directory for your Serpico instance. This command will be specific to your OS, but assuming Linux:

mkdir SERPICO
cd SERPICO

2. Pull the down the Serpico docker container and Start Serpico inside your directory; this is where your database and data will be stored.

docker run --name serpico -p 8443:8443 \
  -v"$(pwd)/db":/Serpico/db -v"$(pwd)/tmp":/Serpico/tmp \
  -v"$(pwd)/attachments":/Serpico/attachments \
  -it serpico/serpico

If you stop your instance of Serpico, you can easily restart it with:

docker start serpico

3. Open up a web browser and start using Serpico; https://localhost:8443/

Updating Serpico from an existing container

First, make sure you have backed up all of your data. You can use docker's cp command to store your data in a safe place (e.g. docker cp serpico:/Serpico my_local_backup_dir)

1. Change directories to an existing Serpico installation. For example, you should have a db directory,etc.
2. Stop your running Serpico container and change it's name. Below I assume your container name is serpico. Changing the name is important:

docker stop serpico
docker rename serpico serpico_old

3. Copy the existing configuration files into your present directory:

docker cp serpico_old:/Serpico/cert.pem .
docker cp serpico_old:/Serpico/key.pem .
docker cp serpico_old:/Serpico/config.json .
docker cp serpico_old:/Serpico/templates/ .

4. Create the new container. Note, the template directory is now mounted.

docker create --name serpico -p 8443:8443 \ 
-v"$(pwd)/templates":/Serpico/templates \
-v"$(pwd)/db":/Serpico/db -v"$(pwd)/tmp":/Serpico/tmp \
-v"$(pwd)/attachments":/Serpico/attachments \
-it serpico/serpico

5. Copy over your configuration files and start Serpico:

sudo docker cp cert.pem serpico:/Serpico/
sudo docker cp key.pem  serpico:/Serpico/
sudo docker cp config.json serpico:/Serpico/
sudo docker cp templates serpico:/Serpico/templates/
sudo docker start serpico

You should be good to go.

Docker Developer Information

The included Dockerfile allows you to run Serpico inside docker from any system that supports containers.

By default, Serpico listens on 8443, you can expose it as 443 if you would like by using docker run -p 443:8443 ...

The image needs to first be built.

1. Build the image
2. Map the database location in docker-compose or at docker run time.
3. If the database doesn't exist, it will be created with defaults

Creating the image

This will create a container with the current state of your repository. The database is not created at this point, and this image is safe for distribution.

docker build -t serpico .

The Dockerfile exposes a VOLUME at /Serpico/db to allow mounting an external database through docker-compose or docker run -v.

Running with docker run

# Create a new container called "serpico" and run it in the foreground
docker run --name serpico -p 8443:8443 -v"$(pwd)":/Serpico/db -it serpico

# Stop the container when you no longer need it
docker stop serpico

# Start it again when you need it. It will keep its state.
docker start serpico

This will store the database locally at $PWD/master.db Please note that the path to the database on the host must be absolute.

docker-compose

The docker-compose.yml in the repository is aimed at development use. It will provision the ruby environment inside the container and mount the repository as the docker application, allowing for reloading the source code by simply restarting the container. The dockerfile docker/dev.dockerfile is used by compose.

Caveats

This is a work in progress, so a few things are currently not supported.

• Running a new container with an existing master.db will not work because first_time.rb will not run, and there won't be any certificates for SSL.
• config.json is not exposed to the host so customization requires rebuilding the image or accessing it with docker exec bash.
• docker-compose up will not automatically reload the backend when .rb files are changed. This is a possible improvement.