From 1275da634f1a02367e70b5d34d0249ac4f6b47c8 Mon Sep 17 00:00:00 2001 From: Fernando Ribeiro Date: Mon, 4 Aug 2025 16:35:46 +0100 Subject: [PATCH 1/6] Update docs for Docker related content --- src/server/install/index.md | 13 +++++++++---- src/server/upgrade/index.md | 16 ++++++++-------- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/src/server/install/index.md b/src/server/install/index.md index ae26d580..c778280c 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -9,6 +9,11 @@ Installation guide will help you to install your o We recommend using a dedicated host machine with 8 GB of memory. 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. +## Install Docker from official source + +Please, use latest version of Docker and Docker Compose tools. +Follow the [official](https://docs.docker.com/engine/install/) guidelines in accordance to your OS system. + ## Mergin Maps CE Docker Images @@ -60,7 +65,7 @@ Then, edit the `.prod.env` file and provide values for all variables marked as r ### Start docker containers -Before proceeding, ensure you have both `docker` and `docker-compose` installed on your system. +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. @@ -70,7 +75,7 @@ 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 +$ docker compose -f docker-compose.yml up -d ``` Enterprise edition stack: @@ -80,8 +85,8 @@ $ 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 +$ docker compose -f docker-compose.yml up -d +$ docker compose -f docker-compose.maps.yml up -d # Run maps stack separately ``` ​​ ### Initialise database diff --git a/src/server/upgrade/index.md b/src/server/upgrade/index.md index dde44ffe..beb4eca8 100644 --- a/src/server/upgrade/index.md +++ b/src/server/upgrade/index.md @@ -242,7 +242,7 @@ Perform the migration: 1. Start up your docker containers ```bash - $ docker-compose -f docker-compose.yml up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up # or similarly, based on your deployment ``` 2. Check that you are on correct versions (`0e3fc92aeaaa`, `223e3be99e92`). @@ -274,7 +274,7 @@ Perform the migration: 1. Start up your docker containers ```bash - $ docker-compose -f docker-compose.yml up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up # or similarly, based on your deployment ``` 2. Check that you are on correct versions (`a5d4defded55`, `223e3be99e92`). @@ -306,7 +306,7 @@ 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 + $ docker compose -f docker-compose.yml up # or similarly, based on your deployment ``` 2. Check that you are on correct versions (`35af0c8be41e`, `3a77058a2fd7`). @@ -334,7 +334,7 @@ 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 + $ docker compose -f docker-compose.yml up # or similarly, based on your deployment ``` 2. Check that you are on correct versions (`3a77058a2fd7`, `0d867687ab64`). @@ -371,7 +371,7 @@ Perform the migration: 1. Start up your docker containers ```bash - $ docker-compose -f docker-compose.yml up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up # or similarly, based on your deployment ``` 2. Check that you are on a correct version (`b6cb0a98ce20`) @@ -395,7 +395,7 @@ Perform the migration: 1. Start up your docker containers ```bash - $ docker-compose -f docker-compose.yml up # or similarly, based on your deployment + $ docker compose -f docker-compose.yml up # or similarly, based on your deployment ``` 2. Check that you are on correct versions (`b6cb0a98ce20`, `0d867687ab64`) @@ -440,7 +440,7 @@ $ docker exec mergin-db pg_dump -U postgres -Fc postgres > pg_backup.dump 4. Stop all running services (from project root folder) ```bash -$ docker-compose -f docker-compose.yml stop +$ docker compose -f docker-compose.yml stop ``` 5. Pull the latest changes @@ -488,7 +488,7 @@ There are few settings you may want to change values for: 7. Make sure projects volume mounts in `docker-compose` file still match (You can set up new volumes by following the [quick start guide](../install/)). 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 +$ docker compose -f docker-compose.yml up ``` 8. Restore backup from older PostgreSQL version, e.g.: From 79fdcb60764828b94c68a55441dcf809c5a88b9c Mon Sep 17 00:00:00 2001 From: Fernando Ribeiro Date: Tue, 5 Aug 2025 10:52:40 +0100 Subject: [PATCH 2/6] Add more insfrastructure content --- src/server/install/index.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/src/server/install/index.md b/src/server/install/index.md index c778280c..dd9895eb 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -7,7 +7,29 @@ Installation guide will help you to install your o ## Installation System Requirements -We recommend using a dedicated host machine with 8 GB of memory. 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. +We recommend using a dedicated host machine with **8 GB** of memory and **4 vCPUS**. 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 `qgis project size * number of versions`. + +On OS level, we recommend to use a Linux distribution that has fully compatibility with Docker, since is deployed by default with `docker compose`. + +A low-latency, high-bandwidth environment is preferred due to volume of data needed to perform synchronization with . This is specially important on large projects with hundreds of megabytes in between syncs. + + +### Infrastructure overview + +* **PostgreSQL** - Database that holds application data. Can be externalized and therefore excluded from install orchestration with proper [configuration](https://merginmaps.com/docs/server/environment/#database-settings). +* **Redis** - The caching and asynchronous task engine running on top of +* **Celery-Beat** - The Celery task orchestrator used by +* **Celery-Worker** - The Celery container responsible for workers that perform tasks on +* **Server** - The server backend intance of +* **Web** - The frontend instance for +* **Proxy** - NGINX instance serving in reverse proxy configuration. + +### Firewall ports + +By default, only HTTP default ports (`80`, and `443` if SSL is enabled) need to be open on firewall side. +All other infrastructure instance will work within the same docker network group. + ## Install Docker from official source From a2c8d749528e4a8233fc5165894d13fde66eece3 Mon Sep 17 00:00:00 2001 From: Fernando Ribeiro Date: Tue, 5 Aug 2025 11:03:57 +0100 Subject: [PATCH 3/6] Fix spelling --- scripts/wordlist.txt | 3 +++ src/server/install/index.md | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/scripts/wordlist.txt b/scripts/wordlist.txt index a29f8fa8..424c360a 100644 --- a/scripts/wordlist.txt +++ b/scripts/wordlist.txt @@ -144,6 +144,7 @@ Skoda SLYR SSL Survey123 +synchronization TLS Transifex Trialing @@ -232,6 +233,7 @@ openmaptiles openssl orthometric orthophoto +orchestrator osm pbf peatlands @@ -282,6 +284,7 @@ uncheck undoable url uuid +vCPUS xcf xyz yml diff --git a/src/server/install/index.md b/src/server/install/index.md index dd9895eb..91b126d7 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -17,11 +17,11 @@ A low-latency, high-bandwidth environment is preferred due to volume of data nee ### Infrastructure overview -* **PostgreSQL** - Database that holds application data. Can be externalized and therefore excluded from install orchestration with proper [configuration](https://merginmaps.com/docs/server/environment/#database-settings). +* **PostgreSQL** - Database that holds application data. Can be external and therefore excluded from install orchestration with proper [configuration](https://merginmaps.com/docs/server/environment/#database-settings). * **Redis** - The caching and asynchronous task engine running on top of * **Celery-Beat** - The Celery task orchestrator used by * **Celery-Worker** - The Celery container responsible for workers that perform tasks on -* **Server** - The server backend intance of +* **Server** - The server backend instance of * **Web** - The frontend instance for * **Proxy** - NGINX instance serving in reverse proxy configuration. From 22f54bf02f82f29f9bf509606187c8ac4994a4a0 Mon Sep 17 00:00:00 2001 From: Fernando Ribeiro Date: Wed, 6 Aug 2025 10:43:48 +0100 Subject: [PATCH 4/6] Refine install and requirements text --- src/server/install/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/server/install/index.md b/src/server/install/index.md index 91b126d7..8023e522 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -7,8 +7,10 @@ Installation guide will help you to install your o ## Installation System Requirements -We recommend using a dedicated host machine with **8 GB** of memory and **4 vCPUS**. 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 `qgis project size * number of versions`. +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 synchronize often your projects, consider a host with **4 vCPUS**. On OS level, we recommend to use a Linux distribution that has fully compatibility with Docker, since is deployed by default with `docker compose`. @@ -27,8 +29,8 @@ A low-latency, high-bandwidth environment is preferred due to volume of data nee ### Firewall ports -By default, only HTTP default ports (`80`, and `443` if SSL is enabled) need to be open on firewall side. -All other infrastructure instance will work within the same docker network group. +By default, only HTTP port `8080` need to be open on firewall side. Also is 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 firewall side. ## Install Docker from official source From d1f1482d4e43e066bda7d30024e8bc35339c5faa Mon Sep 17 00:00:00 2001 From: Fernando Ribeiro Date: Wed, 6 Aug 2025 11:07:11 +0100 Subject: [PATCH 5/6] Typo --- scripts/wordlist.txt | 1 + src/server/install/index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/wordlist.txt b/scripts/wordlist.txt index 424c360a..1e5006a0 100644 --- a/scripts/wordlist.txt +++ b/scripts/wordlist.txt @@ -145,6 +145,7 @@ SLYR SSL Survey123 synchronization +synchronise TLS Transifex Trialing diff --git a/src/server/install/index.md b/src/server/install/index.md index 8023e522..5d7c1f97 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -10,7 +10,7 @@ Installation guide will help you to install your o 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 synchronize often your projects, consider a host with **4 vCPUS**. +If you have a team size over 25 people and synchronise often your projects, consider a host with **4 vCPUS**. On OS level, we recommend to use a Linux distribution that has fully compatibility with Docker, since is deployed by default with `docker compose`. From d8a79ad5d37e87bd65cf4cc4e9397bbb9ebc636a Mon Sep 17 00:00:00 2001 From: Fernando Ribeiro Date: Mon, 1 Sep 2025 14:22:17 +0100 Subject: [PATCH 6/6] Follow up PR review --- scripts/wordlist.txt | 1 - src/server/install/index.md | 17 ++++++++--------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/scripts/wordlist.txt b/scripts/wordlist.txt index 1e5006a0..ece4c8e2 100644 --- a/scripts/wordlist.txt +++ b/scripts/wordlist.txt @@ -144,7 +144,6 @@ Skoda SLYR SSL Survey123 -synchronization synchronise TLS Transifex diff --git a/src/server/install/index.md b/src/server/install/index.md index 5d7c1f97..0aa43adb 100644 --- a/src/server/install/index.md +++ b/src/server/install/index.md @@ -12,9 +12,9 @@ The requirements for CPU and persistent storage depend largely on the frequency 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 projects, consider a host with **4 vCPUS**. -On OS level, we recommend to use a Linux distribution that has fully compatibility with Docker, since is deployed by default with `docker compose`. +On OS level, we recommend to use a Linux distribution that has full compatibility with Docker, since is deployed by default with `docker compose`. -A low-latency, high-bandwidth environment is preferred due to volume of data needed to perform synchronization with . This is specially important on large projects with hundreds of megabytes in between syncs. +A low-latency, high-bandwidth environment is preferred due to the volume of data needed to perform synchronisation with . This is especially important on large projects with hundreds of megabytes in between syncs. ### Infrastructure overview @@ -29,14 +29,13 @@ A low-latency, high-bandwidth environment is preferred due to volume of data nee ### Firewall ports -By default, only HTTP port `8080` need to be open on firewall side. Also is 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 firewall side. +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 from official source - -Please, use latest version of Docker and Docker Compose tools. -Follow the [official](https://docs.docker.com/engine/install/) guidelines in accordance to your OS system. +::: details Install Docker +Please, use the latest version of Docker and Docker Compose tools. +Follow the [official](https://docs.docker.com/engine/install/) guidelines in accordance with your OS system. +::: ## Mergin Maps CE Docker Images