Skip to content

Setup guide

Jump to bottom
Luka Murn edited this page Jun 2, 2018 · 84 revisions

Build & run

For instructions on how to build & run SciNote - including minimal quick-start setup - visit Build & run section.

Environmental variables

SciNote is configured using environmental variables. To see list of available variables, and a minimal application.yml file, visit Environmental variables section.

Production mode (in 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.

Rake tasks

Delayed jobs

SciNote uses delayed jobs library to do background processing, mostly for the following tasks:

  • Sending emails,
  • Extracting text from uploaded files (full-text search),
  • Generating introduction tutorials,
  • Copying/cloning large database objects,
  • etc.

Best option to run delayed jobs is inside a worker process. To start a background worker process that will execute delayed jobs, run the following command:

rails jobs:work

To clear all currently queued jobs, you can use the following command:

rails jobs:clear

Warning! This is not advised to do on production environments.

Adding users

To simplify adding of new users to the system, couple of special rails tasks have been created.

The first, rails db:add_user simply queries all the information for a specific user via STDIN, and then proceeds to create the user.

The second task, rails db:load_users[file_path,create_orgs] takes 2 parameters as an input:

  • Path to .yml file containing list of users & teams to be added. The YAML file needs to be structured properly - field names must match those in the database, users need to have a name user_<id>, and teams name team_<id>. For an example load users file, see db/load_users_template.yml file.
  • A boolean ('true' or 'false') whether to create individual teams for each user or not.

Web statistics

To check current login statistics of registered users, use rails web_stats:login task. To check the last login of any user to the system, use rails web_stats:last_login task.

Clearing data

Execute rails data:clean_temp_files to remove all temporary files. Temporary files are used when importing samples. Execute rails data:clean_unconfirmed_users to remove all users that registered, but never confirmed their email. Calling rails data:clean will execute both above tasks.

Notifications

To generate a new system notification that will be sent to all SciNote users, execute rails notifications:new_system[title, message]. Title & message can contain HTML tags.

Mailer

SciNote needs a configured SMTP mail server to work properly. See environmental variables for configuration of the mailer.

Office Online integration

SciNote can be integrated with an Office Online Server to enable viewing and edition of documents directly in the browser. To enable this integration using the Microsoft Office Online servers, you will need to join the Office Cloud Storage Partner Program and set up the WOPI_* environment variables.

Deploy onto Heroku

Before deploying to Heroku, install heroku client as describe on offical website. To use existing heroku application, add new git remote repository.

git remote add heroku [email protected]:my-random-app-name.git

Or create new heroku application by executing following command.

heroku create

Add additional heroku buildpacks in the same order as specified in .buildpacks:

heroku buildpacks:add --index <i> <buildpack>

e.g. for adding graphviz write:

heroku buildpacks:add --index 2 https://github.com/weibeld/heroku-buildpack-graphviz.git

Before pushing to heroku master branch, some environmental variables should be set.

Heroku environmental variables

For deployment of SciNote onto Heroku, additional environmental variables need to be specified.

Variable Mandatory Description
LANG Yes The default localization language (e.g. en_US.UTF-8).
RAILS_ENV Yes Rails environment: production, test or development.
RACK_ENV Yes Rack environment: production, test or development.
RAILS_SERVE_STATIC_FILES Yes Whether to serve static files. Must be set to enabled.
WEB_CONCURRENCY Yes The concurrency of the server. See Heroku specifications for details.
MAX_THREADS Yes The max. number of threads. See Heroku specifications for details.
PORT Yes The port on which the application should run. See Heroku specifications for details.
RAILS_FORCE_SSL Yes If set to 1, enforce SSL communication on all levels of application.
DATABASE_URL Yes Full URL for connecting to PostgreSQL database.

Testing

In current version, only model tests are implemented for SciNote. To execute them, call rails test:models.

Home

Clone this wiki locally