Repository navigation
Deploying on a VPS
🏠 Home › 🛡️ Operate › 🖥️ Deploying on a VPS
Run the Compose stack on a server you rent, then update it, back it up, move it and change its password without losing data.
Warning
Pre-1.0 and unhardened. Read the security status first. A VPS is on the internet, so treat this as a test deployment until that section says otherwise.
| ✅ Safe any time | ⛔ Deletes data |
|---|---|
docker compose up -d --build / make vps-update
|
docker compose down -v / make docker_down_v
|
docker compose restart / stop / down
|
make dev-reset |
| rebuilding or recreating any container |
docker volume rm … / docker volume prune
|
| a VPS reboot | docker system prune --volumes |
make backup |
the window's Settings → Reset (its local folder) |
# once
git clone https://github.com/fiwon123/eznit.git /srv/eznit && cd /srv/eznit
make vps-init DOMAIN=eznit.example.com # add PROXY=traefik if Traefik runs there
docker compose up -d --build
# day to day
docker compose up -d # start
docker compose down # stop; the data is kept (never add -v)
# update
make vps-update # back up, then the newest release
make vps-autoupdate # or: let the server do it every hourThe rest of this page explains what those commands do.
Containers are disposable, and the data is not in them. It lives in two Docker named volumes, which outlive every container:
flowchart LR
subgraph c["Containers: rebuilt on every update"]
API["⚙️ api"]
DB["🐘 db"]
WEB["🌐 web"]
MIG["🔁 migrate"]
end
subgraph v["Volumes: your data, kept"]
PG[("postgres-data<br/>accounts · records · templates")]
AD[("api-data<br/>uploaded bytes")]
end
DB --- PG
API --- AD
API --> DB
MIG --> DB
WEB --> API
classDef ctr fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef vol fill:#fef3c7,stroke:#d97706,color:#78350f
class API,DB,WEB,MIG ctr
class PG,AD vol
| Volume | Holds |
|---|---|
🐘 postgres-data
|
the database: accounts, file records, templates, sessions |
📁 api-data
|
the uploaded bytes (/data/uploads in the api container) |
Important
A file record in the database points at bytes in api-data. Back up and
restore the two together. A database without its uploads lists files that are
gone.
curl -fsSL https://get.docker.com | sudo sh # Docker + the Compose plugin
sudo usermod -aG docker "$USER" # then log out and back in
sudo apt install -y git make
sudo ufw allow 22 && sudo ufw allow 80 && sudo ufw allow 443 && sudo ufw enablePoint your domain's DNS A record at the server's address. Ports 80 and 443
must be free: stop any web server the image came with (sudo systemctl disable --now nginx apache2 caddy).
sudo mkdir -p /srv/eznit && sudo chown "$USER" /srv/eznit
git clone https://github.com/fiwon123/eznit.git /srv/eznit
cd /srv/eznit
make vps-init DOMAIN=eznit.example.commake vps-init runs make setup, then:
| Step | What it does |
|---|---|
| 🔑 Password | Replaces the example database password with a random one, only while no database exists yet. It never prints it: copy secrets/db_password.txt into your password manager. |
| 🔒 Private ports | Sets API_BIND=127.0.0.1 and WEB_BIND=127.0.0.1 in .env, so only HTTPS is public. Docker's firewall rules bypass ufw, so the bind address is what keeps a port private. |
| 🌐 HTTPS | Sets DOMAIN and COMPOSE_PROFILES=https, which turns on the caddy service. Caddy gets and renews the certificate by itself. |
| 🛰️ Client address | Sets TRUST_PROXY=true, so the login rate limit counts each visitor, not the proxy. |
Running it again is safe. It changes only the domain and what is not set yet.
Note
Traefik or another proxy already on the server? Add PROXY=traefik or
PROXY=none, see Behind Traefik or your own proxy.
Caution
Postgres applies the password only when it creates the volume. That is why
vps-init will not replace it once a database exists. Changing it later is a
separate procedure, below.
docker compose up -d --build
docker compose ps # api "healthy", migrate "exited (0)", caddy "running"-d keeps it running after you log out, and Docker starts it again after a reboot.
Open https://eznit.example.com. The first visit can take a few seconds while
Caddy fetches the certificate.
flowchart LR
U["👤 Browser / CLI"] -->|"HTTPS :443"| C["🔒 caddy"]
C -->|"web:80"| W["🌐 web (nginx)"]
W -->|"/v1"| A["⚙️ api :4000"]
A --> D[("🐘 db")]
classDef pub fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
classDef priv fill:#dcfce7,stroke:#16a34a,color:#14532d
class U,C pub
class W,A,D priv
Important
The first account to sign up becomes the instance's admin. Sign up yourself before you share the address.
In the desktop window, open Settings → Server, type
https://eznit.example.com and click Connect.
If the server already runs a reverse proxy for other projects, it owns ports 80 and 443, so the built-in Caddy has to stay off. Pick the proxy when you initialise:
| Command | HTTPS comes from |
|---|---|
make vps-init DOMAIN=… |
🔒 the built-in caddy service (the default) |
make vps-init DOMAIN=… PROXY=traefik |
🚦 your Traefik, through labels on the web service |
make vps-init DOMAIN=… PROXY=none |
🛠️ any proxy you configure, pointed at 127.0.0.1:5173
|
Then start it as usual with docker compose up -d --build. Running vps-init again
with another PROXY switches between them.
PROXY=traefik writes docker-compose.override.yml next to
docker-compose.yml. It puts web on Traefik's network and adds the router labels
for DOMAIN.
Tip
Put every server-specific Compose change in docker-compose.override.yml,
never in docker-compose.yml. Compose merges the override into every command
(up, down, ps) automatically. It is gitignored, so git fetch,
a release checkout and make vps-update never collide with it. An edit to
docker-compose.yml makes vps-update refuse to run.
If your Traefik uses other names than the defaults, set them in .env:
| Variable | Default | Must match |
|---|---|---|
TRAEFIK_NETWORK |
traefik |
the Docker network Traefik is on (docker network ls) |
TRAEFIK_ENTRYPOINT |
websecure |
the HTTPS entrypoint in Traefik's configuration |
TRAEFIK_CERTRESOLVER |
letsencrypt |
the certificate resolver in Traefik's configuration |
vps-init warns when the network does not exist. It never overwrites an existing
override: delete the file and run it again for a fresh one, or edit it freely.
Important
The override lists both default and traefik under networks. default
is how web reaches the API. With traefik alone, every page loads and every
request fails.
PROXY=none leaves the built-in Caddy off and writes no override. Send
https://DOMAIN to 127.0.0.1:5173. With Caddy on the host:
eznit.example.com {
reverse_proxy 127.0.0.1:5173
}The proxy must set X-Forwarded-For, which Caddy, Traefik and nginx do by default.
Otherwise the login rate limit counts every visitor as one.
cd /srv/eznit
make vps-update # the newest release
make vps-update TAG=v0.39.0 # or a specific oneflowchart LR
A["▶️ Start the current version"] --> B["💾 make backup"]
B --> C["🏷️ Check out the release tag"]
C --> D["🔁 docker compose up -d --build<br/>(migrate adds what is new)"]
B -.->|"fails"| X["⛔ Stop: nothing changed"]
classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class A,B,C,D step
class X stop
The containers are rebuilt and the volumes are kept. migrate applies only the
migrations the database does not have yet. Migrations are append-only, so an
update adds to the schema and never rewrites what is there. Expect a few seconds
of downtime.
vps-update refuses to run when:
- tracked files have local changes, because the checkout would overwrite them;
- the backup fails;
- the release is older than the one running (see the warning below).
Note
The server runs a release tag, not a branch, so git pull does not apply
there: git status says "HEAD detached at v0.39.0", which is expected.
vps-update does the fetch and the checkout.
Warning
Never run a down migration on a deployment you care about. A down migration
drops columns and tables. To go back to an older release, restore the backup
vps-update took before the update.
The server can install each new release by itself:
make vps-autoupdate # on: checks once an hour
make vps-autoupdate-status # on or off, paused or not, the last log lines
make vps-autoupdate-off # offIt pulls: every hour the VPS runs git fetch against the public repository,
and when a newer release exists it runs make vps-update. Nothing about the server
is stored on GitHub (no address, no SSH key, no workflow, no secret), and nothing
new can connect to the server.
flowchart TD
T["⏰ Every hour (cron)"] --> F["🏷️ Fetch the release tags"]
F --> N{"Newer release?"}
N -->|"no"| Z["😴 Log 'up to date'"]
N -->|"yes"| U["💾 Backup, then 🔁 make vps-update"]
U --> H{"API answers?"}
H -->|"yes"| OK["✅ Log 'updated'"]
U -.->|"fails"| P["⏸️ Pause and wait for you"]
H -.->|"no"| P
classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class T,F,N,U,H step
class Z,OK ok
class P stop
| Rule | Why |
|---|---|
🏷️ Only release tags (vX.Y.Z) are installed, never a branch |
a tag has passed the release CI |
| 💾 A backup comes first, and a failed backup stops it | every update can be undone with make restore
|
| 🔒 One run at a time | a slow build never overlaps the next check |
| ⏸️ Any failure pauses it until you look | a broken release is not retried every hour |
| ↩️ No automatic rollback | going back is a restore, and a restore replaces data. You decide. |
Everything is written to backups/auto-update.log.
make vps-autoupdate-status # what failed, and the log
docker compose ps -a # which container is not running
docker compose logs --tail 50 api # why| What you find | What to do |
|---|---|
| a temporary problem (disk full, Docker restarted mid-build) | fix it, make vps-update to finish, then make vps-autoupdate-resume
|
| the new release itself is broken |
make restore BACKUP=backups/<the one taken before the update>, then report it. Keep it paused until a fixed release exists. |
Note
A network error while fetching does not pause it. That run is skipped and the next hour tries again.
make backup # → backups/<UTC timestamp>/database.dump + uploads.tgzscripts/backup.sh does the same without make. The stack must be running.
| File | What it is |
|---|---|
🐘 database.dump
|
a pg_dump custom-format dump made inside the db container, so the password is never read on the host. It is portable across Postgres versions and machines. |
📁 uploads.tgz
|
the contents of the uploads volume, with file ownership kept |
Caution
A backup on the same disk is not a backup. Copy it off the machine, on a schedule.
# crontab -e: back up at 03:00, copy it off the machine, keep two weeks locally
0 3 * * * cd /srv/eznit && make backup >> backups/backup.log 2>&1 && rclone copy backups remote:eznit-backups
30 3 * * * find /srv/eznit/backups -mindepth 1 -maxdepth 1 -type d -mtime +14 -exec rm -rf {} +Tip
Restore one once, on purpose, before you need it. A backup you have never restored is a guess.
make restore BACKUP=backups/2026-11-17T030000Zflowchart TD
A["🔎 Check the folder<br/>database.dump + uploads.tgz"] --> B["🛟 Safety backup<br/>backups/before-restore/"]
B --> C["⏸️ Stop api"]
C --> D["🐘 Empty the schema,<br/>load the dump"]
D --> E["📁 Empty the uploads,<br/>unpack the archive"]
E --> F["🔁 Run migrate<br/>(older backup → current schema)"]
F --> G["▶️ Start api"]
A -.->|"missing file"| X["⛔ Stop: nothing changed"]
B -.->|"fails"| X
classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef safe fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class A,C,D,E,F step
class B,G safe
class X stop
The restore replaces the current data, which is why it takes a safety backup
first and stops if that fails. If a later step fails, it still starts api again
and says so.
- Do a first deploy there (same release, its own password).
-
docker compose up -donce, so the volumes exist. - Copy the backup folder over.
make restore BACKUP=…
Use this for a corrupted volume, or for a new major Postgres version, which cannot read an older version's data folder:
make backup
docker compose stop api
docker compose rm -sf db
docker volume rm eznit_postgres-data # <project>_postgres-data; the project is `name:` in docker-compose.yml
docker compose up -d db migrate api web
make restore BACKUP=backups/<the one you just took>Caution
Editing secrets/db_password.txt alone breaks the deployment. Postgres
stored the old password when it created the volume, so the API and migrate
would start sending a password it does not know.
Change it in the database first, then in the file:
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'
# ALTER USER root PASSWORD 'the-new-password';
# \q
# put the same value in secrets/db_password.txt (chmod 600), then:
docker compose up -d --force-recreate apipsql inside the container connects over the local socket, which needs no
password. That is also the way back in if the file and the database ever disagree.
| 👑 The first account is the admin | Only an admin may list, change or delete other accounts. No route grants the flag. |
| 🐘 The database user is a superuser |
root is the user the Postgres image creates, and the API connects as it. That is acceptable only while the database answers on loopback and the Compose network. |
| 🔑 The server itself | SSH keys only (PasswordAuthentication no, PermitRootLogin no), a normal user with sudo, unattended security updates, and a firewall allowing 22, 80 and 443. |
| 🙈 Secrets stay out of git |
.env and secrets/db_password.txt are gitignored and mode 600. Keep the password in a password manager, not next to the dump. |
Promote another account to admin:
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "UPDATE users SET is_admin = true WHERE email = '\''someone@example.com'\'';"'Warning
Never set DB_BIND=0.0.0.0 on a VPS. It would put a Postgres superuser on the
internet.
The release bundle's Local server runs the API as a process, not as the api
container, so its uploads are in the folder API_UPLOADS names (./uploads by
default), not in a volume. To back it up, dump the database the same way and
copy that folder:
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > database.dumpmake backup and make restore are for the Compose deployment above.
| ⚙️ Configuration | every bind address and variable |
| 🧯 Troubleshooting | when the database or a port refuses |
| 📦 Releases | which tag to deploy, and how to verify it |
🏠 Home · 🚀 Getting Started · 🧯 Troubleshooting · 📦 Downloads · 🐛 Report an issue
This wiki is generated from docs/wiki/ in the repository — edit it there, through a pull request. A change made only here is overwritten by the next make wiki_push.
🚀 Start
📖 Reference
🛡️ Operate
🛠️ Build
🧭 Project