Skip to content

Update docs for Docker related content #664

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MarcelGeo merged 6 commits into from
Sep 15, 2025
Merged

Update docs for Docker related content #664

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1275da6
Update docs for Docker related content
fernandinand Aug 4, 2025
79fdcb6
Add more insfrastructure content
fernandinand Aug 5, 2025
a2c8d74
Fix spelling
fernandinand Aug 5, 2025
22f54bf
Refine install and requirements text
fernandinand Aug 6, 2025
d1f1482
Typo
fernandinand Aug 6, 2025
d8a79ad
Follow up PR review
fernandinand Sep 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions scripts/wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ Skoda
SLYR
SSL
Survey123
synchronise
Comment thread
fernandinand marked this conversation as resolved.
TLS
Transifex
Trialing
Expand Down Expand Up @@ -232,6 +233,7 @@ openmaptiles
openssl
orthometric
orthophoto
orchestrator
osm
pbf
peatlands
Expand Down Expand Up @@ -282,6 +284,7 @@ uncheck
undoable
url
uuid
vCPUS
xcf
xyz
yml
Expand Down
38 changes: 33 additions & 5 deletions src/server/install/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,35 @@ Installation guide will help you to install your <CommunityPlatformNameLink /> 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.
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 <MainPlatformName /> projects, consider a host with **4 vCPUS**.

On OS level, we recommend to use a Linux distribution that has full compatibility with Docker, since <MainPlatformName /> 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 <MainPlatformName />. This is especially important on large projects with hundreds of megabytes in between syncs.


### Infrastructure overview

@varmar05 varmar05 Aug 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what about maps / SSO stack, shall we have something similar there?

@fernandinand fernandinand Aug 5, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not mix here optional components. Maybe on the dedicated sections to add something related with infrastructure requirements? It's mainly for Maps stack...

@varmar05 varmar05 Aug 6, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, I would not add it here but to corresponding sections if we have ones

@fernandinand fernandinand Aug 6, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe we don't have a maps stack section (yet)

@varmar05 varmar05 Aug 6, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's create a ticket at least for not to forget


* **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 <MainPlatformName />
* **Celery-Beat** - The Celery task orchestrator used by <MainPlatformName />
* **Celery-Worker** - The Celery container responsible for workers that perform tasks on <MainPlatformName />
* **Server** - The server backend instance of <MainPlatformName />
* **Web** - The frontend instance for <MainPlatformName />
* **Proxy** - NGINX instance serving <MainPlatformName /> 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.

::: 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
<ServerType type="CE" />
Expand Down Expand Up @@ -60,7 +88,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.

Expand All @@ -70,7 +98,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:
Expand All @@ -80,8 +108,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
Expand Down
16 changes: 8 additions & 8 deletions src/server/upgrade/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ Perform the migration:
<MigrationType type="EE" />
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`).
Expand Down Expand Up @@ -274,7 +274,7 @@ Perform the migration:
<MigrationType type="EE" />
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`).
Expand Down Expand Up @@ -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`).
Expand Down Expand Up @@ -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`).
Expand Down Expand Up @@ -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`)
Expand All @@ -395,7 +395,7 @@ Perform the migration:
<MigrationType type="EE" />
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`)
Expand Down Expand Up @@ -440,7 +440,7 @@ $ docker exec mergin-db pg_dump -U postgres -Fc postgres > pg_backup.dump

4. Stop all running <MainPlatformName /> 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
Expand Down Expand Up @@ -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.:
Expand Down
Loading