Self-hosting
Run Henglos IO on your own machine or server, with Docker.
Henglos IO is self-hosted: the hosting (the API, accounts, workflows, packages) and the studio (the web app) run on your machine or server, and your drivers connect to it.
With Docker Compose
The repository's deploy/docker folder has everything: the two images, with
Caddy in front to serve them on one address.
Browser ──▶ Caddy ──▶ /io/* ──▶ hosting (API, sockets, collaborative editing)
└─▶ the rest ──▶ studioConfigure
cd deploy/docker
cp .env.example .envFill in the two secrets in .env — openssl rand -hex 32 makes one:
HIO_JWT_SECRET=…
HIO_SECRETS_KEY=…Every setting is in Configuration.
Start
docker compose up -dOpen it
Go to http://<this machine>. With no account yet, it opens the setup page — the account you
create there is the instance's first user. Afterwards it goes straight to the login.
With a domain (HTTPS)
Point the domain's DNS to the machine, open ports 80 and 443, and set it in .env — Caddy gets a
certificate from Let's Encrypt on its own:
HIO_SITE_ADDRESS=hio.example.comdocker compose up -dThe images
| Image | Port | What it is |
|---|---|---|
henglosio/hosting | 3333 | The API (/io/api), the sockets (/io/ws) and the collaborative editing (/io/collab). |
henglosio/studio | 5173 | The web app. |
Both are tagged by version (1.0.0-beta.1) and have a healthcheck.
- The hosting keeps everything in
/data— the database (SQLite) and the installation's id: mount a volume there. On every start it brings the database up to date, then serves. - The studio calls the hosting on its own origin (
/io/*), so the two must be served behind one address — by Caddy, as above, or by your own reverse proxy or Ingress, sending/io/*to the hosting (WebSockets included) and the rest to the studio.
Without Compose, the same thing by hand:
docker volume create hio-data
docker run -d --name hio-hosting -v hio-data:/data \
-e HIO_JWT_SECRET=… -e HIO_SECRETS_KEY=… \
henglosio/hosting:1.0.0-beta.1
docker run -d --name hio-studio henglosio/studio:1.0.0-beta.1
# …and a reverse proxy in front of both, as described above.Updates
Change the images' tags in docker-compose.yaml to the new version, then:
docker compose pull
docker compose up -dThe database is brought up to date when the hosting starts.
Backups
Everything is in the hio-data volume. Stop the hosting and copy it:
docker compose stop hosting
docker run --rm -v henglos-io_hio-data:/data -v "$PWD":/backup alpine \
tar czf /backup/hio-data.tgz -C /data .
docker compose start hostingKeep HIO_SECRETS_KEY with the backup
Saved credentials are encrypted with it — a backup restored with another key has them unreadable.
From source
To work on Henglos IO itself, the repository is a pnpm + Turborepo monorepo:
pnpm install
cp apps/hosting/example.env apps/hosting/.env
pnpm --filter hosting db:push
(cd apps/hosting && docker compose -f docker-compose.dev.yaml up -d) # a local registry (Verdaccio) on :4873
pnpm dev| Service | Port | What it is |
|---|---|---|
| Studio | 5173 | The web app |
| Hosting | 3333 | The API, under /io |
| Package registry | 4873 | A local Verdaccio for your own packages |
The repository's Caddyfile serves both at https://hio.localhost (caddy run).