### 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(, , , , [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(, ) ``` -------------------------------- ### 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:.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='' SECURITY_BEARER_SALT='' 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 --is-admin --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 Open File ``` -------------------------------- ### 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 ``` ```html ``` -------------------------------- ### 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

Notes:[% "notes" %]

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