scinote-eln/scinote-web
1
1
Fork 0
mirror of https://github.com/scinote-eln/scinote-web.git synced 2025-09-06 21:24:23 +08:00
Code Issues Projects Releases Packages Wiki Activity

Updated Setup guide (markdown)

Luka Murn 2018-06-02 11:04:19 +02:00
parent a1055ee1f2
commit 9611bbf099
1 changed files with 1 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
Setup-guide.md

@ -8,81 +8,7 @@ SciNote is configured using environmental variables. To see list of available va
## 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](../Environmental-variables), 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:
```bash
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](#user-content-running-server-in-production-mode) 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).
### 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`.
To run SciNote in production mode (in Docker containers), visit the [Production mode](Production-mode) section.
## Rake tasks