Local Deployment With Docker

At A Glance

Task	Command
First run or intentional reset	uv run poe init-docker-db, then uv run poe debug-with-dockerdb
Normal local debug restart	uv run poe debug-with-dockerdb
Production-like local app server	uv run poe serve-with-dockerdb
Stop containers	docker compose down

Prerequisites

• Install uv, for example with pip install uv

• Install Docker

• On Linux, make sure your user can run Docker commands

If Docker is not running yet, use uv run poe ensure-docker. On Windows that checks Docker Desktop is up; on Linux it also tries common service-start commands.

If your Linux host needs a Docker restart after a machine reboot, run this once and then use the regular Docker-backed Poe commands as usual:

uv run poe restart-docker
uv run poe debug-with-dockerdb

On Windows, the regular flow stays the same; if Docker Desktop is confused, close active containers or restart Docker Desktop manually.

Setup

1. Clone the repository and switch to develop.

   git clone https://codebase.helmholtz.cloud/fwk/fwkt/fwkt-data-management/data-capturing/labfrog.git
   cd labfrog
   git switch develop
   

2. Install dependencies.

   uv sync
   

3. Create a local config and point .env at it.

   cp instance/default.cfg instance/docker.cfg
   

   CONFIG_NAME="docker.cfg"
   

4. For routine local development, disable auth in instance/docker.cfg.

   AUTH_METHOD = "none"
   

5. Initialize the Docker-backed database state.

   uv run poe init-docker-db
   

6. Start the app.

   uv run poe debug-with-dockerdb
   

7. Open LabFrog at http://127.0.0.1:5000/.

Normal Restart

For everyday local work, use:

uv run poe debug-with-dockerdb

Optional helpers:

• Mongo Express: http://127.0.0.1:8081/

• Gunicorn against the same Docker MongoDB: uv run poe serve-with-dockerdb

Optional Metadata Customization

If you want a custom local form definition:

1. Edit labfrog/customize/USER-DEFINED-DIAGNOSTICS.ods

2. If you are not using MediaWiki for campaign or target lists, also update:

   • labfrog/customize/CUSTOM_CAMPAIGNS.ods

   • labfrog/customize/CUSTOM_TARGETS.ods

3. Enable the matching options in instance/docker.cfg

   USE_WIKI = False
   USE_CUSTOM_OPTIONS = True
   CUSTOM_OPTIONS_CAMPAIGNS = "CUSTOM_CAMPAIGNS.ods"
   CUSTOM_OPTIONS_TARGETS = "CUSTOM_TARGETS.ods"
   CUSTOM_OPTIONS_COLLECTION = "custom_options"
   
   USE_FULL_CUSTOM = True
   USE_FULL_CUSTOM_FILE = "USER-DEFINED-DIAGNOSTICS.ods"
   MONGODB_COLLECTION_FOR_SETTINGS = "custom_selections"
   

4. Rebuild metadata without dropping saved shots

   uv run flask --app labfrog init-db --reset keep-shots --rebuild both --source auto
   

Use uv run poe init-docker-db again only when you want to rebuild the Docker-backed metadata state before starting the app.