A small, invite-only community video-hosting web application built with Python and FastAPI. The default page title is Atomiser Site and is editable in the admin settings UI.
- Invite-only registration — invite links with expiry, a use limit, an admin-only note, and revocation.
- Role-based access — Configurator, Admin, and Member roles.
- Authentication — email/password with Argon2id, TOTP two-factor, and WebAuthn passkeys.
- Brute-force protection — in-app sliding-window throttling and account lockout on the auth endpoints, independent of the nginx rate-limit zones.
- Session management — users see every device signed in to their account and can revoke any of them; admins can sign a user out everywhere.
- Protected video hosting — only authenticated users can upload or view content.
- Transcoding with a durable queue — uploads are transcoded into 720p, 480p, and 360p MP4s with a poster thumbnail. Jobs live in the database, so a restart mid-transcode resumes instead of stranding the video, and failures retry.
- Quality selection — the player offers every rendition and remembers the viewer's choice, preserving playback position when switching.
- Live processing feedback — a video still transcoding shows progress and swaps in the player automatically when it is ready.
- Secure streaming — videos are served through the app with nginx X-Accel-Redirect so the file system is never exposed directly.
- Activity feed — default landing page shows the latest site-visible videos.
- User profiles — each profile lists videos posted by that user; owners can edit, re-scope, or delete their own videos.
- Admin dashboard — storage use per user, videos by status, recent registrations, and one-click retry of failed transcodes.
- Audit log viewer — filter the recorded activity trail by action, user, and date range.
- Optional email — with SMTP configured, invites can be emailed, users can reset their own passwords, and members are notified when someone posts a new video. Without it the site behaves exactly as before: copy-paste invite links and admin-driven resets.
- New-video notifications — members are emailed when a video goes live, with a one-click unsubscribe link in every message. Delivery runs through a durable queue with retries, so a mail server hiccup does not lose notifications.
- Install Python 3.12+ and ffmpeg.
- Clone the repository and create a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt
- Copy
.env.exampleto.envand setSECRET_KEYto a long random value. - Bootstrap the first Configurator account:
python scripts/bootstrap.py --email you@example.com --name "Your Name" --password "A Strong Password"
- Run the app:
uvicorn app.main:app --reload
- Open http://127.0.0.1:8000/ and log in.
- Configurator — full access; can change site title, manage roles, and delete anything.
- Admin — manage users, invites, and content; cannot change global site settings or demote Configurators.
- Member — upload and view videos; edit own profile.
The recommended stack is a Linux VPS/bare-metal server with nginx as a reverse proxy. A detailed, step-by-step guide is in docs/DEPLOYMENT.md; the high-level steps are:
- Create an unprivileged user and deploy the code to
/opt/atomiser. - Create
/etc/atomiser/atomiser.envfrom.env.exampleand setENV=production,SECRET_KEY, paths, etc. - Create the data directories and set permissions (systemd creates the socket directory
/run/atomiseritself on every start):sudo mkdir -p /opt/atomiser/data /opt/atomiser/uploads sudo chown -R atomiser:atomiser /opt/atomiser
- Bootstrap the first Configurator:
sudo -u atomiser venv/bin/python scripts/bootstrap.py --email you@example.com --name "Your Name" - Install
nginx/atomiser.serviceto/etc/systemd/system/atomiser.serviceand start the service:sudo systemctl daemon-reload sudo systemctl enable --now atomiser - Obtain TLS certificates (e.g. Let's Encrypt with certbot) and install
nginx/atomiser.conf. - Reload nginx.
See docs/DEPLOYMENT.md for TLS setup, backup strategy, troubleshooting, and the full security checklist.
Atomiser runs with no mail server by default. Set SMTP_HOST and SMTP_FROM
in your .env to additionally enable:
- Emailed invites — an optional "email it to" field on the invite form. The link is still shown on screen, so a delivery failure never loses the invite.
- Self-service password reset —
/auth/forgotsends a single-use link that expires afterPASSWORD_RESET_TTL_MINUTES. Completing a reset signs the account out of every device. - New-video notifications — when a video finishes transcoding and is visible
to the site, every subscribed member is emailed a link to it. Members are
subscribed by default and can opt out from their profile or from the
unsubscribe link carried by every notification (including the native
"unsubscribe" button in mail clients that support RFC 8058). Set
NOTIFY_NEW_VIDEOS=falseto disable the feature for the whole site.
Set SITE_URL as well. Password reset and invite links prefer it over the
request's Host header, and notifications require it: the sending worker
runs outside any request, so without it there is no hostname to build links
from and no notification will be sent. The admin dashboard shows a warning if
this is the case.
Notifications are delivered through a queue rather than sent inline, so a fan-out to a large membership never blocks a transcode, failures retry with a backoff, and a restart mid-send resumes. The admin dashboard reports how many messages are queued, sent and undeliverable.
With SMTP unset, /auth/forgot explains that an admin performs resets, the
invite form omits the email field, the profile page hides the notification
setting, and nothing is ever queued.
- All cookies are
HttpOnly/Securein production and useSameSite=Lax. - Forms include CSRF tokens using the double-submit cookie pattern.
- Uploaded files are inspected with magic-byte detection before being accepted.
- Video files are stored outside the web root and are only accessible through authenticated app endpoints or nginx internal redirects.
- Passwords are hashed with Argon2id.
- TOTP uses a server-side secret per user; passkey credentials are bound to the origin.
- Failed sign-ins are throttled per email address and per source IP, and an account locks after repeated failures. An unknown address is throttled identically to a real one, so the response cannot be used to enumerate accounts.
- Password reset tokens are stored only as hashes, are single-use, and expire.
Copyright (C) 2026 James Chapman / OMG-Software
Licensed under the GNU Affero General Public License v3.0 — see
LICENSE for the full text.
Atomiser is intended to be run as a network service, so the AGPL's section 13 matters here: if you run a modified version and let other people use it over a network, you must offer those users the source of your modified version. Plain distribution of the source is covered by the usual GPL terms.