Mergin Maps

Appearance

Upgrade ​

Migration guides are here to help you migrate your Mergin Maps CE or Mergin Maps EE to the latest server version. Mergin Maps Cloud is always migrated to latest version by Mergin Maps team. Read more about server platforms in overview article.

WARNING

Migrations must be performed one by one and cannot be skipped.

Make sure to always back up your database data before doing a migration.

From 2025.5.x to 2025.7.x ​

Enterprise Edition

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 server repository or download deployment folder and open /enterprise folder.
    bash
     $ cd server/deployment/enterprise
  3. Adapt your existing docker-compose.yml and docker-compose.maps.yml file to the new version.
  4. If you have installed maps stack, change qgis_extractor service image version to 2025.3.0 in docker-compose.maps.yml.

Version breaking change

Previously used image version for service qgis_extractor (2025.1.0) is not compatible with latest version of Mergin Maps server.

  1. If you have installed maps stack, add new environment variables to qgis_extractor service in docker-compose.maps.yaml.
yaml
environment:
    - OVERVIEWS_DATA_DIR=/data
    - MM_WMS_TILE_BUFFER=100
    - MM_WMS_AVOID_ARTIFACTS=1
    - BROKER_URL=redis://mergin-redis:6379/0
    - CELERY_RESULT_BACKEND=redis://mergin-redis:6379/0

You can also clean the following variables from .prod.env:

bash
QGIS_EXTRACTOR_TIMEOUT
QGIS_EXTRACTOR_API_URL

  1. Start up your docker containers

    bash
     $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment

  2. Check that you are on correct database migration versions (6cb54659c1de, e95d051969ce).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
6cb54659c1de
e95d051969ce
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 6cb54659c1de
$ docker exec merginmaps-server flask db stamp e95d051969ce

  3. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade community@b9ec9ab6694f
$ docker exec merginmaps-server flask db upgrade enterprise@c40e5e645b57

From 2025.2.x to 2025.7.x (CE) ​

Community Edition

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 server repository or download deployment folder and open /community folder.
    bash
     $ cd server/deployment/community
  3. Adapt your existing docker-compose.yml and .prod.env environment variables to the new version.
  4. Upgrade your nginx proxy configuration file with the latest version available in the nginx.conf (This is a necessary step for improved downloading of zip files from the dashboard).
  5. If you want to persist diagnostic logs from a mobile application and QGIS plugin, run the following command to set proper permissions for the folder /diagnostic_logs used for storing log files:
    bash
    $ sh ../common/set_permissions.sh diagnostic_logs

You can also disable this persistence in docker-compose.yml server service definition. 6. Start up your docker containers

bash
 $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment

  1. Check that you are on correct database migration versions (ba5051218de4).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
35af0c8be41e (head)
ba5051218de4
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 35af0c8be41e
$ docker exec merginmaps-server flask db stamp ba5051218de4

  2. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade heads    
# New head will be community@b9ec9ab6694f

From 2025.3.x to 2025.5.x ​

Enterprise Edition

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. Please clone or pull the server repository or download deployment folder
    bash
     $ cd server/deployment/enterprise
  3. Adapt your existing docker-compose.yml file to the new version.
  4. Upgrade your nginx proxy configuration file with the latest version available in the nginx.conf (This is a necessary step for improved downloading of zip files from the dashboard).
  5. If you want to persist diagnostic logs from a mobile application and QGIS plugin, run the following command to set proper permissions for the folder /diagnostic_logs used for storing log files:
    bash
    $ sh ../common/set_permissions.sh diagnostic_logs

You can also disable this persistence in docker-compose.yml server service definition. 6. Start up your docker containers

bash
 $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment

  1. Check that you are on correct database migration versions (5ad13be6f7ef, 819e6b20ee93).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
5ad13be6f7ef
819e6b20ee93
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 5ad13be6f7ef
$ docker exec merginmaps-server flask db stamp 819e6b20ee93

  2. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade community@6cb54659c1de
$ docker exec merginmaps-server flask db upgrade enterprise@e95d051969ce

Downloading zip files from the dashboard

Zip files are now stored in temporary storage and are deleted after 7 days. This can increase the storage usage of Mergin Maps server. Make sure you have enough space on your server.

Enable Single Sign-On ​

To enable Single Sign-On for your server, follow the instructions in Deployment of Single Sign On.

From 2025.2.x to 2025.3.x ​

Enterprise Edition

Changes on deployment behaviour

Release 2025.3.x brings some changes on Mergin Maps docker compose orchestration deployment procedure.

Get the latest docker-compose file or update docker images manually to version 2025.3.0. Perform the migration:

  1. Stop your running docker containers

    bash
     $ docker compose -f docker-compose.yml down # or similarly, based on your previous deployment
 # INFO: After shutdown update the docker-compose.yml file to latest release

  2. Please clone the server repository or download deployment folder

    bash
     $ cd server/deployment/enterprise

  3. If you plan to use the new webmaps stacks, adapt your existing .prod.env and docker-compose.yml files. Move/copy them to the enterprise deployment folder

    bash
     $ cp /some/path/.prod.env . # assuming you are located in `server/deployment/enterprise`
 $ cp /some/path/docker-compose.yml . # assuming you are located in `server/deployment/enterprise`

  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

  5. Check that you are on correct versions (ba5051218de4, ba5ae5972c4a).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
ba5051218de4
ba5ae5972c4a
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp ba5051218de4
$ docker exec merginmaps-server flask db stamp ba5ae5972c4a

  6. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade community@5ad13be6f7ef
$ docker exec merginmaps-server flask db upgrade enterprise@819e6b20ee93

🗺️ Enable background map ⚠️

Your webmaps won’t display the default background map unless we enable them on our side. To do that, please contact our support team and share your server’s URL.

Alternatively, you can set up your own background map using environment variables.

From 2024.2.x to 2025.2.x (CE) ​

Before you upgrade!

Release 2025.2.x brings significant changes on Mergin Maps docker compose orchestration infrastructure.

Previous individual server container is replaced by 3 service dedicated containers that split the core components of Mergin Maps, server-gunicorn the app, celery-beat Celery task scheduler and celery-worker a dedicated worker container for Celery tasks.

Community Edition

Get the latest docker-compose file or update docker images manually to version 2025.2.2. Perform the migration:

  1. Stop your running docker containers

    bash
    $ docker compose -f docker-compose.yml down # or similarly, based on your deployment
# INFO: After shutdown update the docker-compose.yml file to latest release

  2. Double check if below environment variables are available and filled in .prod.env environment file. If not, add them.

    bash
    SECURITY_EMAIL_SALT='<YOUR STRONG HASH>'
SECURITY_BEARER_SALT='<YOUR STRONG HASH>'
PORT=5000

  3. Start up your docker containers

    • If you stopped the containers during step 1 with new version compose file, you need to manually stop and remove containers.
    bash
    $ docker stop merginmaps-db merginmaps-proxy merginmaps-redis merginmaps-server merginmaps-web
$ docker rm merginmaps-db merginmaps-proxy merginmaps-redis merginmaps-server merginmaps-web
    • After this you can start the new containers
    bash
    $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment

  4. Check that you are on correct versions (35af0c8be41e, a5d4defded55).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
35af0c8be41e (head)
a5d4defded55
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 35af0c8be41e
$ docker exec merginmaps-server flask db stamp a5d4defded55

  5. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade heads

From 2024.4.x to 2025.2.x ​

Before you upgrade!

Release 2025.2.x brings significant changes on Mergin Maps docker compose orchestration infrastructure.

Previous individual server container is replaced by 3 service dedicated containers that split the core components of Mergin Maps, server-gunicorn the app, celery-beat Celery task scheduler and celery-worker a dedicated worker container for Celery tasks.

Enterprise Edition

Get the latest docker-compose file or update docker images manually to version 2025.2.0. Perform the migration:

  1. Stop your running docker containers and build the new images

    bash
    $ docker compose -f docker-compose.yml down # or similarly, based on your deployment
# INFO: After shutdown update the docker-compose.yml file to latest release

  2. Double check if below environment variables are available and filled in .prod.env environment file. If not, add them.

    bash
    SECURITY_EMAIL_SALT='<YOUR STRONG HASH>'
SECURITY_BEARER_SALT='<YOUR STRONG HASH>'
PORT=5000

  3. Start up your docker containers

    • If you stopped the containers during step 1 with new version compose file, you need to manually stop and remove containers.
    bash
    $ docker stop merginmaps-db merginmaps-proxy merginmaps-redis merginmaps-server merginmaps-web
$ docker rm merginmaps-db merginmaps-proxy merginmaps-redis merginmaps-server merginmaps-web
    • After this you can start the new containers
    bash
    $ docker compose -f docker-compose.yml -d up # or similarly, based on your deployment

  4. Check that you are on correct versions (07f2185e2428, df5b4efdae7b).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
07f2185e2428
df5b4efdae7b
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 07f2185e2428
$ docker exec merginmaps-server flask db stamp df5b4efdae7b

  5. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade community@ba5051218de4
$ docker exec merginmaps-server flask db upgrade enterprise@ba5ae5972c4a

From 2024.3.x to 2024.4.x ​

Get the latest docker-compose file or update docker images manually to version 2024.4.0. Perform the migration:

Enterprise Edition

  1. Start up your docker containers

    bash
    $ docker compose -f docker-compose.yml up # or similarly, based on your deployment

  2. Check that you are on correct versions (0e3fc92aeaaa, 223e3be99e92).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
0e3fc92aeaaa
223e3be99e92
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 0e3fc92aeaaa
$ docker exec merginmaps-server flask db stamp 223e3be99e92

  3. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade community@07f2185e2428
$ docker exec merginmaps-server flask db upgrade enterprise@df5b4efdae7b

From 2024.2.x to 2024.3.x ​

Get the latest docker-compose file or update docker images manually to version 2024.3.0. Perform the migration:

Enterprise Edition

  1. Start up your docker containers

    bash
    $ docker compose -f docker-compose.yml up # or similarly, based on your deployment

  2. Check that you are on correct versions (a5d4defded55, 223e3be99e92).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
a5d4defded55
223e3be99e92 (head)
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp a5d4defded55
$ docker exec merginmaps-server flask db stamp 223e3be99e92

  3. Run the database migration:

    bash
    $ docker exec merginmaps-server flask db upgrade community@0e3fc92aeaaa

From 2023.6.1 to 2024.2.x (CE) ​

Get the latest docker-compose file or update docker images manually.

Community Edition

Update image to 2024.2.2 and perform the migration:

  1. Start up your docker containers

    bash
    $ docker compose -f docker-compose.yml up # or similarly, based on your deployment

  2. Check that you are on correct versions (35af0c8be41e, 3a77058a2fd7).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
3a77058a2fd7
35af0c8be41e
    • If you do not see the version numbers at all, run the following commands:
    bash
    $ docker exec merginmaps-server flask db stamp 35af0c8be41e
$ docker exec merginmaps-server flask db stamp 3a77058a2fd7

  3. Run the database migration, there will be several updates:

    bash
    $ docker exec merginmaps-server flask db upgrade heads
Enterprise Edition

Update image to 2024.2.1 and perform the migration:

  1. Start up your docker containers

    bash
    $ docker compose -f docker-compose.yml up # or similarly, based on your deployment

  2. Check that you are on correct versions (3a77058a2fd7, 0d867687ab64).

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
3a77058a2fd7
0d867687ab64
    • If you do not see the version numbers at all, run the following command:
    bash
    $ docker exec merginmaps-server flask db stamp 3a77058a2fd7
$ docker exec merginmaps-server flask db stamp 0d867687ab64

  3. Run the database migration, there will be several updates running in each script:

    bash
    $ docker exec merginmaps-server flask db upgrade community@a5d4defded55
$ docker exec merginmaps-server flask db upgrade enterprise@head

From 2023.2.0+ to 2023.6.1 ​

⚠️ If you are on a server version lower than 2023.2.0, it is important to first upgrade to 2023.2.0 before continuing with this migration.

Get the latest docker-compose file or update docker images manually to version 2023.6.1. Perform the migration:

Community Edition

  1. Start up your docker containers

    bash
    $ docker compose -f docker-compose.yml up # or similarly, based on your deployment

  2. Check that you are on a correct version (b6cb0a98ce20)

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
b6cb0a98ce20 # <--- important
    • If you do not see the version number on the last line, run the following command:
    bash
    $ docker exec merginmaps-server flask db stamp b6cb0a98ce20

  3. Run the database migration

    bash
    $ docker exec merginmaps-server flask db upgrade 3a77058a2fd7
Enterprise Edition

  1. Start up your docker containers

    bash
    $ docker compose -f docker-compose.yml up # or similarly, based on your deployment

  2. Check that you are on correct versions (b6cb0a98ce20, 0d867687ab64)

    bash
    $ docker exec merginmaps-server flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
b6cb0a98ce20
0d867687ab64
    • If you do not see the version numbers, run the following command:
    bash
    $ docker exec merginmaps-server flask db stamp b6cb0a98ce20
$ docker exec merginmaps-server flask db stamp 0d867687ab64

  3. Run the database migration

    bash
    $ docker exec merginmaps-server flask db upgrade community@3a77058a2fd7

Any previous version to 2023.2.0 ​

Besides various fixes, enhancements and performance improvements the most notable change recently introduced is the concept of workspaces. For Community Edition it means there is a common shared workspace (global workspace) for all users where all projects are stored, instead of having a personal or organisational namespace for projects.

TIP

In case you do not need your previous data, we advise to start with clean deployment without the need to follow this migration guide.

Upgrading to 2023.2

  1. Synchronise all your projects and devices using Mergin Maps mobile app and Mergin Maps QGIS plugin. Make sure there are no pending changes.

  2. After synchronisation, all downloaded projects need to be removed from all devices using Mergin Maps mobile app and Mergin Maps QGIS plugin

  3. Backup your database ⚠️

bash
$ docker exec mergin-db pg_dump -U postgres -Fc postgres > pg_backup.dump
  1. Stop all running Mergin Maps services (from project root folder)
bash
$ docker compose -f docker-compose.yml stop
  1. Pull the latest changes
bash
$ git pull
  1. Set environment variables .prod.env. Important ⚠️
Community Edition

As mentioned earlier, Mergin Maps CE operates with one global workspace. We will set it up now. Specify its name with the following environment variable:

  • GLOBAL_WORKSPACE=ShinyWorkspace - name of your workspace. A good fit is the name of your company or team. This value should not be changed later.

TIP

You can find all available environment variables here together with a tutorial on how to set them up.

Further, you need to set a default role for people in your workspace (learn more about our permissions and roles system here). Pick one of these options :

  • GLOBAL_READ=0 everyone will have guest role (without access to any project unless explicitly granted)
  • GLOBAL_READ=1 everyone will have reader role (they can read/download all projects in the workspace)
  • GLOBAL_WRITE=1 everyone will have writer role (they can contribute to all projects in the workspace, e.g. upload files)
  • GLOBAL_ADMIN=1 everyone will have admin role (they can create new projects and share projects with others)

You can specify the maximum storage for your shiny new workspace 🌟 with the following variable:

  • GLOBAL_STORAGE=10737418240 - workspace storage in bytes (10 GB in the example)

TIP

New users can be created from Mergin Maps administration panel, by navigating to <your_url>/admin.

Enterprise Edition

There are few settings you may want to change values for:

  • WORKSPACE_STORAGE_SIZE=104857600 - workspace storage in bytes (100 MB in the example)
  • WORKSPACE_INVITATION_EXPIRATION=7 - days for valid invitation to expire
  • WORKSPACE_EXPIRATION=7 - days for deleted workspace to be cleaned up
  • USER_WORKSPACES_ALLOWED=1 - whether users can create their own workspaces
  • USER_SELF_REGISTRATION=1 - whether users can register themselves, if set to 0, new users can be only added by admin
  1. Make sure projects volume mounts in docker-compose file still match (You can set up new volumes by following the quick start guide). Switch to new server version and PostgreSQL to at least version 12 (14 recommended) by running new docker containers:
bash
$ docker compose -f docker-compose.yml up
  1. Restore backup from older PostgreSQL version, e.g.:
bash
$ docker cp pg_backup.dump merginmaps-db:/tmp
$ docker exec -it merginmaps-db bash
root@merginmaps-db$ pg_restore -U postgres -Fc -d postgres < /tmp/pg_backup.dump

You might see some warnings about using public schema, you can safely ignore those.

WARNING

If your PostgreSQL settings were custom, you might need to follow official instructions for upgrading the PostgreSQL cluster.

Database migration ​

Community Edition

In this step we will select a global workspace (e.g. my-company) where all your projects will be merged. Your projects are migrated as follows: former namespace is prepended to project name and whole project is moved to new global workspace, for example:

john.doe/survey -> my-company/john.doe_survey
my-org/projectA -> my-company/my-org_projectA

Run DB migration scripts in merginmaps-server container:

bash
$ docker exec -it merginmaps-server bash

# stamp database to state of release 2021.6.1, 
# if there is existing alembic record you might need to patch it manually 
$ flask db stamp 2686074eff45 # ← state of 2021.6.1
$ flask db upgrade dbd428cda965 # sync with pre-2023 releases
$ flask db upgrade 0ab6a1fbf974

$ echo $GLOBAL_WORKSPACE # make sure the GLOBAL_WORKSPACE variable is set and has the desired value

$ flask db upgrade 35af0c8be41e
$ flask db upgrade 1fcbea2a0f2c
$ flask db upgrade 3daefa84ce67
$ flask db upgrade b6cb0a98ce20

If all goes well your database should end up in the following state

bash
$ flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
b6cb0a98ce20 (head)
35af0c8be41e (head)
Enterprise Edition

In this step all your user and organisation namespaces will be migrated to workspaces keeping their original names. From now on there won't be any difference between user and organisation namespace.

Run DB migration scripts in merginmaps-server container:

bash
$ docker exec -it merginmaps-server bash

# stamp database to state of release 2021.6.1, 
# if there is existing alembic record you might need to patch it manually 
$ flask db stamp 2686074eff45 # ← state of 2021.6.1
$ flask db stamp f2f038cbae06 # ← state of 2021.6.1 (enterprise branch)
$ flask db upgrade community@dbd428cda965  # sync with pre-2023 releases

# run bunch of workspace related updates
$ flask db upgrade community@0ab6a1fbf974 
$ flask db upgrade enterprise@92a63acb7973
$ flask db upgrade community@1fcbea2a0f2c
$ flask db upgrade community@3daefa84ce67
$ flask db upgrade community@b6cb0a98ce20
$ flask db upgrade enterprise@0d867687ab64

If all goes well your database should end up in the following state

bash
$ flask db current
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
0d867687ab64 (head)
b6cb0a98ce20 (head)

Your should be successfully migrated. Please note that files on your disk were not touched, only project names (namespaces) were changed.

You can now download and continue working with your projects.