Data Server

Host your own OME-ZARR data server on your lab network. Your data never leaves your infrastructure. The browser streams ZARR chunks directly from your server.

Why Use a Data Server?

• Keep data on-site: no cloud upload, no transfer costs
• Access control: JWT tokens scoped to specific datasets
• Works with the viewer: just paste a URL and go
• Simple setup: one Docker command

The whole progression

Share Your Microscopy Data With Your Team Without Sending Anyone a Hard Drive walks it end to end: open a local file, put it behind this server for colleagues on the network, then add a token once the data is sensitive. It also covers when you do not need this server at all, which is any time the data already sits on S3 or MinIO.

Install

mkdir -p ~/.findnuclei

docker run -d \
  -p 3333:3333 \
  -p 3334:3334 \
  -v /path/to/your/zarr/data:/data/storage \
  -v ~/.findnuclei:/data/config \
  -e FN_ADMIN_PASSWORD=changeme \
  fn0000/fn-data-server

Port	What
3333	Data server. S3-compatible, serves ZARR chunks
3334	Admin console. Manage tokens, browse buckets

Two mount points:

• /data/storage: your ZARR data directory (read-only is fine)
• /data/config: token database and signing key (persists across restarts)

Organize Your Data

Each top-level directory in your storage becomes a bucket:

/your/zarr/data/
├── project-alpha/
│   ├── sample1.zarr/
│   └── sample2.zarr/
└── project-beta/
    └── experiment.zarr/

View Your Data

Once the server is running, open the viewer with a direct link:

https://find-nuclei.github.io?url=http://localhost:3333/project-alpha/sample1.zarr

Or paste the URL into the Open Image dialog.

Authentication

By default, the data server requires JWT tokens for all data access. This is the recommended mode for any network that isn't fully trusted.

Create a Token

1. Open the admin console at http://localhost:3334/admin
2. Log in with your admin password
3. Set a label (e.g., "Alice's token") and scope (bucket name or * for all)
4. Click Create Token
5. Copy the token. It won't be shown again

Use the Token in the Viewer

Option 1: URL parameter

https://find-nuclei.github.io?url=http://localhost:3333/project-alpha/sample.zarr&token=YOUR_JWT

Option 2: Auth prompt

If you open a URL without a token, the viewer detects the 401 response and shows a 🔑 token prompt. Paste your token and the image loads.

Token Scoping

Tokens can be restricted to specific buckets:

• project-alpha: only access /project-alpha/ and its contents
• *: wildcard, access everything

Additional restrictions (optional):

• TTL: token expires after a set time
• Host: only works from specific domains (supports wildcards: *.lab.internal)
• IP: only works from specific client IPs (supports wildcards: 192.168.1.*)

Open Mode

For fully trusted networks (isolated lab VLAN, localhost only), you can disable authentication:

docker run -d \
  -e FN_AUTH_ENABLED=false \
  ...
  fn0000/fn-data-server

All data endpoints are open. No tokens needed.

Scaling

The data server runs multiple worker processes by default:

Users	Config
1–5	Default (4 workers)
5–20	-e FN_DATA_WORKERS=8
20–50	Multiple containers behind a load balancer

Network Setup

The data server only needs to be reachable from the user's browser, not from the internet:

┌─────────────┐          ┌─────────────┐          ┌──────────────┐
│  Viewer     │  ZARR    │   User's    │  ZARR    │ Data Server  │
│  (github.io)│  metadata│   Browser   │  chunks  │ (your LAN)   │
│             │◄────────►│             │◄────────►│              │
└─────────────┘          └─────────────┘          └──────────────┘

Common setups:

• Localhost: viewer and data server on the same machine
• Lab network: data server on a NAS or shared workstation
• VPN: users connect to the lab network remotely

CORS

The data server allows all origins by default (FN_CORS_ORIGINS=*). To restrict:

-e FN_CORS_ORIGINS=https://find-nuclei.github.io,http://localhost:8080

Troubleshooting

Image loads but appears dark

Auto-contrast needs pixel data to calculate display range. Try adjusting the channel contrast sliders manually, or click the auto-contrast button after the image has loaded.

401 / 403 errors

• 401: no token provided. Add &token=YOUR_JWT to the URL or enter it in the auth prompt.
• 403: token is invalid, expired, or scoped to a different bucket. Create a new token in the admin console.

Can't connect from browser

• Check that the data server is reachable from your browser (not just the server machine)
• If using Docker Desktop on Mac/Windows, localhost works from the host but not from other machines on the network. Use the machine's LAN IP instead.
• Check CORS settings if you see network errors in the browser console.

Docker networking

In Docker, the client IP seen by the server is the Docker gateway (e.g., 192.168.65.1), not 127.0.0.1. Check http://localhost:3334/health. The your_ip field shows what IP the server sees for your requests.