From eea5c91636d03479120962ed616bc437d2ef6c7c Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Wed, 14 Oct 2026 13:49:55 +0200 Subject: [PATCH 01/12] Add 2026.10 EE upgrade guide, new env vars and custom email templates --- src/server/environment/index.md | 29 ++++++++++- src/server/install/index.md | 32 ++++++++++++ src/server/upgrade/index.md | 90 +++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-) diff --git a/src/server/environment/index.md b/src/server/environment/index.md index 31c35147..4e867a9f 100644 --- a/src/server/environment/index.md +++ b/src/server/environment/index.md @@ -35,6 +35,7 @@ Security settings are important for production use. | `SECURITY_EMAIL_SALT`⭐️| string | | Token salt for sending verification email, should be a generated strong string. | | `SECURITY_BEARER_SALT`⭐️| string | | Bearer token salt for decode web token, should be a generated strong string.| | `SECURITY_PASSWORD_SALT`⭐️| string | | Password salt for hashing, should be a generated strong string. | +| `SECURITY_UNLOCK_SALT`⭐️| string | | Token salt for unlocking user accounts locked after too many failed login attempts, should be a generated strong string. | | `WTF_CSRF_ENABLED` | Boolean | `true` | Enable CSRF protection. It is strongly recommended to have this on. | | `WTF_CSRF_TIME_LIMIT` | integer | `86400` | Lifetime of CSRF token in seconds. When expired, users need to refresh it. | ​ @@ -88,7 +89,13 @@ To ease the process of permission (user) management, you can set the following g | `MAIL_USE_TLS`🛡️ | Boolean | `true` | Use TLS encryption when connecting to SMTP server. | | `MAIL_USE_SSL`🛡️ | Boolean | `false` | Whether to use SSL encryption when connecting to SMTP server. | | `MAIL_BCC` | string | `None` | Email address to send copies of all sent emails. Should be system/application administrator. Mandatory in versions until 2024.4.0. | -| `MERGIN_LOGO_URL` | string | Mergin Maps logo | Link to logo in emails. | +| `MERGIN_LOGO_URL` | string | Mergin Maps logo | Link to the logo in emails and the web dashboard. | + + + +| Variable name | Type | Default | Description | +|-------------------------|---------|-----------|-------------| +| `EMAIL_TEMPLATES_DIR` | string | `None` | Directory with custom email templates (e.g. `/custom_templates`). Templates found there override the built-in ones, so their paths must match the built-in template paths exactly. If the directory does not exist, the server fails to start. See [custom email templates](../install/#custom-email-templates). | If you have issues with sending emails, follow [troubleshooting](../troubleshoot/) page. @@ -138,6 +145,15 @@ Mergin Maps is using Celery and Redis to perform asynchronous tasks or doing reg |`BROKER_URL` |string|`redis://merginmaps-redis:6379/0`| Connection details to celery message broker. If non-default, it should match definition in `docker-compose` file. | |`CELERY_RESULT_BACKEND`|string|`redis://merginmaps-redis:6379/0`| Connection details to celery result back-end broker. If non-default, it should match definition in `docker-compose` file. | +## Caching + + +The cache is stored in its own Redis database, separate from the one used by Celery, so cached data never mix with asynchronous task queues. + +| Variable name | Type | Default | Description | +|-----------------------|--------|----------|-------------| +| `REDIS_URL` | string | `redis://merginmaps-redis:6379/1` | Connection details to the Redis database used for caching. Use a different database number than in `BROKER_URL` and `CELERY_RESULT_BACKEND`. If non-default, it should match the definition in the `docker-compose` file. | + ## Diagnostic logs Users of Mergin Maps plugin and Mergin Maps mobile application are able to send diagnostic logs from their devices. In custom deployments, logs are stored in `diagnostic_logs` folder. If you want to send these logs to Mergin Maps instead of storing them locally, set the `DIAGNOSTIC_LOGS_URL` variable to `https://api.merginmaps.com/logs`. @@ -153,6 +169,10 @@ Users of Mergin Maps plugin and Mergin Maps mobile application are able to send | `MAPS_ENABLED` | boolean | `true` | Flag to enable webmaps | | `VECTOR_TILES_URL` | string | `https://tiles-ee.merginmaps.com/data/default/{z}/{x}/{y}.pbf` | Vector tiles URL used as background map layer in webmaps | | `VECTOR_TILES_STYLE_URL` | string | `https://tiles-ee.merginmaps.com/styles/default.json` | Vector tiles style URL used to style the background map layer in webmaps | +| `VECTOR_TILES_LIGHT_STYLE_URL` | string | `https://tiles-ee.merginmaps.com/styles/light.json` | Vector tiles style URL for the light alternative of the background map in webmaps | +| `VECTOR_TILES_DARK_STYLE_URL` | string | `https://tiles-ee.merginmaps.com/styles/dark.json` | Vector tiles style URL for the dark alternative of the background map in webmaps | +| `OGC_API_ENABLED` | boolean | `true` | Flag to enable generating OGC API links for projects. | +| `MAPS_SHARING_ENABLED` | boolean | `true` | Flag to enable sharing of webmaps with a public link. | ## Single Sign-On (SSO) @@ -162,3 +182,10 @@ Users of Mergin Maps plugin and Mergin Maps mobile application are able to send | `SSO_ENABLED` | boolean | `false` | Flag to enable SSO in | | `SSO_SERVER_URL` ⭐️ | string | `http://localhost:8081` | Public URL of the SSO server. This URL should be accessible from the internet. | | `SSO_SERVER_API_KEY` ⭐️ | string | `` | This API key is used to authenticate requests to the SSO service. It must be one of the keys defined in the `JACKSON_API_KEYS` variable within the Ory Polis (for more details see [Single Sign-On deployment guide](../sso-deployment#configure-server)). | + +## Audit logs + + +| Variable name | Type | Default | Description | +|--------------------------|----------|-------------------------------|--------------------------------| +| `AUDIT_LOGS_ENABLED` | boolean | `true` | Flag to enable the collection of audit logs. If set to `false`, audit events are not stored. | diff --git a/src/server/install/index.md b/src/server/install/index.md index f91788e5..3718fa4c 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -140,6 +140,38 @@ $ docker exec merginmaps-server flask user create --is-adm ``` ::: +### Custom email templates + + +To use your own email templates, set the `EMAIL_TEMPLATES_DIR` [environment variable](../environment/#sending-emails) to a folder with your templates and mount that folder to the `server`, `celery-worker` and `celery-beat` services in `docker-compose.yml`: + +```yaml +volumes: + - ./custom_templates:/custom_templates +``` + +```shell +EMAIL_TEMPLATES_DIR=/custom_templates +``` + +Templates in this folder override the built-in ones, so their paths (relative to the folder) must match the paths below: + +| Template path | Email | +|-------------------------------------------|-----------------------------------------------------------| +| `email/components/base.html` | Common layout of all emails (logo, header, footer) | +| `email/user_created.html` | New user account created by an administrator | +| `email/email_confirmation.html` | Email address confirmation (resent from user profile) | +| `email/password_reset.html` | Password reset | +| `email/account_locked.html` | Account locked after too many failed login attempts | +| `email/project_access_request.html` | Request for access to a project, sent to project owners | +| `workspace/invitation.html` | Invitation to a workspace | +| `workspace/project_transfer_request.html` | Request to transfer a project to another workspace | +| `workspace/user_registration.html` | Email address confirmation after user self-registration | + +::: warning +If `EMAIL_TEMPLATES_DIR` is set to a directory that does not exist in the container, the server fails to start. Make sure the folder is mounted to all services that use the `.prod.env` file. +::: + ## Test deployment In order to test your deployment there are some utility commands to perform basic checks. diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index 06ee7f43..6974ff27 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -14,6 +14,96 @@ Make sure to always back up your database data before doing a migration. [[toc]] +## From 2025.7.x to 2026.10.x {#migration-guide-from-2025-7-x-to-2026-10-x} + + + +Perform the migration: + +1. Stop your running docker containers + ```bash + $ docker compose -f docker-compose.yml down # or similarly, based on your previous deployment + ``` +2. Clone or pull the or download and open the `/enterprise` folder. + ```bash + $ cd server/deployment/enterprise + ``` +3. Adapt your existing `docker-compose.yml` and `docker-compose.maps.yml` (if your server has maps enabled) files to the new version. + + - Bump images to the latest version in `docker-compose.yml`. + - Bump images of `qgis` and `qgis-extractor` to the latest 2026.4.0 image tag in `docker-compose.maps.yml`. + - Add new environment variables to the `mergin-qgis` container in `docker-compose.maps.yml`: + ```bash + - QGIS_SERVER_SERVICE_URL=http://localhost:5555 + - QGIS_SERVER_API_WFS3_ROOT_PATH=/wfs3 + ``` +4. Double-check that the following environment variable is available and filled in the `.prod.env` environment file. If not, add it. + ```bash + # Generate a hash string using the following command (or similar): + # LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32; echo + # Add the content to the .prod.env file + SECURITY_UNLOCK_SALT='' + ``` +5. This version of the server provides audit logs. To enable or disable the collection of audit logs, use the following variable in the `.prod.env` environment file. + ```bash + AUDIT_LOGS_ENABLED=True # False to disable + ``` +6. This version of the server supports [caching](../environment/#caching) in a separate Redis database. Double-check that the following environment variable is available and filled in the `.prod.env` environment file. If not, add it. + ```bash + REDIS_URL=redis://merginmaps-redis:6379/1 + ``` +7. Double-check that the following maps-related environment variables are available and filled in the `.prod.env` environment file. If not, add them with the proper values. + ```bash + # Enable/disable generating OGC API links for projects + OGC_API_ENABLED=True # False to disable + # Enable/disable map sharing for projects + MAPS_SHARING_ENABLED=True # False to disable + # Support for multiple background map alternatives + VECTOR_TILES_LIGHT_STYLE_URL=https://tiles-ee.merginmaps.com/styles/light.json + VECTOR_TILES_DARK_STYLE_URL=https://tiles-ee.merginmaps.com/styles/dark.json + ``` +8. Change your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : + ```bash + location ^~ /maps/embed/ { + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Host $http_host; + proxy_redirect off; + proxy_pass http://app_server; + + proxy_hide_header X-Frame-Options; + proxy_hide_header Content-Security-Policy; + add_header Content-Security-Policy "frame-ancestors *;" always; + } + ``` + + - If you have enabled OGC API with the `OGC_API_ENABLED` variable and want to integrate it with other web clients, allow CORS for the `/v2/ogc` endpoint in your proxy. An example is in the related section of . + +9. Start up your docker containers + ```bash + $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment + $ docker compose -f docker-compose.maps.yml -d up # when maps are enabled + ``` +10. Check that you are on the correct database migration versions (`c40e5e645b57`, `b9ec9ab6694f`). + ```bash + $ docker exec merginmaps-server flask db current + INFO [alembic.runtime.migration] Context impl PostgresqlImpl. + INFO [alembic.runtime.migration] Will assume transactional DDL. + c40e5e645b57 + b9ec9ab6694f + ``` + - If you do not see the version numbers at all, run the following commands: + ```bash + $ docker exec merginmaps-server flask db stamp c40e5e645b57 + $ docker exec merginmaps-server flask db stamp b9ec9ab6694f + ``` +11. Run the database migration: + + ```bash + $ docker exec merginmaps-server flask db upgrade community@d8a2f6c1e5b4 + $ docker exec merginmaps-server flask db upgrade enterprise@93f85f6c45fa + ``` + ## From 2025.5.x to 2025.7.x {#migration-guide-from-2025-5-x-to-2025-7-x} From 89b22052858d25796f6a8481b9b08d844e1c9718 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Wed, 14 Oct 2026 14:05:15 +0200 Subject: [PATCH 02/12] Add upgrade to postgres 17 section --- src/server/upgrade/index.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index 6974ff27..2b5fda73 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -30,8 +30,13 @@ Perform the migration: ``` 3. Adapt your existing `docker-compose.yml` and `docker-compose.maps.yml` (if your server has maps enabled) files to the new version. - - Bump images to the latest version in `docker-compose.yml`. - - Bump images of `qgis` and `qgis-extractor` to the latest 2026.4.0 image tag in `docker-compose.maps.yml`. + - Upgrade image tag in server related container to the latest version in `docker-compose.yml`. + - Upgrade `mergin-db` container to tag 17. Server is supporting also older versions, but we are recommending upgrade to `postgres:17` + ```bash + db: + image: postgres:17 + ``` + - Upgrade image tags of `qgis` and `qgis-extractor` to the latest 2026.4.0 image tag in `docker-compose.maps.yml`. - Add new environment variables to the `mergin-qgis` container in `docker-compose.maps.yml`: ```bash - QGIS_SERVER_SERVICE_URL=http://localhost:5555 From 31ffe2cb262883b04e71e89fc9c9e6a66f9a2528 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Wed, 14 Oct 2026 15:54:44 +0200 Subject: [PATCH 03/12] Added alembic migration removal --- src/server/upgrade/index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index 2b5fda73..547e8a75 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -89,7 +89,11 @@ Perform the migration: $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment $ docker compose -f docker-compose.maps.yml -d up # when maps are enabled ``` -10. Check that you are on the correct database migration versions (`c40e5e645b57`, `b9ec9ab6694f`). +10. This release of the Mergin Maps server removes a redundant database migration. If your database still references it, remove the reference directly from the `alembic_version` table, either with `psql` or in your favourite PostgreSQL client: + ```bash + $ docker exec merginmaps-db psql -U postgres -c "DELETE FROM alembic_version WHERE version_num='35af0c8be41e';" + ``` +11. Check that you are on the correct database migration versions (`c40e5e645b57`, `b9ec9ab6694f`). ```bash $ docker exec merginmaps-server flask db current INFO [alembic.runtime.migration] Context impl PostgresqlImpl. @@ -102,7 +106,7 @@ Perform the migration: $ docker exec merginmaps-server flask db stamp c40e5e645b57 $ docker exec merginmaps-server flask db stamp b9ec9ab6694f ``` -11. Run the database migration: +12. Run the database migration: ```bash $ docker exec merginmaps-server flask db upgrade community@d8a2f6c1e5b4 From 0c9917f145ae09fb7ed7a0d8333f69f71a46aba3 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Mon, 19 Oct 2026 12:15:39 +0200 Subject: [PATCH 04/12] Address comments @varmar05 --- src/server/environment/index.md | 8 +++--- src/server/upgrade/index.md | 43 +++++++++++++++++++-------------- 2 files changed, 29 insertions(+), 22 deletions(-) diff --git a/src/server/environment/index.md b/src/server/environment/index.md index 4e867a9f..4df4f440 100644 --- a/src/server/environment/index.md +++ b/src/server/environment/index.md @@ -167,10 +167,10 @@ Users of Mergin Maps plugin and Mergin Maps mobile application are able to send | Variable name | Type | Default | Description | |--------------------------|----------|-------------------------------|--------------------------------| | `MAPS_ENABLED` | boolean | `true` | Flag to enable webmaps | -| `VECTOR_TILES_URL` | string | `https://tiles-ee.merginmaps.com/data/default/{z}/{x}/{y}.pbf` | Vector tiles URL used as background map layer in webmaps | -| `VECTOR_TILES_STYLE_URL` | string | `https://tiles-ee.merginmaps.com/styles/default.json` | Vector tiles style URL used to style the background map layer in webmaps | -| `VECTOR_TILES_LIGHT_STYLE_URL` | string | `https://tiles-ee.merginmaps.com/styles/light.json` | Vector tiles style URL for the light alternative of the background map in webmaps | -| `VECTOR_TILES_DARK_STYLE_URL` | string | `https://tiles-ee.merginmaps.com/styles/dark.json` | Vector tiles style URL for the dark alternative of the background map in webmaps | +| `VECTOR_TILES_URL` | string | `https://tiles.merginmaps.com/data/default/{z}/{x}/{y}.pbf` | Vector tiles URL used as background map layer in webmaps | +| `VECTOR_TILES_STYLE_URL` | string | `https://tiles.merginmaps.com/styles/default.json` | Vector tiles style URL used to style the background map layer in webmaps | +| `VECTOR_TILES_LIGHT_STYLE_URL` | string | `https://tiles.merginmaps.com/styles/light.json` | Vector tiles style URL for the light alternative of the background map in webmaps | +| `VECTOR_TILES_DARK_STYLE_URL` | string | `https://tiles.merginmaps.com/styles/dark.json` | Vector tiles style URL for the dark alternative of the background map in webmaps | | `OGC_API_ENABLED` | boolean | `true` | Flag to enable generating OGC API links for projects. | | `MAPS_SHARING_ENABLED` | boolean | `true` | Flag to enable sharing of webmaps with a public link. | diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index 547e8a75..f5351e20 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -28,36 +28,39 @@ Perform the migration: ```bash $ cd server/deployment/enterprise ``` -3. Adapt your existing `docker-compose.yml` and `docker-compose.maps.yml` (if your server has maps enabled) files to the new version. - - - Upgrade image tag in server related container to the latest version in `docker-compose.yml`. - - Upgrade `mergin-db` container to tag 17. Server is supporting also older versions, but we are recommending upgrade to `postgres:17` +3. Upgrade PostgreSQL to version 17. + - If you are going to upgrade PostgreSQL, make sure you back up your database before proceeding. + - Upgrade the `mergin-db` container to PostgreSQL version 17. The server also supports older versions, but we recommend upgrading to `postgres:17`. ```bash db: image: postgres:17 ``` - - Upgrade image tags of `qgis` and `qgis-extractor` to the latest 2026.4.0 image tag in `docker-compose.maps.yml`. + +4. Adapt your existing `docker-compose.yml` and `docker-compose.maps.yml` (if your server has maps enabled) files to the new version. + + - Upgrade the image tags of the server-related containers to the latest version in `docker-compose.yml`. + - Upgrade the image tags of `qgis` and `qgis-extractor` to the latest 2026.4.0 image tag in `docker-compose.maps.yml`. - Add new environment variables to the `mergin-qgis` container in `docker-compose.maps.yml`: ```bash - QGIS_SERVER_SERVICE_URL=http://localhost:5555 - QGIS_SERVER_API_WFS3_ROOT_PATH=/wfs3 ``` -4. Double-check that the following environment variable is available and filled in the `.prod.env` environment file. If not, add it. +5. Double-check that the following environment variable is available and filled in the `.prod.env` environment file. If not, add it. ```bash # Generate a hash string using the following command (or similar): # LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32; echo # Add the content to the .prod.env file SECURITY_UNLOCK_SALT='' ``` -5. This version of the server provides audit logs. To enable or disable the collection of audit logs, use the following variable in the `.prod.env` environment file. +6. This version of the server provides audit logs. To enable or disable the collection of audit logs, use the following variable in the `.prod.env` environment file. ```bash AUDIT_LOGS_ENABLED=True # False to disable ``` -6. This version of the server supports [caching](../environment/#caching) in a separate Redis database. Double-check that the following environment variable is available and filled in the `.prod.env` environment file. If not, add it. +7. This version of the server supports [caching](../environment/#caching) in a separate Redis database. Double-check that the following environment variable is available and filled in the `.prod.env` environment file. If not, add it. ```bash REDIS_URL=redis://merginmaps-redis:6379/1 ``` -7. Double-check that the following maps-related environment variables are available and filled in the `.prod.env` environment file. If not, add them with the proper values. +8. Double-check that the following maps-related environment variables are available and filled in the `.prod.env` environment file. If not, add them with the proper values. ```bash # Enable/disable generating OGC API links for projects OGC_API_ENABLED=True # False to disable @@ -67,7 +70,7 @@ Perform the migration: VECTOR_TILES_LIGHT_STYLE_URL=https://tiles-ee.merginmaps.com/styles/light.json VECTOR_TILES_DARK_STYLE_URL=https://tiles-ee.merginmaps.com/styles/dark.json ``` -8. Change your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : +9. Update your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : ```bash location ^~ /maps/embed/ { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -84,16 +87,16 @@ Perform the migration: - If you have enabled OGC API with the `OGC_API_ENABLED` variable and want to integrate it with other web clients, allow CORS for the `/v2/ogc` endpoint in your proxy. An example is in the related section of . -9. Start up your docker containers - ```bash +10. Start up your docker containers + ```bash $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment $ docker compose -f docker-compose.maps.yml -d up # when maps are enabled - ``` -10. This release of the Mergin Maps server removes a redundant database migration. If your database still references it, remove the reference directly from the `alembic_version` table, either with `psql` or in your favourite PostgreSQL client: + ``` +11. This release of the Mergin Maps server removes a redundant database migration. If your database still references it, remove the reference directly from the `alembic_version` table, either with `psql` or in your favourite PostgreSQL client: ```bash $ docker exec merginmaps-db psql -U postgres -c "DELETE FROM alembic_version WHERE version_num='35af0c8be41e';" ``` -11. Check that you are on the correct database migration versions (`c40e5e645b57`, `b9ec9ab6694f`). +12. Check that you are on the correct database migration versions (`c40e5e645b57`, `b9ec9ab6694f`). ```bash $ docker exec merginmaps-server flask db current INFO [alembic.runtime.migration] Context impl PostgresqlImpl. @@ -106,13 +109,17 @@ Perform the migration: $ docker exec merginmaps-server flask db stamp c40e5e645b57 $ docker exec merginmaps-server flask db stamp b9ec9ab6694f ``` -12. Run the database migration: +13. Run the database migration: ```bash - $ docker exec merginmaps-server flask db upgrade community@d8a2f6c1e5b4 - $ docker exec merginmaps-server flask db upgrade enterprise@93f85f6c45fa + $ docker exec merginmaps-server flask db upgrade community@heads + $ docker exec merginmaps-server flask db upgrade enterprise@heads ``` + ::: tip New database schema + This will create a new database schema `audit`. If the application connects to the database as a different PostgreSQL user (not the owner of the tables), you will need to grant this user `USAGE` on the new schema and `SELECT` on its tables. Do not forget to also grant `EXECUTE` on the functions `ensure_log_partitions(integer)` and `before_insert_log()`. + ::: + ## From 2025.5.x to 2025.7.x {#migration-guide-from-2025-5-x-to-2025-7-x} From 8133bd1e389088ce67f31f1e53d764208bd89d2d Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Fri, 23 Oct 2026 11:10:20 +0200 Subject: [PATCH 05/12] Add more optional to step 9 and some grammar issues --- src/server/environment/index.md | 4 ++-- src/server/install/index.md | 2 +- src/server/upgrade/index.md | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/server/environment/index.md b/src/server/environment/index.md index 4df4f440..dedb88c9 100644 --- a/src/server/environment/index.md +++ b/src/server/environment/index.md @@ -148,11 +148,11 @@ Mergin Maps is using Celery and Redis to perform asynchronous tasks or doing reg ## Caching -The cache is stored in its own Redis database, separate from the one used by Celery, so cached data never mix with asynchronous task queues. +The cache is stored in its own Redis database, separate from the one used by Celery, so cached data is never mixed with asynchronous task queues. | Variable name | Type | Default | Description | |-----------------------|--------|----------|-------------| -| `REDIS_URL` | string | `redis://merginmaps-redis:6379/1` | Connection details to the Redis database used for caching. Use a different database number than in `BROKER_URL` and `CELERY_RESULT_BACKEND`. If non-default, it should match the definition in the `docker-compose` file. | +| `REDIS_URL` | string | `redis://merginmaps-redis:6379/1` | Connection details to the Redis database used for caching. Use a different database number from the one in `BROKER_URL` and `CELERY_RESULT_BACKEND`. If non-default, it should match the definition in the `docker-compose` file. | ## Diagnostic logs Users of Mergin Maps plugin and Mergin Maps mobile application are able to send diagnostic logs from their devices. In custom deployments, logs are stored in `diagnostic_logs` folder. If you want to send these logs to Mergin Maps instead of storing them locally, set the `DIAGNOSTIC_LOGS_URL` variable to `https://api.merginmaps.com/logs`. diff --git a/src/server/install/index.md b/src/server/install/index.md index 3718fa4c..358a2ae0 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -160,7 +160,7 @@ Templates in this folder override the built-in ones, so their paths (relative to |-------------------------------------------|-----------------------------------------------------------| | `email/components/base.html` | Common layout of all emails (logo, header, footer) | | `email/user_created.html` | New user account created by an administrator | -| `email/email_confirmation.html` | Email address confirmation (resent from user profile) | +| `email/email_confirmation.html` | Email address confirmation (resent from the user profile) | | `email/password_reset.html` | Password reset | | `email/account_locked.html` | Account locked after too many failed login attempts | | `email/project_access_request.html` | Request for access to a project, sent to project owners | diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index f5351e20..ac9e02ee 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -24,7 +24,7 @@ Perform the migration: ```bash $ docker compose -f docker-compose.yml down # or similarly, based on your previous deployment ``` -2. Clone or pull the or download and open the `/enterprise` folder. +2. Clone or pull the or download the and open the `/enterprise` folder. ```bash $ cd server/deployment/enterprise ``` @@ -67,10 +67,10 @@ Perform the migration: # Enable/disable map sharing for projects MAPS_SHARING_ENABLED=True # False to disable # Support for multiple background map alternatives - VECTOR_TILES_LIGHT_STYLE_URL=https://tiles-ee.merginmaps.com/styles/light.json - VECTOR_TILES_DARK_STYLE_URL=https://tiles-ee.merginmaps.com/styles/dark.json + VECTOR_TILES_LIGHT_STYLE_URL=https://tiles.merginmaps.com/styles/light.json + VECTOR_TILES_DARK_STYLE_URL=https://tiles.merginmaps.com/styles/dark.json ``` -9. Update your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : +9. If you are using any top proxy settings and maps are enabled in your server, pay attention to update your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : ```bash location ^~ /maps/embed/ { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -85,7 +85,7 @@ Perform the migration: } ``` - - If you have enabled OGC API with the `OGC_API_ENABLED` variable and want to integrate it with other web clients, allow CORS for the `/v2/ogc` endpoint in your proxy. An example is in the related section of . + - If you have enabled OGC API with the `OGC_API_ENABLED` variable and want to integrate it with other web clients, allow CORS for the `/v2/ogc` endpoint in your proxy. An example can be found in the related section of . 10. Start up your docker containers ```bash From 3b585b23f42d5201d8d3b1ab3eb2e8f2802009df Mon Sep 17 00:00:00 2001 From: Marcel Kocisek Date: Fri, 23 Oct 2026 12:08:40 +0200 Subject: [PATCH 06/12] Update src/server/upgrade/index.md Co-authored-by: Alexandra Bucha Rasova <94905350+alex-cit@users.noreply.github.com> --- src/server/upgrade/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index ac9e02ee..58a46d42 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -92,7 +92,7 @@ Perform the migration: $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment $ docker compose -f docker-compose.maps.yml -d up # when maps are enabled ``` -11. This release of the Mergin Maps server removes a redundant database migration. If your database still references it, remove the reference directly from the `alembic_version` table, either with `psql` or in your favourite PostgreSQL client: +11. This release of the server removes a redundant database migration. If your database still references it, remove the reference directly from the `alembic_version` table, either with `psql` or in your favourite PostgreSQL client: ```bash $ docker exec merginmaps-db psql -U postgres -c "DELETE FROM alembic_version WHERE version_num='35af0c8be41e';" ``` From 84c5c9683f5e174a1a86b38eb16e8cec8f22b1a0 Mon Sep 17 00:00:00 2001 From: Marcel Kocisek Date: Fri, 23 Oct 2026 12:08:51 +0200 Subject: [PATCH 07/12] Update src/server/environment/index.md Co-authored-by: Alexandra Bucha Rasova <94905350+alex-cit@users.noreply.github.com> --- src/server/environment/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/server/environment/index.md b/src/server/environment/index.md index dedb88c9..76faa872 100644 --- a/src/server/environment/index.md +++ b/src/server/environment/index.md @@ -89,7 +89,7 @@ To ease the process of permission (user) management, you can set the following g | `MAIL_USE_TLS`🛡️ | Boolean | `true` | Use TLS encryption when connecting to SMTP server. | | `MAIL_USE_SSL`🛡️ | Boolean | `false` | Whether to use SSL encryption when connecting to SMTP server. | | `MAIL_BCC` | string | `None` | Email address to send copies of all sent emails. Should be system/application administrator. Mandatory in versions until 2024.4.0. | -| `MERGIN_LOGO_URL` | string | Mergin Maps logo | Link to the logo in emails and the web dashboard. | +| `MERGIN_LOGO_URL` | string | logo | Link to the logo in emails and the web dashboard. | From 0238f8bd256704116a68bcca8e09618003f11836 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Thu, 29 Oct 2026 10:18:45 +0100 Subject: [PATCH 08/12] Fix merginmaps-db --- src/server/upgrade/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index 58a46d42..b864bf06 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -30,7 +30,7 @@ Perform the migration: ``` 3. Upgrade PostgreSQL to version 17. - If you are going to upgrade PostgreSQL, make sure you back up your database before proceeding. - - Upgrade the `mergin-db` container to PostgreSQL version 17. The server also supports older versions, but we recommend upgrading to `postgres:17`. + - Upgrade the `merginmaps-db` container to PostgreSQL version 17. The server also supports older versions, but we recommend upgrading to `postgres:17`. ```bash db: image: postgres:17 @@ -696,7 +696,7 @@ In case you do not need your previous data, we advise to start with [clean deplo 3. Backup your database ⚠️ ```bash -$ docker exec mergin-db pg_dump -U postgres -Fc postgres > pg_backup.dump +$ docker exec merginmaps-db pg_dump -U postgres -Fc postgres > pg_backup.dump ``` 4. Stop all running services (from project root folder) From 74942658fe0d21a9e6cebf4415604a961f33baa9 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Thu, 29 Oct 2026 10:19:55 +0100 Subject: [PATCH 09/12] Fix heads -> head --- src/server/upgrade/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index b864bf06..058b4957 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -112,8 +112,8 @@ Perform the migration: 13. Run the database migration: ```bash - $ docker exec merginmaps-server flask db upgrade community@heads - $ docker exec merginmaps-server flask db upgrade enterprise@heads + $ docker exec merginmaps-server flask db upgrade community@head + $ docker exec merginmaps-server flask db upgrade enterprise@head ``` ::: tip New database schema From 3b92a77c704476cde83ab1dfffaee779417001ab Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Thu, 29 Oct 2026 10:23:06 +0100 Subject: [PATCH 10/12] up -d --- src/server/upgrade/index.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index 058b4957..e23e8ca6 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -89,8 +89,8 @@ Perform the migration: 10. Start up your docker containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment - $ docker compose -f docker-compose.maps.yml -d up # when maps are enabled + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment + $ docker compose -f docker-compose.maps.yml up -d # when maps are enabled ``` 11. This release of the server removes a redundant database migration. If your database still references it, remove the reference directly from the `alembic_version` table, either with `psql` or in your favourite PostgreSQL client: ```bash @@ -160,8 +160,8 @@ You can also clean the following variables from `.prod.env`: 6. Start up your docker containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment - $ docker compose -f docker-compose.maps.yml -d up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment + $ docker compose -f docker-compose.maps.yml up -d # or similarly, based on your deployment ``` 7. Check that you are on correct database migration versions (`6cb54659c1de`, `e95d051969ce`). ```bash @@ -250,7 +250,7 @@ Perform the migration: You can also disable this persistence in `server` service definition. 6. Start up your docker containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment ``` 7. Check that you are on correct database migration versions (`ba5051218de4`). ```bash @@ -295,7 +295,7 @@ Perform the migration: You can also disable this persistence in `server` service definition. 6. Start up your docker containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment ``` 7. Check that you are on correct database migration versions (`5ad13be6f7ef`, `819e6b20ee93`). ```bash @@ -352,8 +352,8 @@ Perform the migration: ``` 4. Start up your docker containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment - $ docker compose -f docker-compose.maps.yml -d up # If you want to deploy webmaps stack + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment + $ docker compose -f docker-compose.maps.yml up -d # If you want to deploy webmaps stack ``` 5. Check that you are on correct versions (`ba5051218de4`, `ba5ae5972c4a`). ```bash @@ -412,7 +412,7 @@ Perform the migration: - After this you can start the new containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment ``` 4. Check that you are on correct versions (`35af0c8be41e`, `a5d4defded55`). @@ -470,7 +470,7 @@ Perform the migration: - After this you can start the new containers ```bash - $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up -d # or similarly, based on your deployment ``` 4. Check that you are on correct versions (`07f2185e2428`, `df5b4efdae7b`). From 38fabdcb84ce231758176830e3ce9743de34ffd1 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Thu, 29 Oct 2026 10:56:04 +0100 Subject: [PATCH 11/12] Finalize --- src/server/upgrade/index.md | 47 +++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index e23e8ca6..247e4b9f 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -18,28 +18,49 @@ Make sure to always back up your database data before doing a migration. +Mergin Maps EE Docker images are now available in a private Docker Hub repository. Previous versions were also available in the Amazon ECR registry, but images starting with version `2026.10.1` are no longer published there. If you do not have access to the Docker Hub repository, contact [support](https://support.merginmaps.com/new-ticket). + Perform the migration: -1. Stop your running docker containers +1. Upgrade PostgreSQL to version 17. + - If you are going to upgrade PostgreSQL, make sure you back up your database before proceeding. + + ```bash + # Stop services so they do not handle any traffic + docker compose stop server celery-beat celery-worker web proxy + # Dump the existing database + docker exec merginmaps-db pg_dump -U postgres -Fc postgres > mergin-pg14.dump + + # Stop all services + docker compose -f docker-compose.yml down + + # Move the data directory to a PostgreSQL 14 backup folder + mv mergin-db-enterprise mergin-db-enterprise-pg14 + + # Change version of db container to Postgres 17 in docker compose file + #db: + # image: postgres:17 + + # Start the database container + docker compose -f docker-compose.yml up -d db + # Restore your data to the new PostgreSQL 17 database + docker exec -i merginmaps-db pg_restore -U postgres -d postgres < mergin-pg14.dump + ``` + +2. Stop your running docker containers ```bash $ docker compose -f docker-compose.yml down # or similarly, based on your previous deployment ``` -2. Clone or pull the or download the and open the `/enterprise` folder. +3. Clone or pull the or download the and open the `/enterprise` folder. ```bash $ cd server/deployment/enterprise ``` -3. Upgrade PostgreSQL to version 17. - - If you are going to upgrade PostgreSQL, make sure you back up your database before proceeding. - - Upgrade the `merginmaps-db` container to PostgreSQL version 17. The server also supports older versions, but we recommend upgrading to `postgres:17`. - ```bash - db: - image: postgres:17 - ``` + 4. Adapt your existing `docker-compose.yml` and `docker-compose.maps.yml` (if your server has maps enabled) files to the new version. - - Upgrade the image tags of the server-related containers to the latest version in `docker-compose.yml`. - - Upgrade the image tags of `qgis` and `qgis-extractor` to the latest 2026.4.0 image tag in `docker-compose.maps.yml`. + - Upgrade the image tags of the server-related containers to the latest version tag `2026.10.1` in `docker-compose.yml`. + - Upgrade the image tags of `qgis` to the `2026.4.0` image tag and `qgis-extractor` to the `2026.4.1` image tag in `docker-compose.maps.yml`. - Add new environment variables to the `mergin-qgis` container in `docker-compose.maps.yml`: ```bash - QGIS_SERVER_SERVICE_URL=http://localhost:5555 @@ -60,7 +81,7 @@ Perform the migration: ```bash REDIS_URL=redis://merginmaps-redis:6379/1 ``` -8. Double-check that the following maps-related environment variables are available and filled in the `.prod.env` environment file. If not, add them with the proper values. +8. Double-check that the following maps-related environment variables are available and filled in the `.prod.env` environment file. If not, add them with the proper values. ```bash # Enable/disable generating OGC API links for projects OGC_API_ENABLED=True # False to disable @@ -70,7 +91,7 @@ Perform the migration: VECTOR_TILES_LIGHT_STYLE_URL=https://tiles.merginmaps.com/styles/light.json VECTOR_TILES_DARK_STYLE_URL=https://tiles.merginmaps.com/styles/dark.json ``` -9. If you are using any top proxy settings and maps are enabled in your server, pay attention to update your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : +9. If you are using any top proxy settings and maps are enabled in your server, pay attention to update your proxy settings to allow embedding of maps by changing the `Content-Security-Policy` header for the `/maps/embed` path. Add the following lines to : ```bash location ^~ /maps/embed/ { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; From 121399e1f3bbaf1b5cb7cf596a0a9731aabdc7c0 Mon Sep 17 00:00:00 2001 From: MarcelGeo Date: Thu, 29 Oct 2026 11:34:20 +0100 Subject: [PATCH 12/12] Ignore cors --- scripts/wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/wordlist.txt b/scripts/wordlist.txt index eebf15e5..d4aded24 100644 --- a/scripts/wordlist.txt +++ b/scripts/wordlist.txt @@ -22,6 +22,7 @@ CPUs Consulting's CRS CSRF +CORS CSV CharlieColleague DAF