Deployment

Prerequisites

Docker ≥ 24 and Docker Compose ≥ 2.20
A running Bonsai instance if Bonsai is to be used for fetching allele profiles and sample metadata. MIMOSA can run without Bonsai if allele profiles are imported manually via the chewBBACA import page or the command line (see Pipeline).

Installation

git clone https://github.com/genomic-medicine-sweden/MIMOSA.git
cd MIMOSA
vi .env   # edit DOMAIN and JWT_SECRET at minimum
docker compose up -d

MIMOSA is then available in the browser at http://localhost:3000.

Note

If using the automation service, also update .env.automation — see Automation.

Note

MIMOSA requires MongoDB running as a replica set to detect outbreaks and dispatch notifications. The provided docker-compose.yml handles this automatically. If connecting to an external MongoDB instance, configure it with --replSet rs0.

Environment variables (`.env`)

Variable	Description	Required
`DOMAIN`	Hostname where MIMOSA is reachable (e.g. `rosalind.example.com`)	Yes
`BACKEND_PORT`	Port the backend listens on (e.g. `5000`)	Yes
`FRONTEND_PORT`	Port the frontend listens on (e.g. `3000`)	Yes
`BONSAI_PORT`	Port of the Bonsai service (used in frontend URL construction)	Yes
`MONGO_URI_INTERNAL`	MongoDB connection string used by backend and automation inside Docker (e.g. `mongodb://mongo:27017/mimosa?replicaSet=rs0`)	Yes
`JWT_SECRET`	Secret key for signing JWT tokens — use a long random string	Yes
`PUBLIC_ORIGIN`	Full public origin of the frontend, including scheme and port (e.g. `https://rosalind.example.com:3000`). Overrides the default `http://<DOMAIN>:<FRONTEND_PORT>`.	No
`NEXT_PUBLIC_API_URL`	Base URL the browser uses to reach the backend API (e.g. `http://rosalind.example.com:5000`)	No
`NEXT_PUBLIC_BONSAI_URL`	Base URL of the Bonsai service shown in the frontend	No
`SECURE_COOKIES`	Set to `true` to mark auth cookies as `Secure` (requires HTTPS)	No
`MIMOSA_RELATIVE_URL_BASE`	URL prefix if MIMOSA is served under a sub-path (e.g. `/mimosa`)	No

Reverse proxy / subpath

Leave all optional URL variables empty for standard local or direct deployments. For most non-standard setups, only PUBLIC_ORIGIN and MIMOSA_RELATIVE_URL_BASE need to be set. The remaining URL variables (NEXT_PUBLIC_API_URL, NEXT_PUBLIC_BONSAI_URL) are for advanced setups with separate internal/external routing.

HTTPS

Set SECURE_COOKIES=true when serving MIMOSA over HTTPS. This sets the Secure flag on the auth cookie. Do not set this for plain HTTP — it will break login.

Python environment (manual pipeline only)

Only needed if running the pipeline manually outside Docker (see Pipeline):

conda create -n mimosa python=3.11 -y
conda activate mimosa
pip install -r automation/requirements.txt

Verifying the installation

A test suite uploads three artificial samples (TEST1, TEST2, TEST3) to confirm MIMOSA handles uploads correctly:

python test/test.py --credentials credentials.json

On success, the samples appear in the database and are visible in the dashboard. To remove them afterwards:

python test/test.py --credentials credentials.json --delete

Updating MIMOSA

git pull
docker compose build --no-cache
docker compose up -d