G. Preflight + boot

Everything is now configured. This step runs a preflight check to confirm your setup, starts the pipeline, and opens the submission UI in your browser.

Requires: TLS + credentials (step F)

The preflight check verifies the certificate and login you created in F. TLS + credentials, along with the configuration and reference data from the earlier steps. Complete steps A–F first.

Windows: use Git Bash

All make commands must be run in Git Bash, not PowerShell or cmd.exe.

1. Preflight: make doctor

make doctor

doctor is a read-only check that confirms your .env, required settings, the rotated config salt, your reference data files (model.json + mappers.xlsx), the TLS certificate and key, your credentials file, the data mounts, and the required tools (Docker, gh login, OpenSSL, make).

Verify reference data contents: make check-mappers METADATA=...

doctor only checks that the reference data files exist, not that their contents are valid. To verify your mappers.xlsx covers all the coded values in your data, run make check-mappers with METADATA= pointing at your metadata workbook, after editing the mappers file:

make check-mappers METADATA=./path/to/your-metadata.xlsx

Without METADATA=, the command checks a bundled test fixture (tests/data/metadata/metadata.xlsx), not your data — a clean result then means nothing about your submission. Run it with your own workbook to catch unmapped values up front, before they become invalid items in the curation UI.

A healthy setup ends with doctor: OK:

OK: .env exists
OK: gh is installed, authenticated, and wired into git
doctor: OK
Fix every FAIL before continuing

Any problem is printed as a FAIL: line and doctor exits without reaching doctor: OK. Each line names what is wrong; fix them all and re-run make doctor until it is clean. Do not run make up until doctor passes — booting on a broken setup just fails later, less clearly.

2. Start the stack

make up

This starts all the pipeline services (database, web app, and workers) using the images you pulled in C. Install package. First boot can take up to a minute while the database initialises and the app reports healthy — the command waits for that, then prints the UI address:

[+] Running 5/5
 ✔ Container bp-submission-pipeline-pipeline-db-1       Healthy
 ✔ Container bp-submission-pipeline-slidetap-db-init-1  Exited
 ✔ Container bp-submission-pipeline-slidetap-task-1     Started
 ✔ Container bp-submission-pipeline-slidetap-app-1      Healthy
 ✔ Container bp-submission-pipeline-slidetap-web-1      Started
slidetap UI: https://localhost:443  (resolves to 127.0.0.1)

The address comes from your .env: PIPELINE_SERVERNAME and PIPELINE_PORT. With the defaults from D. Configure (localhost and 443) it is https://localhost:443. If you changed either value, use the address make up printed for you.

3. Open the UI

Open the address from the previous step in your browser.

Because the certificate is self-signed (you created it yourself in step F), the browser shows a “your connection is not private / not secure” warning. This is expected and does not mean anything is wrong. It only means the certificate was not issued by a public authority. Tell the browser to continue:

Click Advanced, then Proceed to localhost (unsafe).

Click Advanced…, then Accept the Risk and Continue.

Click Show Details, then visit this website, and confirm.

You should land on the login page, confirming the stack is up.

4. Add a slide image for the test run

The example sample set ships with metadata, mappers, and a model file, but no slide image — whole-slide images run to gigabytes and are too large to bundle. Before you run the test submission in H. Run a submission, place one slide in your image folder so the Pre-process step has something to convert. OpenSlide publishes freely usable example slides for exactly this.

  1. Open the OpenSlide demo gallery: https://openslide.org/demo/.
  2. Pick a slide and download it. Some formats are large and slow to download and convert, so start with a small, single-file Aperio (.svs) slide — e.g. Aperio › CMU-1-Small-Region (a few MB) or Aperio › CMU-1. Avoid the MIRAX (.mrxs) and Hamamatsu VMS slides for a first run: they arrive as multi-file bundles and take longer to process.
  3. Move the downloaded file into your image folder, PIPELINE_IMAGE_ROOT (default ./data/images — see D. Configure).
  4. Open tests/data/metadata/metadata.xlsx — the example workbook that ships with the pipeline — and set its Image path cell to the filename you just downloaded (e.g. CMU-1-Small-Region.svs). The shipped value is a placeholder (IMAGE_gold-ref) — replace it with the exact filename on disk. Pre-process resolves the path relative to PIPELINE_IMAGE_ROOT.
Note

The image folder is mounted read-only into the containers, but files you drop in after make up are still picked up live — you do not need to restart the stack.

Logging in and running a submission is the next step, H. Run a submission.

Useful controls

  • make logs — follow the live output from all services (press Ctrl-C to stop watching; the services keep running). Your first stop when something misbehaves. Tail one service with make logs s=slidetap-app.
  • make down — stop and remove the containers. Your data is preserved; run make up again to restart.

When do I need to restart?

Once the stack is running, editing a file on disk doesn’t always take effect immediately — it depends on when the containers read it.

File Needs a restart? Why
mappers.xlsx Yes — make down then make up slidetap-app/slidetap-task parse it once when they start. The bind-mounted file changes on disk immediately, but the running process keeps what it already parsed
model.json Yes — make down then make up Same as mappers.xlsx — parsed once at startup
config.yaml Yes — make down then make up Parsed once at startup, same as the reference data files
.env Yes — but just re-running make up is enough, see below Baked into each container’s environment and bind-mount paths when Compose creates it
credentials.json Yes — make down then make up Password hashes load into memory once, when slidetap-app starts
TLS certificate/key (from F. TLS + credentials) Yes — make down then make up slidetap-web (nginx) reads the certificate and key once, when it starts
NBIS receiver credentials (from J. Upload) No — picked up live make upload/make upload-dry-run create a fresh, one-off container for every run, so they always read whatever is on disk at that moment
.env shortcut: you can skip make down

For .env changes specifically, re-running make up on its own is enough — Compose detects that the resolved container configuration changed and recreates just the affected containers. For the other rows above marked “Yes”, only the file’s content changed, not the container configuration, so a plain make up sees nothing to do — you need the full make down + make up cycle to force those containers to start fresh and re-read the file.

None of these need make rebuild

make rebuild force-rebuilds the container images from source — for when the application code itself changes, not when you edit your own config or reference data. Editing any file in the table above never needs a rebuild, at most a restart.

If something goes wrong

  • doctor says a cert, key, or credentials file is missing. You skipped or mis-set F. TLS + credentials. Re-run make ssl and make gen-credentials.
  • doctor says the config still matches the example / the salt is not rotated. Rotate the salt in D. Configure, then re-run make gen-credentials so your login still matches.
  • doctor says a host path is missing or not owned by UID 1000. Create the local data tree with make dirs (single-host setups), or fix the mount — see D. Configure.
  • doctor says gh is not logged in. Re-run the sign-in from B. GitHub access.
  • The browser can’t reach the UI after make up. Give it a few seconds and refresh. If it still fails, check the service output with make logs — the app may have failed to start. Confirm nothing else is using the port in PIPELINE_PORT.