One-liner (fresh VPS)
/opt/slideless, generates
secrets into .env (mode 600), starts the stack, and configures UFW
(22/80/443). With a domain, finish by wiring the reverse proxy
(reverse-proxy.md) and setting TRUST_PROXY=true in
.env.
Without a domain
The app is published on127.0.0.1 only and the app port stays closed in
the firewall. Reach the dashboard through an SSH tunnel:
0.0.0.0 bind is
reachable from the internet no matter what the firewall says — the bind
address is the only control that actually holds. And the wizard request
carries the owner password and the setup token, so the server itself refuses
to complete setup over plaintext HTTP on a non-loopback origin
(403 insecure_transport).
To publish anyway on a trusted private network, pass --expose-port: it
binds 0.0.0.0, opens the port in ufw, and sets ALLOW_INSECURE_SETUP=true.
It needs to know the address this host is reached on, which it reads from
hostname -I; on a host where that prints nothing it stops and asks, so pass
HOST_IP=<address> alongside it rather than letting an empty value become the
instance’s PUBLIC_BASE_URL.
Manual (any machine with Docker)
setup.sh is idempotent: with an existing .env it just (re)starts.
.env carries the host publication settings, and update.sh / restore.sh
read them back — so a custom port survives an upgrade instead of reverting:
First boot
The dashboard shows the setup wizard: instance name + owner account. The wizard always requires a setup token — this stops a stranger racing you to own a freshly exposed instance.setup.sh and the one-liner installer
generate one into .env; a container started without SETUP_TOKEN (a
hand-written .env, a plain docker run) generates its own at first boot,
writes it to /data/setup-token inside the data volume and prints it in
the container log (docker compose logs app | grep setup). Setup is never
first-come-first-served. It runs exactly once; afterwards the endpoint
answers 410 Gone and the generated token file is removed.
Setup is also refused over plaintext HTTP on a non-loopback PUBLIC_BASE_URL
(403 insecure_transport) — the request carries the owner password and the
token. Use https, an SSH tunnel to the loopback bind, or the deliberate
ALLOW_INSECURE_SETUP=true opt-in.
Teammates join via invitations (Members → Invite). Every invitation yields a
copyable accept link — SMTP is never required. To also send invitation
emails, configure an email driver in .env
(env-reference.md).
What’s running
The app container is stateless by design — all state lives in Postgres and
the
/data volume. Migrations apply automatically at boot under an advisory
lock; set AUTO_MIGRATE=false to run them manually (the instance then
refuses readiness while behind).
Deck images
The dashboard shows a still image of each deck version on its card. The image is made by an optional renderer container,slideless-renderer,
that holds a sandboxed headless Chromium and nothing else: no database, no
file storage, no secret but the one it shares with the app. Without it, the
cards show a plain block and everything else works the same.
On by default for a new install. setup.sh (and so install.sh) pulls
the renderer and runs its self-check on the host before the first start.
When Chromium’s sandbox starts there, it turns the images profile on and
writes the renderer’s two settings into .env; when it cannot, the install
goes on without pictures and says why. install.sh --no-images (or
SLIDELESS_IMAGES=off ./setup.sh) installs without them.
Turning it on or off later, on an install made before pictures were on
by default or after --no-images:
on writes three lines into .env and restarts the stack:
.env when the sandbox cannot start on the host,
and 4 when the renderer image cannot be pulled. off removes the profile and
the URL (the secret stays, for a later on). The renderer image follows
RENDERER_IMAGE like the app follows APP_IMAGE; update.sh pulls both.
The renderer is reached on the compose network only (no published port).
After a push, the app hands the new version to it with a one-time key; the
renderer pulls the version’s files from the app with that key, captures the
first page, and puts the image back with the same key. The app never waits
for it: a version whose image is not there yet shows a plain block, and the
renderer can be added, stopped or upgraded at any time.
What it costs. The renderer image is about 920 MB on disk, 334 MB of it
the browser. Each capture takes about one second of CPU and 200 to 300 MB of
memory while it runs, one at a time, with a queue of four.
The seccomp profile beside the compose file. Chromium protects the
renderer from a deck’s script with its own sandbox, and that sandbox needs
Linux user namespaces, which Docker’s default seccomp profile forbids.
deploy/seccomp-chromium.json is Docker’s default profile with that one
permission added (the namespace calls, for a process without
CAP_SYS_ADMIN), and docker-compose.yml applies it to the renderer
service, never to the app. The renderer refuses to start where the sandbox
cannot: its log says so and the container restarts until the profile is in
place (images.sh on runs the same check first, so it never turns on a
renderer that cannot start). There is no setting that runs Chromium without its sandbox. Never use
seccomp=unconfined in its place.
To check a host, run the renderer image’s self-check with the profile:
SLIDELESS_URL=http://app:3000, the shared secret, LOG_LEVEL). The rest
has defaults and is rarely changed:
While it is off (
./scripts/images.sh off, or the renderer stopped), the
app answers that it makes no images and the cards show a plain block;
versions pushed meanwhile get their image once the renderer is back.
Other runtimes.
- Hostinger’s one-file template (hostinger.md) carries
the renderer too. A single downloaded compose file cannot ship the seccomp
profile, so there the renderer keeps Docker’s default profile and holds
only the two capabilities that profile ties the namespace calls to
(
cap_drop: ALL,cap_add: [SYS_ADMIN, SYS_CHROOT]), as the non-root user withno-new-privilegesand a read-only root: its processes hold no effective capability, and Chromium’s own sandbox stays on. That filter is wider than the profile’s (the calls Docker’s default profile opens withSYS_ADMINbecome reachable, the kernel still refusing every privileged one), which is why the standard install keeps the profile. - Kubernetes: run the renderer as its own deployment with a seccomp
profile that allows the same calls (a
Localhostprofile built fromdeploy/seccomp-chromium.json), reachable from the app pods only, withSLIDELESS_URLpointing at the app service.Unconfinedis not recommended: it lifts every syscall filter to allow three calls. - Cloud Run: a second service on the second-generation execution
environment (it allows the namespaces the sandbox needs), with no public
invoker: the app’s service account is the only one allowed to call it, and
SLIDELESS_RENDERER_GOOGLE_AUTH=trueon the app makes every hand-off carry a Google identity token for the renderer’s URL (inX-Serverless-Authorization, beside the shared secret). The renderer keeps its CPU while its queue drains (the capture runs after the202), with concurrency 1, and scales to zero between captures, since the app hands a job over and never polls.SLIDELESS_URLon the renderer is the app’s public URL: the one-time key is what the app checks.