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

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

Platform Integration

If you're using the Find Nuclei Platform, you can register your data server as a Data Source:

1. Go to Settings → Data Sources in the platform
2. Add your server URL and a token
3. Click Test Connection
4. Images added from your data server will stream through the platform viewer

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.