Mergin Maps

https://merginmaps.com/docs
Admin
Mergin Maps is a field data collection and geo-data synchronization platform built on QGIS that...
Tokens:43,893
Snippets:752
Trust Score:8.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies and start local server

Source: https://merginmaps.com/docs/misc/write-docs

Run these commands to install required packages and launch the VitePress development server.

```bash
cd MerginMaps/docs
yarn install 
yarn dev
```

--------------------------------

### Start Docker Containers

Source: https://merginmaps.com/docs/server/upgrade

Bring the updated services back online.

```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
```

--------------------------------

### Start Docker Containers

Source: https://merginmaps.com/docs/server/upgrade

Launch the services using Docker Compose.

```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
```

--------------------------------

### Start Community Edition Stack

Source: https://merginmaps.com/docs/server/install

Prepare data directories and launch the Community Edition containers.

```shell
$ 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
```

--------------------------------

### Start Docker containers

Source: https://merginmaps.com/docs/server/upgrade

Launch the Mergin Maps services using Docker Compose.

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

--------------------------------

### Start SSO Stack

Source: https://merginmaps.com/docs/server/sso-deployment

Execute this command to start the SSO stack using the specified Docker Compose file.

```shell
docker compose -f docker-compose.sso.yml up -d
```

--------------------------------

### Install Mergin Maps Python Client

Source: https://merginmaps.com/docs/dev/integration

Use pip to install the mergin-client package from PyPI.

```bash
pip3 install mergin-client
```

--------------------------------

### Start Docker containers

Source: https://merginmaps.com/docs/server/upgrade

Deploy the updated server and database containers using the existing docker-compose configuration.

```bash
$ docker compose -f docker-compose.yml up
```

--------------------------------

### Start Enterprise Edition Stack

Source: https://merginmaps.com/docs/server/install

Prepare data directories and launch the Enterprise Edition containers, including the maps stack.

```shell
$ 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
```

--------------------------------

### Create a New User

Source: https://merginmaps.com/docs/dev/integration

Method signature and example for creating a new user within a workspace.

```python
client.create_user(<email>, <password>, <workspace_id>, <workspace_role>, [username], [notify_user])
```

```python
from mergin.common import WorkspaceRole

client.create_user("jill@example.com", "T0p_secret", 1, WorkspaceRole.EDITOR, notify_user=True)
```

--------------------------------

### Start Docker Containers

Source: https://merginmaps.com/docs/server/upgrade

Start the updated containers in detached mode.

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

--------------------------------

### Project migration naming convention

Source: https://merginmaps.com/docs/server/upgrade

Examples of how project namespaces are transformed during the migration to a global workspace.

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

--------------------------------

### Test email configuration

Source: https://merginmaps.com/docs/server/install

Use this command to verify the email setup by sending a test message to a specified address.

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

--------------------------------

### Manage Docker Containers

Source: https://merginmaps.com/docs/server/upgrade

Commands to stop, remove, and start Docker containers during the upgrade process.

```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
```

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

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

--------------------------------

### Manage Docker Containers

Source: https://merginmaps.com/docs/server/upgrade

Commands to stop and start the Mergin Maps server containers.

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

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

--------------------------------

### Initialize Database

Source: https://merginmaps.com/docs/server/install

Run the initialization command to set up the database and create the initial super-user.

```shell
$ docker exec merginmaps-server flask init
```

--------------------------------

### Create Environment Configuration

Source: https://merginmaps.com/docs/server/install

Initialize the production environment file from the provided template.

```shell
cp .env.template .prod.env
```

--------------------------------

### Email configuration output

Source: https://merginmaps.com/docs/server/install

Example output when email notifications are disabled by default.

```shell
# 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.
```

--------------------------------

### Initialize MerginClient

Source: https://merginmaps.com/docs/dev/integration

Create a MerginClient instance to interact with the API. Requires valid user credentials.

```python
import mergin

client = mergin.MerginClient(login='john', password='T0p_secret')
client.download_project('lutraconsulting/Basic survey', '/tmp/basic-survey')
```

```python
import Mergin.mergin as mergin
client = mergin.MerginClient(login='john', password='T0p_secret')
```

--------------------------------

### Get Workspace Member Detail

Source: https://merginmaps.com/docs/dev/integration

Retrieves details for a specific member within a workspace.

```python
client.get_workspace_member(<workspace_id>, <user_id>)
```

--------------------------------

### Navigate to Deployment Directory

Source: https://merginmaps.com/docs/server/install

Switch to the directory corresponding to the edition being deployed.

```shell
# For community edition
cd deployment/community

# For enterprise edition
cd deployment/enterprise
```

--------------------------------

### Navigate to Deployment Directory

Source: https://merginmaps.com/docs/server/upgrade

Change directory to the community deployment folder.

```bash
$ cd server/deployment/community
```

--------------------------------

### Clone the documentation repository

Source: https://merginmaps.com/docs/misc/write-docs

Use this command to download the documentation source code to your local machine.

```bash
cd MyProjects
git clone git@github.com:MerginMaps/docs.git
```

--------------------------------

### Initialize Ory Polis Environment

Source: https://merginmaps.com/docs/server/sso-deployment

Navigate to the enterprise deployment directory and execute the initialization script to generate the .sso.env file.

```shell
cd deployment/enterprise/sso
./sso-init.sh
```

--------------------------------

### Update local repository

Source: https://merginmaps.com/docs/misc/write-docs

Ensure your local main branch is synchronized with the upstream repository before starting changes.

```bash
cd MerginMaps/docs
git checkout main
git pull origin main
```

--------------------------------

### Navigate to Deployment Directory

Source: https://merginmaps.com/docs/server/upgrade

Change directory to the enterprise deployment folder.

```bash
$ cd server/deployment/enterprise
```

--------------------------------

### Define default value for image direction

Source: https://merginmaps.com/docs/layer/exif

Example expression to store the GPSImgDirection EXIF tag in a survey field.

```text
read_exif(@project_home + '/' + "photo", 'GPSImgDirection')
```

--------------------------------

### Copy Configuration Files

Source: https://merginmaps.com/docs/server/upgrade

Move or copy existing environment and compose files to the deployment directory.

```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`
```

--------------------------------

### Generate photo name with prefix and reversed timestamp

Source: https://merginmaps.com/docs/gis/photo-names

Adds a static string prefix and uses a timestamp starting with seconds.

```QGIS Expression
'photo-' + format_date( now(),'ssmmhhddMMyy')
```

--------------------------------

### Configure Image Preview

Source: https://merginmaps.com/docs/gis/features

Display an image in the preview panel by using the # image marker followed by a file path or URL.

```text
# image
file:///[%@project_folder%]/[% "image_1" %]
```

--------------------------------

### Configure fork and upstream remotes

Source: https://merginmaps.com/docs/misc/write-docs

Set up your local environment to track both your fork and the official upstream repository.

```bash
mkdir MerginMaps; cd MerginMaps
git clone git@github.com:<my_fork_of_MerginMaps/docs>.git
git remote add upstream git@github.com:MerginMaps/docs.git
```

--------------------------------

### Example email task log output

Source: https://merginmaps.com/docs/server/troubleshoot

This shows the expected log format when an email task is successfully processed by the celery worker.

```text
[2024-12-09 10:37:16,265: INFO/ForkPoolWorker-2] Task mergin.celery.send_email_async[3e50df69-90c1-49be-b31c-78f1fb417500] succeeded in 0.11469305199989321s: None
```

--------------------------------

### Run Database Migrations

Source: https://merginmaps.com/docs/server/upgrade

Execute the database upgrade for community and enterprise components.

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

--------------------------------

### Clean Vector Tile Style URL

Source: https://merginmaps.com/docs/field/broken-project

Example of a problematic Style URL that should be truncated to resolve vector tile loading issues.

```text
styleUrl=https://raw.githubusercontent.com/QwantResearch/qwant-basic-gl-style/master/style.json&type=xyz&url=https://www.qwant.com/maps/tiles/ozbasemap/%7Bz%7D/%7Bx%7D/%7By%7D.pbf&zmax=14&zmin=0
```

```text
styleUrl=https://raw.githubusercontent.com/QwantResearch/qwant-basic-gl-style/master/style.json
```

--------------------------------

### Run Database Migrations

Source: https://merginmaps.com/docs/server/upgrade

Apply pending database migrations to the server.

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

```bash
$ docker exec merginmaps-server flask db upgrade heads
```

--------------------------------

### PROJ Pipeline Definition

Source: https://merginmaps.com/docs/gis/projections

Example of a PROJ pipeline string defining coordinate transformation steps, including projection inversion, horizontal grid shift, and unit conversion.

```PROJ
+proj=pipeline
+step +inv +proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy
+step +proj=hgridshift +grids=OSTN15_NTv2_OSGBtoETRS.gsb
+step +proj=unitconvert +xy_in=rad +xy_out=deg
```

--------------------------------

### Identify Vector Layer Save Failure

Source: https://merginmaps.com/docs/field/broken-project

Example of the error log generated in the Mergin Maps mobile app when a feature fails to commit due to incorrect attribute data types.

```text
2023-12-05 09:04:25.058221+0100 Input[2593:32260] "2023-12-05T08:04:25.058Z CommitChanges: Failed to commit changes:\nERROR: 1 feature(s) not added.\n\n  Provider errors:\n    wrong data type for attribute 12 of feature -2: 10\n"
```

--------------------------------

### Execute Database Migrations

Source: https://merginmaps.com/docs/server/upgrade

Run the upgrade commands to apply database schema changes.

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

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

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

```bash
$ docker exec merginmaps-server flask db upgrade heads
```

--------------------------------

### Verify Server Configuration

Source: https://merginmaps.com/docs/server/install

Perform a basic check of the server configuration and environment variables.

```shell
$ docker exec merginmaps-server flask server check
```

--------------------------------

### Navigate to Deployment Directory

Source: https://merginmaps.com/docs/server/upgrade

Change to the enterprise deployment directory after updating the repository.

```bash
 $ cd server/deployment/enterprise
```

--------------------------------

### Configure Environment Variables

Source: https://merginmaps.com/docs/server/upgrade

Required security and port settings for the .prod.env file.

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

--------------------------------

### Display Mergin CLI Help

Source: https://merginmaps.com/docs/dev/integration-cpp

Use the help command to view available options and commands for the mergin tool.

```bash
$ mergin --help
Usage: mergin [OPTIONS] COMMAND [ARGS]...

Options:  
  --help      Show this message and exit.
  --version   Show the version information.
  --username  Mergin username (or MERGIN_USERNAME env. variable)
  --password  Mergin password (or MERGIN_PASSWORD env. variable)
  --url       Mergin url      (defaults to app.merginmaps.com)

Commands:
  create         Create a new project on Mergin server
  download       Download last version of mergin project
  sync           Pull&Push the changes
  remove         Remove project from server.
```

--------------------------------

### Verify and Apply Database Migrations

Source: https://merginmaps.com/docs/server/upgrade

Check current migration versions and apply upgrades using the flask CLI.

```bash
$ docker exec merginmaps-server flask db current
$ docker exec merginmaps-server flask db stamp 6cb54659c1de
$ docker exec merginmaps-server flask db stamp e95d051969ce
$ docker exec merginmaps-server flask db upgrade community@b9ec9ab6694f
$ docker exec merginmaps-server flask db upgrade enterprise@c40e5e645b57
```

--------------------------------

### Create Additional Users

Source: https://merginmaps.com/docs/server/install

Manually create new users with administrative privileges.

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

--------------------------------

### Open local file via HTML widget

Source: https://merginmaps.com/docs/layer/open-file

Use an HTML anchor tag with the project:// protocol to link a file stored in the project folder.

```html
<a href="project://my-pdf.pdf">Open File</a>
```

--------------------------------

### Reference QGIS and QGIS Help pages

Source: https://merginmaps.com/docs/misc/write-docs

Use these components to link to specific QGIS website pages or documentation sections.

```html
<QGIS link="en/site/forusers/download.html" text="QGIS Download page" />
```

```html
<QGISHelp ver="latest" link="user_manual/index.html" text="See QGIS Help page" />
```

--------------------------------

### Download Project via CLI

Source: https://merginmaps.com/docs/dev/integration

Download a project from the Mergin Maps server to a local directory using the mergin command-line tool.

```bash
mergin download john/project1 ~/mergin/project1
```

--------------------------------

### Execute Database Migration

Source: https://merginmaps.com/docs/server/upgrade

Run the database migration to update the schema to the latest version.

```bash
$ docker exec merginmaps-server flask db upgrade heads
```

--------------------------------

### client.create_user

Source: https://merginmaps.com/docs/dev/integration

Creates a new user and adds them to a specified workspace. Requires workspace admin, owner, or server administrator privileges.

```APIDOC
## client.create_user(email, password, workspace_id, workspace_role, [username], [notify_user])

### Description
Creates a new user account and assigns them a role within a specific workspace.

### Parameters
- **email** (string) - Required - Unique email address for the user.
- **password** (string) - Required - Password meeting security requirements.
- **workspace_id** (int) - Required - The ID of the workspace where the user will be added.
- **workspace_role** (WorkspaceRole enum) - Required - The role assigned to the user in the workspace.
- **username** (string) - Optional - Username for the user; generated from email if omitted.
- **notify_user** (Boolean) - Optional - If true, sends email communication to the user. Default is False.
```

--------------------------------

### Create a new branch

Source: https://merginmaps.com/docs/misc/write-docs

Create and switch to a new branch for your documentation changes.

```bash
git checkout -b my_docs_fix_branchname
```

--------------------------------

### Configure HTML Map Tip

Source: https://merginmaps.com/docs/gis/features

Use standard HTML tags to format the content of the mobile app preview panel.

```html
<p><strong>Notes:</strong>[% "notes" %]</p>
```

--------------------------------

### Backup database

Source: https://merginmaps.com/docs/server/upgrade

Create a custom format dump of the PostgreSQL database.

```bash
$ docker exec mergin-db pg_dump -U postgres -Fc postgres > pg_backup.dump
```
Tokens:
Raw