What you need, and what you do not
Three things are required, one is optional, and two that people expect to need are not needed at all.
| What | Needed | Why |
|---|---|---|
| Node and a build toolchain | built | The SimpleX native addon compiles at install, which is the first runbook step |
| PostgreSQL with pgvector | built | The database URL is the only hard-required variable. pgvector is installed for the server own major version and the extension is created once as superuser, because the application role deliberately is not one |
| Debian, systemd, nginx, and a domain with real TLS | built | Passkeys need a secure context and a domain-based identity. Development runs on the seeded local preview console instead |
| Ollama and a GPU | idea | Optional. AI is opt-in twice: the environment flag ships false and the console setting must also be turned on. Without it the bot runs deterministic replies. The endpoint must be loopback or a private address, and a public one is refused at boot |
| Your own SimpleX server | declined | Not needed. The embedded core uses preset public relays, and self-hosted relay capture is explicitly parked |
| A separate daemon, or an open SimpleX port | declined | None exists. One process, the core embedded in-process, and the admin console binds loopback only |
a bare IP or plain HTTP would not
Ten steps, and the commands they take
The runbook, condensed. Every command is quoted exactly as it is written down, because a command edited for readability is a different command.
01Toolchain and system user
Install toolchain, create the system user
useradd --system … cinderella
02Source and build
The SimpleX native addon compiles at install
git clone https://github.com/saschadaemgen/cinderella.git /opt/cinderella && npm ci && npm run build
03Postgres
Role and owned database, pgvector extension as superuser
04The env file
Write the env file at 0600 with the database URL, admin credentials, session secret, media root, media secret and public origin
npm run hash-password
05Directories
Create the state, files and media directories owned by the service user
06Migrations
Run migrations under the env file
node dist/db/migrate.js
07The unit
Install the systemd unit, then enable and start it
systemctl enable --now cinderella
08Check it answers
It answers ok true
curl -fsS http://127.0.0.1:8787/healthz
09TLS and the vhost
TLS via certbot, install the repo nginx vhost
nginx -t && systemctl reload nginx
10First login
First login with the break-glass password, then Security, then register passkeys on at least two devices, then optionally disable break-glass
One note for a standalone host
the shipped vhost listens behind the operator's SNI stream splitter; a plain deployment edits the listen line
This is the runbook condensed for a reader deciding whether to run it. The repository carries the full version, and that is the one to follow with a terminal open.
Five steps, in order, after it starts
Two of these need the core already running, which is why the order is not a suggestion.
- Create the bot in the wizard: Identity, Contact handling, Group and role, Permissions, Review
- Press create the contact address, and the running core mints the bot link. Right after a restart it honestly reports the core still starting, about 10 s
- Add the bot as a contact from your own SimpleX app, and accept the request on the console. Every acceptance is manual
- Invite the bot into the group from your app, then press join the group on the console
- Turn on its plugins and assign which bot captures the room. Capture is on by default, and search, music and the rest ship off
nothing publishes until a member says so: consent is first-person and forward-only, so the archive starts empty and honest