18.2. Deployment from pre-build images

18.2.1. Requirements

  • Docker Engine >= 19.03

  • Docker Compose >= 1.14

You also need pre-build docker images. Usualy URLs for pre-build images look like: registry.example.com/some-path/service:version-additional-flags. Authorization in docker registry (via docker login registry.example.com) may be required.

18.2.2. Setup

On docker host create working directory (/srv/ngwdocker for example).

$ mkdir /srv/ngwdocker
$ cd /srv/ngwdocker

To store backups directly on docker host (instead of docker volume) also create backup directory:

$ mkdir /srv/ngwdocker/backup

Create docker-compose.yaml using following example or file from your image provider:

version: '3.7'
services:
  app:
    image: registry.example.com/some-path/app:1-py2
    restart: unless-stopped
    volumes:
    - {type: volume, source: data_app, target: /opt/ngw/data/app}
    - {type: volume, source: config_app, target: /opt/ngw/config/app}
    - {type: volume, source: secret, target: /opt/ngw/secret}
    # To use docker host directory as backup storage (recomended):
    - {type: bind, source: ./backup, target: /opt/ngw/backup}
    # To use docker volume as backup storage uncomment following line:
    # - {type: volume, source: backup, target: /opt/ngw/backup}
    ports:
    # Bind directly to default HTTP port 80. If this port is busy,
    # then you can use another, for example 8080.
    - 80:8080
    depends_on:
    - postgres
  postgres:
    image: registry.example.com/some-path/postgres:1-py2-postgres10-postgis25
    restart: unless-stopped
    volumes:
    - {type: volume, source: data_postgres, target: /opt/ngw/data/postgres}
    - {type: volume, source: config_postgres, target: /opt/ngw/config/postgres}
    - {type: volume, source: secret, target: /opt/ngw/secret}
  archivist:
    image: registry.example.com/some-path/archivist:1-py2
    restart: unless-stopped
    volumes:
    - {type: volume, source: data_app, target: /opt/ngw/data/app}
    - {type: volume, source: data_postgres, target: /opt/ngw/data/postgres}
    - {type: volume, source: config_app, target: /opt/ngw/config/app}
    - {type: volume, source: config_postgres, target: /opt/ngw/config/postgres}
    - {type: volume, source: secret, target: /opt/ngw/secret}
    # To use docker host directory as backup storage (recomended):
    - {type: bind, source: ./backup, target: /opt/ngw/backup}
    # To use docker volume as backup storage uncomment following line:
    # - {type: volume, source: backup, target: /opt/ngw/backup}
volumes:
  data_app: {}
  data_postgres: {}
  config_app: {}
  config_postgres: {}
  secret: {}
  # To use docker volume as backup storage uncomment following line:
  # backup: {}

After than run following command to pull images, create and start containers:

$ docker-compose up -d

Wait some time and check logs with docker-compose logs to see progress. After process completed you can access your web gis at: http://localhost/ or http://hostname/.

../../_images/login.png

You can sign in to Web GIS with default login administrator and password admin. Do not forget to change default password in control panel.

18.2.3. Backup and maintenance

To run weekly backup weekly and maintenance create file cronjob with following contents and set executable flag on it.

$ cat <<EOF > cronjob
#!/bin/bash
set -ex
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
docker-compose exec -T --env NGWDOCKER_INITIALIZE_DB=no \
    app /opt/ngw/bin/docker-entrypoint \
    bash -c "nextgisweb backup && nextgisweb maintenance"
EOF
$ chmod +x cronjob

This script starts nextgisweb online backup and then maintenance task. For more info about backup and maintenance see relevant sections in this documentation.

Now add this script to run every sunday on 02:00 via cron and then restart it:

$ cat <<EOF > /etc/cron.d/ngwdocker
0 2 * * 0 root cd /srv/ngwdocker && ./cronjob
EOF
$ systemctl restart cron

18.2.4. Configuration

The easiest way to configure NextGIS Web is through environment variables. Refer to NextGIS Web configuration docs and add variables to app environment section. And update the stack via docker-compose up -d when finished.

Available variables can be listed by running docker-compose run --rm app nextgisweb-config --env-vars.

Configuration files are stored in config_app volume, which is mounted at /opt/ngw/config/app in app container. For example, NextGIS Web config.ini can be edited by:

$ docker-compose run --rm app nano config/app/config.ini

Don’t forget to restart the stack after modifications:

$ docker-compose down && docker-compose up -d

18.2.4.1. Additional fonts

QGIS renderer uses system fonts in app container. Some basic fonts are already installed, additional fonts can be placed into font directory in config_app volume. It corresponds to /opt/ngw/config/app/font directory inside app container. Thus, you can copy fonts with docker cp:

$ docker-compose ps
Name                    Command     State   Ports
----------------------------------------------------------------
ngwdocker_app_1         /opt/ ...   Up      0.0.0.0:80->8080/tcp
ngwdocker_archivist_1   /opt/ ...   Up
ngwdocker_postgres_1    /opt/ ...   Up      5432/tcp
$ docker cp /path/to/some-font.ttf ngwdocker_app_1:/opt/ngw/config/app/font/
$ docker-compose down && docker-compose up -d

Having copied font files, existing fonts can be listed by running fc-list command:

$ docker-compose exec app fc-list | grep some-font
/opt/ngw/config/app/font/some-font.ttf: Some Font:style=Regular

18.2.5. Upgrade

Step 1: Stop all services and make the backup using archivist tool.

$ docker-compose stop
$ docker-compose run --rm archivist backup

Additional information about backup and can be found in “Backup and restore” section below.

Step 2: Create the backup of docker-compose.yaml and update image tags there. For example, replace registry.example.com/some-path/app:1.1.0 with registry.example.com/some-path/app:1.2.0.

Step 3: Apply migrations using the NextGIS Web migration instructions. Shell access to the application container can be achieved with the following command:

$ docker-compose run --rm app bash
ngw@4409295bba0a:~$

Note

The version of NextGIS Web core package (nextgisweb) and extensions packages (nextgisweb_*) don’t match Docker images versions.

Stage 4: Start all services:

$ docker-compose up -d

18.2.6. PostgreSQL cluster recreation

To recreate PostgreSQL cluster, for example, in case of changing LC_COLLATION and LC_CTYPE default options, use the following steps:

Step 1: Stop all services and make the backup using archivist tool.

$ docker-compose down
$ docker-compose run --rm archivist backup

Step 2: Start postgres service, wait until it’s started, and create PostgreSQL dump:

$ docker-compose up -d postgres
$ docker-compose exec postgres bin/postgres-dump

Step 3: Ensure that archivist (archivist-YYYYMMDD-hhmmss.tar.zst) and postgres (postgres-YYYYMMDD-hhmmss.sql) backups has been created in backup directory (or in the corresponding Docker volume).

Step 4: Delete PostgreSQL data volume, and start postgres service:

Note

The actual name of PostgreSQL data volume depends on Docker Compose’s project name and its location. The example below assumes that the default location (/srv/ngwdocker) is used and Docker Compose’s project name wasn’t set. In other circumstances, it may be different.

$ docker-compose down
$ docker volume rm ngwdocker_data_postgres
$ docker-compose up -d postgres

Step 5: Restore the dump and start the rest of the stack:

$ docker-compose exec postgres bin/postgres-restore
$ docker-compose up -d