/concepts/examples-site/
The examples site
The examples site shows every capability of vola, one page per capability, over a demo tenant. Anyone can open it, upload a file, share it or set a PIN, without an account or a pasted key. This page explains what limits those visitors.
The server serves the built site itself (VOLA_UI_DIR), so one container is both the API and the site. All the demo routes exist only when VOLA_EXAMPLES=true. Otherwise they answer 404 and the site asks for a key.
Two keys
Section titled “Two keys”| Key | Scopes | Where it lives |
|---|---|---|
VOLA_DEMO_API_KEY |
files:read, folders:read |
Handed to every visitor by GET /vola/examples/config, along with the demo instance, the limits and the server’s features |
VOLA_DEMO_WRITE_KEY |
files:write, folders:write, shares:write, keyrings:write and the reads |
Never leaves the server |
At startup the server creates the demo tenant if it is missing and stores both keys by hash. A key that already exists is checked. The server refuses to start and says why if the visitor key has any write scope, if the write key is short of one, or if a key belongs to another tenant or is revoked.
The write proxy
Section titled “The write proxy”A visitor’s write goes to /vola/examples/write/<route> without a key. The server checks it against a policy and replays it against <route> under the write key. The policy is the visitor’s whole authority: anything it does not name is 403 demo_forbidden, which includes keys, admin, stats, another instance and another tenant’s file.
| What | Route | Guard |
|---|---|---|
| Upload | POST files/demo/<id> |
Content-Length up to 5 MiB plus 64 KiB of multipart, else 413. After the upload the type must be on the list, else the file is purged and the answer is 415 demo_mime_not_allowed |
| Resumable upload | POST uploads, then HEAD, PATCH and DELETE on uploads/:id |
Upload-Length up to 5 MiB and the demo instance in the metadata. Location is rewritten to the proxy. The type is checked when the last PATCH completes |
| Change a file or folder | PATCH and DELETE on files/…/:fileId, POST, PATCH and DELETE on folders/… |
created_by must equal the request’s X-User-Id, so a seeded row or another visitor’s is 403 demo_forbidden. So is an own folder holding someone else’s file or subfolder |
| Shares | POST and GET on shares, GET and DELETE on shares/:id |
The file must be in the demo instance. expires_at is capped at VOLA_DEMO_TTL_HOURS. The list shows the visitor’s own shares, and another visitor’s share is 403 |
| The visitor’s keyring | keyrings/me/* |
The visitor’s own principal |
The type list is images, PDF, mp4 and webm video, mp3, mp4, ogg and wav audio, plain text and Markdown. An upload naming a parent_id, or a resumable one naming a slug, is 403 when that would add to or replace a file the visitor did not make.
The visitor id
Section titled “The visitor id”Every proxied request must carry X-User-Id: demo- followed by 6 to 32 lowercase letters or digits. The site makes one per browser session and keeps it in sessionStorage. Without it, the answer is 400 demo_user_required.
This id is the created_by of everything the visitor makes, which is what the purge selects on. It is also the principal of their keyring. Settings on the site has a “New identity” button. A new identity, or a second tab, is another visitor and cannot change what the first one made.
The ownership check stops accidents and casual edits, not an attacker. X-User-Id is self-declared and created_by is in every file’s answer, so anyone reading the demo can send another visitor’s id.
Rate limit
Section titled “Rate limit”Writes are limited per address: VOLA_DEMO_RATE_LIMIT (60) per ten minutes, then 429 demo_rate_limited with Retry-After. Behind a reverse proxy, set VOLA_TRUST_PROXY=true so the address is the visitor’s and not the proxy’s.
The purge
Section titled “The purge”Every VOLA_DEMO_PURGE_INTERVAL_MIN (15) minutes, and once at start, the server removes what visitors made more than VOLA_DEMO_TTL_HOURS (24) ago. It goes in this order:
- Their keyrings, as a crypto-shred. The files under them go first.
- Their files in the demo instance: every version, soft-deleted rows too. A blob no other row cites is removed from disk.
- Their folders.
The seeder’s files are never selected. Shares end with their capped expiry. Each row goes by its own creation time, with one exception: a folder past its age is deleted recursively, so a younger file in it is soft-deleted with it. An admin key can run the purge at once with POST /vola/examples/purge.
How the site talks to the server
Section titled “How the site talks to the server”The site is Vite and React 19 on @vol-a/react and @jsudc/react. Its VolaProvider gets a VolaClient whose fetch is a small wrapper called demoFetch:
- A request that needs the proxy goes to the write proxy without the key. That means anything other than
GETorHEAD, the whole/uploadsprotocol,/shares, and/keyrings/me/*. The unlock beacon, the UDC actions and the demo routes are exceptions and do not use the proxy. - Everything else goes straight to the API with the read-only key.
- With a key of the visitor’s own, set in Settings, nothing is rewritten.
The site sets the resumable threshold to 1 MiB and the chunk to 256 KiB, so the resumable path has room under the 5 MiB cap and the progress bar moves.
One more demo route, POST /vola/examples/regenerate/:fileId, drops a demo file’s thumbnails so the next /thumb answers 202 and queues the worker again. The Thumbnails page’s button calls it.
The demo pack
Section titled “The demo pack”vola demo-seed, run by the compose seeder service, upserts ten generated files under their slugs as X-User-Id: seeder: images, documents, a video clip and an audio tone marked is_global_public, and two tenant-encrypted files. A restart changes nothing when the bytes are the same. ASSETS.md lists them.
The sidebar is the repository’s menu.yaml, served as the menu UDC collection.
Running your own
Section titled “Running your own”Make the key pair once for your .env. Nothing is stored until the server starts:
docker compose -f docker-compose.yaml run --rm --no-deps vola vola demo-keysThen start the stack with the demo profile, which adds the seeder:
docker compose -f docker-compose.yaml --profile demo up -d # vola, vola-worker, postgres, redis, seederEncrypted files and keyrings also need the key and pepper files. The reverse proxy must allow WebSocket upgrades on /vola/udc/subscribe and a body of at least 6 MiB.
| Variable | Default | What it does |
|---|---|---|
VOLA_UI_DIR |
None (image: /app/ui) |
The built site; empty means API only |
VOLA_EXAMPLES |
false |
The demo routes; true needs both keys |
VOLA_DEMO_TENANT |
demo |
The tenant, created when missing |
VOLA_DEMO_INSTANCE_TYPE, VOLA_DEMO_INSTANCE_ID |
demo, 00000000-0000-4000-8000-000000000001 |
The one instance the site shows |
VOLA_DEMO_MAX_UPLOAD_BYTES |
5 MiB | The proxy’s upload cap |
VOLA_DEMO_TTL_HOURS |
24 | How long a visitor’s things live |
VOLA_DEMO_RATE_LIMIT |
60 | Writes per address per ten minutes |
VOLA_DEMO_PURGE_INTERVAL_MIN |
15 | 0 means never |
VOLA_PUBLIC_URL |
None | The origin share links are built on |
The operator’s guide is EXAMPLES-SITE.md.
v1.1.1released built 519e3dc