Production mode

SciNote can be run in production mode using Docker containers.

Running server in production mode

New functionality for running in production mode was introduced with SciNote version 1.10.0. In order to run SciNote application in production inside Docker you'll need the following:

• docker engine (version 1.12.0+),
• docker-compose (version 1.6.0+).

You'll also need to set environment variables in production.env file; variables are the same as described in Environmental variables section, the only differences are:

• format of records is changed - use KEY=VALUE record format;
• you should set DATABASE_URL=postgresql://postgres@db/scinote_production without quotation marks.

The mentioned variable is used to configure database connection and by default it contains credentials to connect to the PostgreSQL database inside db container; you will need to change this variable if you decide to use another DB or set password for default db user.

You can generate default (minimal) production.env file with the following command: make config-production. This command will also generate SECRET_KEY_BASE and PAPERCLIP_HASH_SECRET variables automatically.

After setting all the required variables you need to build the Docker image with make docker-production; this command will install all needed Gems and precompile assets.

When the above build is finished, database needs to be initialized (if you're performing a new install). This can be done by running make database-production. This will initialize the database and start a running process; the database will be hosted in the scinote_db_production container. This container is configured to keep all database files in the persistent Docker volume named scinote_production_postgres, which is (by default) placed in /var/lib/docker/volumes of the host system.

There is also another persistent Docker volume called scinote_production_files; this container is used for storing generated and uploaded files if you configure local file storage.

All these volumes will be kept safe in case you delete your Docker containers. Running docker rm with -v flag, however, will also delete these volumes (same thing happens if you run docker-compose down with -v flag).

Background jobs worker will be running in another separate container called scinote_jobs_production.

Now (finally), you can start SciNote with the following command: docker-compose -f ./docker-compose.production.yml up. Or you can use docker-compose -f ./docker-compose.production.yml up -d to start the server in background mode. Please consult docker-compose documentation for the rest of supported commands.

In short, the sequence of commands to setup SciNote (for fresh install) would be:

make config-production
make docker-production
make database-production

docker-compose -f ./docker-compose.production.yml up

Migrating to new production setup

If you are using some old/custom setup, and want to switch to production mode which was introduced in version 1.10.0 (see above), you will need to perform the following steps before updating the application files.

1. Migrate database data

You will need to migrate database data from old database to the new one running in scinote_db_production container. The easiest way to do this is to dump data from the old container and restore it into the new one. You can do this by using your preferred database client and login credentials from your config file. For example, you can do it inside the web container after entering shell with make cli and pg_dump or with any GUI tool (like pgAdmin). You can find the IP address of the local database container by running docker inspect and inspecting the output (in most cases, name of the database container will be similar to e.g. web_db_1).

Important! You should extract the old database dump before updating the source code tree of the application.

2. Migrate files

If you are using local file storage, you will also need to move user's files from ./public/system directory in application directory to the Docker volume scinote_production_files.

3. Migrate ENV variables

Don't forget to migrate ENV variables from config/application.yml into production.env. See previous section on rules for production.env.

4. Update source files

After all of the above steps are done, you can finally update application files and run DB migrations as described here.

Upgrading SciNote installation running in production mode

After downloading the new version of SciNote application files, the following needs to be done to upgrade a running SciNote instance running in production Docker mode.

1. Rebuild Docker images

First of all, you will need to rebuild Docker images using the new version of SciNote. That means that you need to stop the current instance (if it is running), and then run the command make docker-production.

2. Migrate database data

Open command prompt inside the web container with make cli-production and, once inside it, run migrations with the following command: rails db:migrate. On rare occasions, you will also need to run additional migration scripts, please check Release Notes for that.

3. Restart

After migrations are finished, you can start the application normally with the command docker-compose -f ./docker-compose.production.yml up.