22.2. Deployment from pre-build images¶
22.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.
22.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/.
You can sign in to Web GIS with default login administrator and password
admin. Do not forget to change default password in control panel.
22.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
22.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
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
22.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:~$
Примечание
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
22.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:
Примечание
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