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