Getting Started

Choose the path that matches how you want to use LabFrog. If you only need to enter or review data, use an existing service. Install the repository only when you need a local instance, a deployment, or a development checkout.

Choose An Access Path

Path

Use it when

Start

HZDR production

You are an authorized HZDR user working with institutional experiment data

Open FWKT Shotsheet on the HZDR network or VPN

Hosted demo

You want a safe walkthrough without operating infrastructure

Open labfrog.hzdr.de and read Demo Mode

Local, no Docker

You already have a reachable MongoDB and want the shortest development loop

See Local Development Without Docker below

Local Docker

You want LabFrog and MongoDB together on one machine

Follow Docker Setup

Independent deployment

You operate your own application host and MongoDB

Follow External Deployment

First Use

Once LabFrog is open:

  1. Select the record mode: shot or set.

  2. Select a campaign.

  3. Open Add Entry.

  4. Enter the record and save it.

  5. Open Search Records and filter to the campaign to confirm the record.

If the campaign has no mapped form, Add Entry shows an inline setup prompt. A form administrator must select or create a layout before normal entry can continue. See Configuring Forms.

Local Development Without Docker

Requirements:

  • Python 3.11 or newer

  • uv

  • A MongoDB instance described by the selected instance/*.cfg file

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

Create .env and select a configuration:

CONFIG_NAME="default.cfg"

Check the environment before starting:

uv run poe doctor
uv run poe run-in-debug

Open http://127.0.0.1:5000/.

The bundled default.cfg is a local demo configuration. Review its database, authentication, and metadata-source settings before using it with real data.

Verify The Setup

Confirm that:

  • the login or anonymous-development flow completes

  • Add Entry opens for the selected campaign

  • a test record can be saved in a disposable database

  • Search Records can find that record

  • static assets and plots load without browser errors

Do not run database initialization or reset commands against a database that contains data you need to keep. See Deployment and Administration before changing metadata or database state.

Next Steps