A Rust port of EXACT (annotation tool for microscopy images): one binary plus PostgreSQL, a new React front end, and the same REST interface for exact-sync and ML workers. Work in progress.
You can start from scratch (no earlier EXACT needed, see Get started) or run it on an existing EXACT (Django) database: no schema change except additive tables, so Django can be rolled back at any time. The plan, decisions, measurements and the status of every phase are in PLAN.md.
Documentation: docs/ (published with GitHub Pages: user guide, shortcuts, administration, API, installation).
| Do you already run EXACT (the Django version)? | |
|---|---|
| No, I want to start using EXACT-Rust | follow the six steps below (about 30 minutes, most of it waiting) |
| Yes, I want to move my EXACT with its users and data | read Moving from EXACT: try it on a copy first, then run both side by side |
You need a computer with Windows, macOS or Linux, about 10 GB of free disk and an internet connection. No programming, no database and no graphics card are needed: everything runs inside Docker.
1. Install Docker Desktop from docker.com/products/docker-desktop and start it (on Windows it may ask to install WSL and to restart). On Linux install Docker Engine instead. Docker has to be running whenever EXACT-Rust should be reachable.
2. Download EXACT-Rust: on this page click the green Code button → Download ZIP, and unpack it, for example into
your Documents folder. (With git: git clone https://github.com/DeepMicroscopy/Exact-Rust.git.)
3. Open a terminal in that folder (the one that contains README.md and the folder deploy):
- Windows 11: right-click the folder → Open in Terminal (Windows 10: Shift + right-click → Open PowerShell window here)
- macOS: right-click the folder → Services → New Terminal at Folder (or open Terminal, type
cdand drag the folder into its window, then press Enter) - Linux: open a terminal and
cdinto the folder
4. Create your settings file and open it in a text editor; type the line for your system into the terminal and press Enter:
| Windows | copy deploy\quickstart.env.example deploy\.env and then notepad deploy\.env |
| macOS | cp deploy/quickstart.env.example deploy/.env and then open -e deploy/.env |
| Linux | cp deploy/quickstart.env.example deploy/.env and then nano deploy/.env |
In the file, replace both change-me with passwords of your own: SQL_PASSWORD (for the database; you never type it again, make it
long) and EXACT_ADMIN_PASSWORD (to log in). EXACT_ADMIN_USER is your login name, EXACT_ADMIN_TEAM the name of your first team.
Save and close the file.
5. Start EXACT-Rust:
docker compose -f deploy/quickstart.yml up -d --build
The first time this takes 20 to 40 minutes (it builds everything); you can follow it in the terminal. It is done when the prompt comes back; give the server another minute to prepare the database on its very first start. Later starts take seconds.
6. Open http://localhost:8002 in your browser and log in with EXACT_ADMIN_USER and
EXACT_ADMIN_PASSWORD. Change the password under your user name (top right) → Preferences.
Then create your first image set and upload slides; invite colleagues under Administration → Users.
Good to know
- EXACT-Rust starts by itself whenever Docker Desktop is running (also after a restart of the computer).
- Stop it:
docker compose -f deploy/quickstart.yml stop(start again with... start). - Update: download the new version, copy your
deploy/.envinto it and run the command of step 5 again in the new folder. Your slides, annotations and accounts are kept (they live in Docker, not in the downloaded folder). - Something does not work? The troubleshooting table lists the usual messages and
their fix;
docker compose -f deploy/quickstart.yml logs servershows what the server says. - More options (another port, slides in a folder of your own, access from other computers with https, the registration worker): Start from scratch.
The numbers
Median response time in milliseconds (lower is better), one request at a time, the first request of each series left out:
| Request | EXACT (Django), production | exact-rust, beta | faster |
|---|---|---|---|
| Image sets · Basic auth | 694 | 44 | 16× |
| Teams · Basic auth | 732 | 48 | 15× |
| Images, 100 · Basic auth | 649 | 80 | 8.1× |
| Image sets · session | 162 | 54 | 3.0× |
| Teams · session | 184 | 33 | 5.5× |
| Images, 100 · session | 138 | 74 | 1.9× |
| Slide information (DeepZoom) | 96 | 54 | 1.8× |
| Full-resolution tile | 109 | 45 | 2.4× |
| Low-resolution tile | 135 | 52 | 2.6× |
| Thumbnail | 111 | 84 | 1.3× |
How this was measured (tests/perf/compare_servers.py; the picture is drawn by tests/perf/render_chart.py): the same read-only requests against the old EXACT on its production server and
exact-rust on a copy of the same data (24,169 images, 1.4 million annotations), one request at a time, the two servers alternating, with an ordinary member account on each. Basic auth
is what exact-sync and workers use (Django checks the password on every request, which is most of its time there); session is what the browser uses after logging in. The slide requests are the DeepZoom descriptor,
a tile and the thumbnail of 11 images in 6 formats. Caveats: measured over home wifi, so differences below about 50 ms are noise; the two accounts differ by one team; production serves real users meanwhile.
Not in the picture: loading all 45,000 annotations of one image at once (the call exact-sync uses; Django had not answered after three minutes) and many parallel clients: both are in the script and need a quiet server.
| Area | State |
|---|---|
| Auth: password (all Django hash formats), tokens, sessions, passkeys (server side), invitations, impersonation (API) | done |
REST: /api/v1 byte-compatible with EXACT incl. writes and the legacy endpoints of exact-sync; /api/v2 for the new UI |
done |
| Slides: OpenSlide formats, TIFF/BigTIFF, OME-TIFF z-stacks, NIfTI/DICOM (three-plane view), MKT, MP4/AVI, CZI/VSI (helper) | done; iSyntax dropped |
| Pyramid repair, level registration, image registration (manual and by worker plugins), job queue | done |
| Front end: image sets, uploads, viewer with annotation tools and polygon operations, crops, export, registration, jobs, administration | done |
| Deployment: Dockerfile, compose, systemd units, runbook (docs/DEPLOY.md); new installations without Django | beta on a copy of production in progress |
crates/exact-coreconfig, errors -exact-dbqueries and additive migrations -exact-authhashes, tokens, WebAuthncrates/exact-wsislide readers, DeepZoom tiles, TIFF reader/writer, pyramid repair and registrationcrates/exact-apiHTTP layer (compat/= v1/legacy for exact-sync,v2/, slides, repair) -exact-server,exact-clifrontend/React + TypeScript + Vite;helpers/slideio_helper.pyreads CZI/VSI/DICOM through slideiotests/conformancereplays recorded responses of the reference EXACT against this server;tests/perf,reference/(reference Django setup)
To install and use EXACT-Rust see Get started; this is for working on the code.
make ui # build the front end (frontend/dist, served by the binary)
cargo build -p exact-server -p exact-cli # needs libopenslide, ffmpeg (libav*) and libclang to build
export SQL_DATABASE=exact SQL_USER=... SQL_PASSWORD=... IMAGE_PATH=/path/to/images EXACT_LISTEN=127.0.0.1:8002
target/debug/exact-cli migrate --confirm-db exact # an empty database gets EXACT's tables first: no Django needed for a new instance
target/debug/exact-cli create-superuser --username admin --team mylab --confirm-db exact # new instance only; password on stdin
target/debug/exact-server
Configuration uses EXACT's environment variable names (SQL_*, IMAGE_PATH, FIDO_SERVER_ID, ...); EXACT_CACHE_DIR holds
thumbnails, SLIDEIO_PYTHON / SLIDEIO_HELPER select the slideio helper, EXACT_STATIC_DIR the front end.
make verify restores a scratch database from a backup of an EXACT database (backups/, not in the repository: create it
with pg_dump -Fc of a local EXACT, see scripts/restore-backup.sh), starts the reference Django and this server and runs
unit tests, conformance (Django vs. recorded responses vs. Rust), exact-sync, the v2 suites and a schema-sync check
(make schema-sync). make e2e runs the browser smoke test (system Chrome); make e2e-repair the repair flow on a scratch copy.
MIT, like EXACT.



