5.5. Administrator manual for NextGIS GeoServices
5.5.1. Introduction
This manual describes the process of deploying NextGIS GeoServices sowftware on-premise. Mainly it uses Docker platform and docker-compose tool. All steps are performed on Linux-based OS.
5.5.2. Preparation
First you need to get source codes. The easiest way is to clone them from a git repository:
git clone --depth 1 https://gitlab.com/nextgis_private/geoservices.git
cd geoservices
Next build DBMS image with PostGIS support (name example: registry.nextgis.com/postgis:3.3.2):
docker build -t registry.nextgis.com/postgis:3.3.2 basemap
Next you need to prepare data for the basemap:
docker build -t prepare-data -f basemap/Dockerfile-prepare basemap
docker run -it --rm -v $(pwd)/basemap:/work prepare-data
Then build web application image (with a name like registry.nextgis.com/geoservices:2.5.0, for example):
docker build -t registry.nextgis.com/geoservices:2.5.0 .
5.5.3. Setting up
After all images are successfully built and data is prepared, modify docker-compose.yml:
Change image names to those set during building (tag ‘image’)
Change environment variable SESSION_KEY to a random text value (optional, if it is empty or not set, it generates automatically)
Change environment variables DB_PASSWORD and POSTGRES_PASSWORD to new password (value must be the same in all occurrences)
Change environment variable ADMIN_PASSWORD to new password
Change environment variables S3_ACCESS_KEY/MINIO_ACCESS_KEY and S3_SECRET_KEY/MINIO_SECRET_KEY to new passwords (values must be different for *_ACCESS_KEY and *_SECRET_KEY)
In the ‘redis’ launch command set the memory capacity (within limits available for the container, best set it 1-2 Gb lower than limit). Example:
nano docker-compose.yml
version: '3.7'
services:
app:
image: registry.nextgis.com/geoservices:2.5.0
depends_on:
- "postgis"
- "postgres"
- "redis"
- "s3"
environment:
SESSION_KEY: 5n3zczvhe3v0
DB_TYPE: postgres
DB_HOST: postgres
DB_PASSWORD: b0apciz6p3n9
REDIS_ENDPOINT: redis:6379
ADMIN_PASSWORD: admin
BM_DB_HOST: postgis
DEBUG: "false"
GIN_MODE: release
S3_ACCESS_KEY: 8lo5m0wcteuf
S3_SECRET_KEY: rro48pbjh6o8
S3_ENDPOINT: s3:9000
S3_SSL: "false"
S3_DEFAULT_STORAGE_CLASS: REDUCED_REDUNDANCY
S3_BUCKET_PREFIX: tiles
EXT_TMS_SUPPORT: "true"
volumes:
- data:/work
ports:
- 8088:8088
restart: always
postgres:
image: postgres:15-alpine
environment:
POSTGRES_PASSWORD: b0apciz6p3n9
POSTGRES_DB: geoservices
POSTGRES_USER: geoservices
volumes:
- postgres:/var/lib/postgresql/data
restart: always
redis:
image: redis:alpine
command: "redis-server --maxmemory 20Gb --maxmemory-policy allkeys-lru --appendonly no"
volumes:
- redis:/data
restart: always
postgis:
image: registry.nextgis.com/postgis:3.3.2
environment:
POSTGRES_PASSWORD: b0apciz6p3n9
POSTGRES_DB: basemap
POSTGRES_USER: geoservices
volumes:
- postgis:/var/lib/postgresql/data
restart: always
s3:
image: minio/minio
command: server /data
environment:
MINIO_ACCESS_KEY: 8lo5m0wcteuf
MINIO_SECRET_KEY: rro48pbjh6o8
MINIO_BROWSER: "false"
volumes:
- s3:/data
restart: always
volumes:
data: {}
postgres: {}
redis: {}
s3: {}
postgis: {}
If you need PKK data for integration with external geo services, then to the environment variables of the container ‘app’ add variable PKK_EXTERNAL_APIKEY with the API key of your profile on https://geoservices.nextgis.com.
For integration with NextGIS Web to the environment variables of the container ‘app’ add the following variables: NGW_URL, NGW_LOGIN, NGW_APIKEY.
NGW_URL - address of NextGIS Web server in ‘scheme-host-port’ format
NGW_LOGIN and NGW_APIKEY - username and password for NextGIS Web This user must have permission to read data that has to be cached in GeoServices.
5.5.4. Launch
To launch and check functionality of the stack, run the following code:
docker-compose up
To launch in service mode:
docker-compose up -d
After you launched it in browser open service address with port set to 8088. For example,
http://localhost:8088
5.5.5. Complete list of environment variables for NextGIS GeoServices
For each variable the table provides the following info: required or not, default value, short description.
Variable |
Required |
Default value |
Description |
---|---|---|---|
DEBUG |
no |
true |
Enable SQL debugging |
ADMIN_PASSWORD |
yes |
admin |
Pre-set administrator password |
SESSION_KEY |
no |
secret |
Session key - random text |
GIN_MODE |
no |
release |
Controls debugging of the gin library and web application diagnostic messages |
INCLUDE_ORIGIN_SUFFIXES |
no |
“nextgis.com”, “nextgis.ru” |
Origin array that is added to those specified in the API key |
TOKEN_CACHE_SIZE |
no |
1024 |
Max number of authorization tokens in cache |
TIMEOUT |
no |
180 |
Network request timeout |
FILE_TIMEOUT |
no |
1800 |
Timeout for file downloads |
SESSION_MAX_AGE |
no |
259200 |
How long a web application session lasts |
HTTP_SKIP_SSL_VERIFY |
no |
false |
Do not check https certificates |
LDAP_LOGIN |
no |
false |
Authentication via LDAP
Keep default
|
LDAP_TLS |
no |
no |
Use TLS |
LDAP_URL |
no |
“” |
LDAP server address |
LDAP_USER_FILTER |
no |
(objectClass=posixAccount) |
User search filter |
LDAP_USER_ATTR |
no |
uid |
User attribute |
LDAP_GROUP_FILTER |
no |
cn=geoservices |
Group search filter |
LDAP_GROUP_ATTR |
no |
memberUid |
Group attribute |
LDAP_DEFAULT_GROUP_ID |
no |
0 |
Default group for LDAP users - 0 group assignment disabled |
LDAP_UPDATE_GROUPS |
no |
false |
Update inclusion to groups for users |
OAUTH2_LOGIN |
no |
false |
Enable authentication via OAuth2 |
OAUTH2_CLIENT_ID |
no |
OAuth2 client ID |
|
OAUTH2_CLIENT_SECRET |
no |
OAuth2 client secret |
|
OAUTH2_REDIRECT_URI |
no |
OAuth2 redirect URI |
|
OAUTH2_ENDPOINT |
no |
Endpoint |
|
OAUTH2_SCOPE |
no |
user_info.read |
Scope |
OAUTH2_TYPE |
no |
1 |
Authorization type: 1 -NextGIS ID, 2 - Keycloak, 3 - custom, 4 - Blitz |
OAUTH2_TOKEN_ENDPOINT |
no |
Token endpoint |
|
OAUTH2_AUTH_ENDPOINT |
no |
Authorization endpoint |
|
OAUTH2_USERINFO_ENDPOINT |
no |
Endpoint for user info (not needed for JWT) |
|
OAUTH2_INTROSPECTION_ENDPOINT |
no |
Introspection endpoint |
|
OAUTH2_PROFILE_SUBJ_ATTR |
no |
nextgis_guid |
Field for getting user ID (subject) |
OAUTH2_PROFILE_KEYNAME_ATTR |
no |
username |
Field for getting username |
OAUTH2_PROFILE_FIRSTNAME_ATTR |
no |
first_name |
Field for user’s first name |
OAUTH2_PROFILE_LASTNAME_ATTR |
no |
last_name |
Field for user’s last name |
OAUTH2_USER_AUTOCREATE |
no |
true |
Creates user on first enter |
OAUTH2_VALIDATE_KEY |
no |
“” |
Key to verify JWT signature |
OAUTH2_CREATE_GROUPS |
no |
false |
Create groups based on user roles |
OAUTH2_UPDATE_GROUPS |
no |
false |
Update user inclusion into groups based on user roles |
OAUTH2_TOKEN_CACHE_TTL |
no |
3600 |
Default token lifetime unless another is not returned by server |
OAUTH2_LOGOUT_ENDPOINT |
no |
“” |
Logout endpoint |
OAUTH2_GROUPS_JWT_KEY |
no |
resource_access/{client_id}/roles |
Path for role/group search in JWT token |
LOCAL_LOGIN |
no |
true |
Allow local user accounts |
DEFAULT_LANGUAGE |
no |
en |
Default language |
LOG |
no |
false |
stdout messages in structured format |
LOG_ONLY_EDITS |
no |
false |
stdout only contains message on data modifications |
CLOUD_MODE |
no |
false |
Cloud launch mode |
MAX_AGE |
no |
43200 |
Time the tiles are stored in user’s browser - 12 hrs |
EXT_TMS_SUPPORT |
no |
false |
Enable external TMS service support |
no |
URL for integration with public cadaster map (PKK) |
||
PKK_EXTERNAL_APIKEY |
no |
“” |
APIKey for integration with PKK |
PKK_TILES_URL |
no |
“” |
URL of the local serveer for PKK integration |
PKK_FEATURES_URL |
no |
“” |
URL of the local serveer for PKK integration |
PKK_MIN_ZOOM |
no |
3 |
Min level of PKK tile zoom |
PKK_MAX_ZOOM |
no |
18 |
Max level of PKK tile zoom |
PKK_REGION |
no |
MULTIPOLYGON (((-168.4 84,-168.4 50,-179.999999 50,-179.9999999 84,-168.4 84)),
((130 40,130 84,179.999999 84,179.999999 40,130 40)),
((129.999999 84,129.999999 47,82.5 47,82.5 84,129.999999 84)),
((82.4999999 50,50 50,50 84,82.4999999 84,82.4999999 50)),
((20 84,49.999999 84,49.999999 40,20 40,20 84)))
|
Are for PKK tiles query |
DB_TYPE |
yes |
sqlite3 |
DB type - sqlite3, postgres, mysql |
DB_USER |
no |
geoservices |
User account used to access DB |
DB_PASSWORD |
yes |
DB password |
|
DB_HOST |
yes |
localhost |
DB address |
DB_PORT |
yes |
5432 |
DB port |
DB_NAME |
no |
geoservices |
DB name |
DB_MAXCONN |
no |
50 |
Max number of connections |
DB_MAXIDLECONN |
no |
10 |
Max number of idle connections |
DB_SSL_MODE |
no |
disable - I don’t care about security, and I don’t want to pay the overhead of encryption.
allow - I don’t care about security, but I will pay the overhead of encryption if the server insists on it.
prefer - I don’t care about encryption, but I wish to pay the overhead of encryption if the server supports it.
require - I want my data to be encrypted, and I accept the overhead. I trust that the network will make sure I always connect to the server I want.
verify-ca - I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server that I trust.
verify-full - I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server I trust, and that it’s the one I specify.
|
|
DB_SSL_CERT |
no |
Path to certificate file |
|
DB_SSL_KEY |
no |
Path to key file |
|
DB_SSL_ROOT_CERT |
no |
Path to root certificate |
|
REDIS_ENDPOINT |
yes |
localhost:6379 |
Redis service address |
REDIS_MAX_IDLE |
no |
100 |
Max time before pool connection is closed |
REDIS_MAX_ACTIVE |
no |
1000 |
Max number of active connections in the pool |
REDIS_IDLE_TIMEOUT |
no |
60 |
time before pool connection is closed |
REDIS_CLUSTER |
no |
false |
Connect to Redis cluster |
REDIS_NODES |
no |
“localhost:6379 localhost:7001 localhost:7002 localhost:7003 localhost:7004 localhost:7004” |
Redis cluster node (only used if REDIS_CLUSTER == true) |
REDIS_KEY_PREFIX |
no |
“” |
Prefix for Redis keys generated by the app |
REDIS_USER |
no |
geoservices |
Redis user login |
REDIS_DATABASE |
no |
0 |
Redis data base |
REDIS_SSL |
no |
false |
Connection using SSL/TLS |
REDIS_INSECURE_SSL |
no |
false |
Do not validate SSL/TLS |
S3_ACCESS_KEY |
yes |
Q3AM3UQ867SPQQA43P2F |
Access key for S3 |
S3_SECRET_KEY |
yes |
zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG |
Secret access key for S3 |
S3_ENDPOINT |
yes |
play.min.io |
S3 server address |
S3_SSL |
no |
true |
Use encryption |
S3_INSECURE_SSL |
no |
false |
Do not check SSL certificates |
S3_DEFAULT_STORAGE_CLASS |
no |
REDUCED_REDUNDANCY |
Storage method: REDUCED_REDUNDANCY or STANDARD |
S3_BUCKET_NAME |
no |
geoservices |
Bucket name |
S3_KEY_PREFIX |
no |
“” |
Prefix for S3 keys generated by the app |
S3_NO_OBJECT_TAGGING |
no |
false |
Do not dedupe or apply expiration time if S3 does not support tags |
RASTER_MAX_ZOOM |
no |
20 |
Max zoom for raster tiles |
VECTOR_MAX_ZOOM |
no |
14 |
Max zoom for vector tiles |
EXPIRE_TILES_MIN_ZOOM |
no |
7 |
Min zoom for tile expiration control |
EXPIRE_TILES_MAX_ZOOM |
no |
16 |
Max zoom for tile expiration control |
NET_MAX_RETRY_COUNT |
no |
5 |
Number of attempts for iterative queries |
LONG_REQUEST_MIN_TIME |
no |
0 |
Only log long queries - 0 disabled |
NGW_URL |
no |
Address of associated NextGIS Web (to create cache from basemaps) |
|
NGW_LOGIN |
no |
administrator |
Login for NextGIS Web - needed to render tile while seeding |
NGW_APIKEY |
no |
admin |
Password for NextGIS Web - needed to render tile while seeding |
NGW_FEATURE_LIMIT |
no |
256 |
Number of entries in page mode |
USERS_MAINTANCE_SCHEDULE |
no |
@every 9m1s |
Schedules user cache clearing |
SERVICE_MAINTANCE_SCHEDULE |
no |
@every 10m4s |
Schedules service cache clearing |
SERVICE_HOUSEKEEPING_SCHEDULE |
no |
@every 25h30m10s |
Schedules system clearing |
DATA_STORE |
no |
/data |
Path to data necessary for service functioning
Keep default
|
FILE_STORE |
no |
/work |
Path to the working directory. This is the folder for downloading files, performing operations, creating temporary files. |
BM_DB_HOST |
no |
localhost |
Host with PostGIS DB. Upon starting web application checks for DB connection and necessary extensions
If connection fails or extensions are not found, basemap section is disabled
|
BM_DB_PORT |
no |
5432 |
Port for PostGIS DB |
BM_DB_NAME |
no |
basemap |
DB name for OSM dump import |
BM_DB_USER |
no |
geoservices |
User account used to access basemap DB |
BM_DB_PASSWORD |
yes |
Password for basemap DB access |
|
BM_DB_SSL_MODE |
no |
disable - I don’t care about security, and I don’t want to pay the overhead of encryption.
allow - I don’t care about security, but I will pay the overhead of encryption if the server insists on it.
prefer - I don’t care about encryption, but I wish to pay the overhead of encryption if the server supports it.
require - I want my data to be encrypted, and I accept the overhead. I trust that the network will make sure I always connect to the server I want.
verify-ca - I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server that I trust.
verify-full - I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server I trust, and that it’s the one I specify.
|
|
BM_DB_SSL_CERT |
no |
Path to certificate file |
|
BM_DB_SSL_KEY |
no |
Path to key file |
|
BM_DB_SSL_ROOT_CERT |
no |
Path to root certificate |
|
BM_DB_PARALLEL_SQL |
no |
true |
Perform parallel DB queries for vector tiles |
BM_DIFF_URL |
no |
Address to download OSM delta files (only if EXT_SOURCES_SUPPORT == true) |
|
BM_EXPIRE_TILES_MIN_ZOOM |
no |
7 |
Min zoom to log invalid tiles |
BM_EXPIRE_TILES_MAX_ZOOM |
no |
16 |
Max zoom to log invalid tiles |
EXT_SOURCES_SUPPORT |
no |
false |
Allow/forbid getting files from Internet. For example, to initialize DB by downloading a dump from Internet or getting diff regularly.
Keep default
|
EXT_RASTER_RESAMPLING |
no |
bilinear |
Raster interpolation. Supported methods:
near: nearest neighbour resampling (default, fastest algorithm, worst interpolation quality).
bilinear: bilinear resampling.
cubic: cubic resampling.
cubicspline: cubic spline resampling.
lanczos: Lanczos windowed sinc resampling.
average: average resampling, computes the weighted average of all non-NODATA contributing pixels.
rms root mean square / quadratic mean of all non-NODATA contributing pixels (GDAL >= 3.3)
mode: mode resampling, selects the value which appears most often of all the sampled points.
In the case of ties, the first value identified as the mode will be selected.
max: maximum resampling, selects the maximum value from all non-NODATA contributing pixels.
min: minimum resampling, selects the minimum value from all non-NODATA contributing pixels.
med: median resampling, selects the median value of all non-NODATA contributing pixels.
q1: first quartile resampling, selects the first quartile value of all non-NODATA contributing pixels.
q3: third quartile resampling, selects the third quartile value of all non-NODATA contributing pixels.
sum: compute the weighted sum of all non-NODATA contributing pixels (since GDAL 3.1)
|
EXT_ZEROBLOCKHTTPCODES |
no |
“204,404” |
Codes of HTTP responses for white tiles |
LOCALES |
no |
“ru en” |
List of user interface languages |
OUTDATED_STAT_TABLE_ROWS |
no |
2*365*24*time.Hour |
Delete log entries from before 2 years |
ENABLE_SWAGGER |
no |
true |
Enable web interface for swagger |
SSL_CERT_FILE |
no |
To override path to certificate
You can also add certificates using following paths (depends on the platform):
“/etc/ssl/certs/ca-certificates.crt”,
// Debian/Ubuntu/Gentoo etc. “/etc/pki/tls/certs/ca-bundle.crt”,
// Fedora/RHEL 6 “/etc/ssl/ca-bundle.pem”,
// OpenSUSE “/etc/pki/tls/cacert.pem”,
// OpenELEC “/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem”,
// CentOS/RHEL 7 “/etc/ssl/cert.pem”,
// Alpine Linux
|
|
DEFAULT_KEY_EXPIRE |
no |
7 days |
TTL for tiles of external services |