SELF-HOST · REQUIREMENTS
What you need to run it.
Six containers, one machine and Docker. A running install idles at about one gibibyte of memory with almost no CPU. Building the web image from source needs more than 3.8 GB.
Measured on one install · AGPL-3.0 · Docker Compose
REQUIREMENTS
| Containers | 6 |
|---|---|
| Memory to run | about 1 GiB |
| Memory to build | more than 3.8 GB |
| Database | PostgreSQL 16 |
| Needs | Docker and Compose |
Measured
The numbers we have, and where they come from.
One real install, running for 44 hours with two documents in it, on a virtual machine with 3.8 GiB.
- ≈1.0 GiBMemory, idleAll six containers together.
- 0 to 0.5%CPU, idleMeasured across the same six containers.
- >3.8 GBMemory to buildThe web image build was killed for lack of memory at 3.8 GB.
- 6ContainersDatabase, file store, converter, app, worker and web.
Container by container
Where the memory goes.
| Container | What it does | Idle memory |
|---|---|---|
| app | The API and the business logic | about 271 MiB |
| worker | Sends email and reminders | about 254 MiB |
| storage | The file store for signed PDFs, S3-compatible | about 176 MiB |
| gotenberg | Draws template pages to PDF | about 188 MiB |
| db | PostgreSQL 16 with row-level security | about 76 MiB |
| web | The app, the signing page and this kind of page | about 45 MiB |
Run or build
Two different jobs.
- MemoryAbout one gibibyte at idle
- CPUClose to nothing at idle
- PortsOnly the web container publishes a port; the rest talk on Compose's private network
- AddressPut HTTPS in front and set the public address
- MemoryMore than 3.8 GB: the web build was killed at 3.8 GB
- TimeThe build that failed ran for about three minutes first
- AdviceBuild on a bigger machine, or use a prebuilt image when one is published
- Not measuredThe exact minimum to build
What is not measured yet
We say so rather than guess.
Load
Memory and CPU with ten signers at once, or with the worker busy, have not been measured. The idle numbers are the lower bound.
Disk
Disk use depends on how many documents you keep. A signed PDF is small, and the database and file store sit in two named Docker volumes.
Other platforms
A Helm chart ships with requests of 256 Mi for the app and worker and 128 Mi for web. It has not been run on a cluster yet.
Settings you will meet first
A handful of lines in one file.
| Setting | What it does |
|---|---|
| KEYSTONE_PUBLIC_URL | The address people use. It goes into the links in emails, and the provider sends people back to it for single sign-on. |
| KEYSTONE_MASTER_KEY | Seals stored secrets and each workspace's file key. init.sh writes it. Lose it and sealed files cannot be opened. |
| RESEND_API_KEY | Your own mail provider key. Leave it empty to use your own SMTP server in Settings, Email. |
| KEYSTONE_MAIL_SENDER | The default From address until you verify your own domain. |
| KEYSTONE_TRUSTED_PROXY_HOPS | How many proxies sit in front, so the real address of a visitor is read correctly. |
| DOCUSTAY_TELEMETRY | Set to off to stop the one anonymous daily ping. |
Before you start
Four things to have ready.
1 / 4
Docker with Compose
Any machine that runs Docker and Docker Compose. The install is a folder of files in the repository.
2 / 4
A name and HTTPS
A domain you control and a reverse proxy with a certificate in front of the web container. Caddy, nginx and Traefik are covered in the docs.
3 / 4
A provider key, or your own SMTP server including Amazon SES, so signers get their emails. Without one Docustay says email is not set up.
4 / 4
A place for backups
Somewhere that is not this machine. The backup folder holds secrets, so keep it as private as the install itself.
What it sends
One anonymous ping a day, and you can turn it off.
Once a day an install sends a random install id, its version and five counts, never content. Set DOCUSTAY_TELEMETRY=off to stop it, or send the report by hand. A Pro licence is checked the same way and keeps working up to 30 days offline.
- Nothing of ours is inside the install: every key and certificate is made on your machine.
- It is an honour system, not copy protection.
- Install idrandom
- Versionthis one
Questions
Quick answers.
Can I run it on a small server?
A running install idles at about one gibibyte, so a machine with 2 GB can run it. Building the web image needs more than 3.8 GB, so build elsewhere or use a prebuilt image.
Does it need the internet?
It needs outbound access for email and for the licence check if you run Pro, and a Pro licence keeps working up to 30 days offline. The Community edition needs no licence check.
Which database does it use?
PostgreSQL 16, in its own container, with row-level security on every table that holds workspace data.
Where do I read the full steps?
In the documentation: the install, the reverse proxy guide, backups, upgrades, single sign-on and hardening each have a page.
Does a self-hosted install send my documents anywhere?
No. Documents, files and keys stay on your machine, and the only thing the install sends us is the optional anonymous daily ping of a random id, the version and five counts.