Install

Installation guide will help you to install your Mergin Maps CE or Mergin Maps EE to the latest server version. Mergin Maps Cloud is always up-to-date and managed by Mergin Maps team. Read more about server platforms in overview article.

• Installation System Requirements
  • Infrastructure overview
  • Firewall ports
• Mergin Maps CE Docker Images
• Mergin Maps EE Docker Images
• Deployment
  • Setup environment
  • Start docker containers
  • Initialise database
• Test deployment

Installation System Requirements

For a typical deployment, we recommend using a dedicated host machine with 8 GB of memory and 2 vCPUS (similar to AWS t3a.large instances). The requirements for CPU and persistent storage depend largely on the frequency of project updates and the anticipated size of the data you expect to store respectively. A very conservative rule of thumb, regarding needed disk size would be mergin maps project size * number of versions. If you have a team size over 25 people and synchronise often your Mergin Maps projects, consider a host with 4 vCPUS.

On OS level, we recommend to use a Linux distribution that has full compatibility with Docker, since Mergin Maps is deployed by default with docker compose.

A low-latency, high-bandwidth environment is preferred due to the volume of data needed to perform synchronisation with Mergin Maps. This is especially important on large projects with hundreds of megabytes in between syncs.

Infrastructure overview

• PostgreSQL - Database that holds application data. Can be external and therefore excluded from install orchestration with proper configuration.
• Redis - The caching and asynchronous task engine running on top of Mergin Maps
• Celery-Beat - The Celery task orchestrator used by Mergin Maps
• Celery-Worker - The Celery container responsible for workers that perform tasks on Mergin Maps
• Server - The server backend instance of Mergin Maps
• Web - The frontend instance for Mergin Maps
• Proxy - NGINX instance serving Mergin Maps in reverse proxy configuration.

Firewall ports

By default, only HTTP port 8080 need to be open on firewall side. It is also recommended to open 443 port if SSL is enabled. All other infrastructure instances will work within the same docker network group, so no additional ports need to be managed on the firewall side.

Install Docker

Please, use the latest version of Docker and Docker Compose tools. Follow the official guidelines in accordance with your OS system.

Mergin Maps CE Docker Images

Community Edition only

The Mergin Maps CE images are stored on publicly accessible Lutra Consulting's Docker.

Follow the deployment guidelines to install and configure it.

Mergin Maps EE Docker Images

Enterprise Edition only

The Mergin Maps EE enhanced features are only available on specific Docker images stored on Lutra Consulting's private AWS repository. To get access, you need your contract and licence from our sales team.

Afterwards, you can follow this guide to retrieve your Mergin Maps EE images.

Enable Mergin Maps Telemetry

Make sure you follow deployment guidelines to ensure any firewalls in your infrastructure are configured to allow the call-home functionality to send usage data.

Deployment

Follow these steps to run a local Mergin Maps instance.

Clone the Mergin Maps github repository locally or download deployment folder.

$ git clone git@github.com:MerginMaps/server.git

Locate yourself on the proper Mergin Maps edition.

# For community edition
cd deployment/community

# For enterprise edition
cd deployment/enterprise

Setup environment

​ This step configures deployment settings by modifying environment variables.

Start by creating the .prod.env file (if it does not exist yet), by running:

cp .env.template .prod.env

Then, edit the .prod.env file and provide values for all variables marked as required in the list of environment variables.

Start docker containers

Before proceeding, ensure you have both docker and docker compose installed on your system.

Once your environment is configured, you can start the containers by running the following commands for the Community and Enterprise editions.

Community edition stack:

$ mkdir -p mergin_db # database data directory
$ sh ../common/set_permissions.sh projects # application internal data directory
$ sh ../common/set_permissions.sh diagnostic_logs # directory to persist diagnostic logs (optional)
$ docker compose -f docker-compose.yml up -d

Enterprise edition stack:

$ mkdir -p mergin-db-enterprise # database data directory
$ sh ../common/set_permissions.sh data # application internal data directory
$ sh ../common/set_permissions.sh map_data # maps data directory (neccessary for maps)
$ sh ../common/set_permissions.sh diagnostic_logs # directory to persist diagnostic logs (optional)
$ docker compose -f docker-compose.yml up -d
$ docker compose -f docker-compose.maps.yml up -d # Run maps stack separately

Diagnostic logs

Users of the Mergin Maps Mobile App and Mergin Maps QGIS plugin can send diagnostic logs from their devices. In custom deployments, logs are stored in the diagnostic_logs folder. If you do not want to persist these logs in a volume, remove the mount point for this folder in the /MerginMaps/server/blob/master/deployment/enterprise/docker-compose.yml file.

If you want to send diagnostic logs from devices to Mergin Maps instead of storing them in a folder, set DIAGNOSTIC_LOGS_URL to https://api.merginmaps.com/logs.

​​

Initialise database

If server is started for the first time, database needs to be initialised and super-user created. Use the init command which will perform it automatically (the command generates password for the admin account):

$ docker exec merginmaps-server flask init

If you don't have CONTACT_EMAIL variable set, you will be asked to provide a super user email using the -e/--email option. The init will also check your server setup (celery jobs, emails, etc.) and print out a list of missing variables. If you see any errors in the console output, you can run the command again as the database and super user will not be re-initialised.

TIP

If you want to create another users manually, you can use the following command:

$ docker exec merginmaps-server flask user create <username> <password> --is-admin --email <email>

Test deployment

In order to test your deployment there are some utility commands to perform basic checks.

Overall basic check on server configuration:

$ docker exec merginmaps-server flask server check

Output will be similar to the next snippet. The utility will try to provide some background information if some needed environment variable is missing or wrongly set (ex: MERGIN_BASE_URL)

# Server health check

Mergin Maps edition: Enterprise Edition
Mergin Maps version: 2025.2.0  
Error: No base URL set. Please set MERGIN_BASE_URL environment variable
Error: No contact email set. Please set CONTACT_EMAIL environment variable
Database initialized properly
Celery running properly

To test email configuration:

$ docker exec merginmaps-server flask server send-check-email --email me@myorg.com

By default, email notifications are disabled, so output will be similar to this:

# Sending check email to specified email address me@myorg.com.

Error: Sending emails is disabled. Please set MAIL_SUPPRESS_SEND=False to enable sending emails.

To enable them, set variable MAIL_SUPPRESS_SEND in accordance to above and fill all MAIL_* related variables with your company SMTP server configuration.

Some of the most common issues with custom deployments are listed in the troubleshoot section.