Production mode - scinote-eln/scinote-web GitHub Wiki

Table of Contents

Introduction

SciNote can be run in production mode using Docker containers.

  • If setting up a new SciNote server, where SciNote version > 1.10.0, see this section;
  • if updating from an old version of SciNote (< 1.10.0), onto version > 1.10.0, see this section;
  • if updating SciNote version after 1.10.0, see this section.

Prerequisites

It is strongly suggested to first read Build & run section before setting up SciNote server in production mode, as various details about how SciNote is deployed (mainly about Docker containers) are explained there.

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 following 2 requirements are needed:

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

Step 1: Set environmental variables

Production mode SciNote server requires that the environment variables are specified in production.env file, located in the root application directory. Variables should follow the same requirements as specified in environmental variables section, the only two differences are:

  • format of entries in production.env file is different: use KEY=VALUE format;
  • DATABASE_URL=postgresql://postgres@db/scinote_production should be set without quotation marks.
  • [email protected], [email protected] might also have to be set without quotation marks.

The DATABASE_URL variable is used to configure database connection and by default it contains credentials to connect to the PostgreSQL database inside db container; if using some other database not inside default SciNote Docker container, or if password for default database user is changed, this variable should be updated accordingly.

Minimal default production.env file can be generated with the following command: make config-production. This command will also generate SECRET_KEY_BASE and PAPERCLIP_HASH_SECRET variables automatically.

Step 2: Build Docker images

After setting all the required variables in the production.env file, Docker images can be built. This can be done by running the command make docker-production; this command will install all required Gems, and precompile assets.

Step 3: Initialize database (when performing new install)

Once the above command finishes, database needs to be initialized (if you're performing a new install). This can be done by running make database-production. This command will initialize the database and start a running process.

Details: the database is 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.

Step 4: Start-up the server

To start SciNote server in production mode, invoke the following command:

  • docker-compose -f ./docker-compose.production.yml up
  • (or alternatively, 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.

Summary

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

make config-production
# (set env. variables)
make docker-production
make database-production

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

Docker containers breakdown

Production SciNote server is using the following containers to operate:

  • Persistent:
    • scinote_production_postgres hosts all database engine files, and is placed by default into /var/lib/docker/volumes folder on the host system;
    • scinote_production_files stores all generated & uploaded files when SciNote is configured to use local filesystem for storage (PAPERCLIP_STORAGE is set to 'filesystem');
  • Non-persistent:
    • scinote_db_production hosts the database engine process;
    • scinote_jobs_production hosts the background worker process;
    • scinote_web_production hosts the web application process.

All persistent volumes will be kept safe in case you delete your Docker containers.

WARNING! Running docker rm with -v flag, however, will also delete these volumes (same thing happens if you run docker-compose down with -v flag).

Migrating old versions of SciNote to production mode

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.

Updating 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.