BillApe on your own server

A. Hetzner VPS (recommended)

You need a domain name, for example billape.yourdomain.nl, with an A record that points to your VPS's IP address. You set this at your domain provider.

1. Log in to the VPS: ssh root@YOUR_VPS_IP
2. Install Docker, once: curl -fsSL https://get.docker.com | sh
3. Get BillApe: git clone https://github.com/MrBeeAye/BillApp.git && cd BillApp/deploy
4. Make your settings file: cp .env.example .env, then open it with nano .env and fill in:
   • BILLAPE_DOMAIN=billape.yourdomain.nl
   • POSTGRES_PASSWORD= the output of openssl rand -hex 24
   • SYNC_TOKEN= the output of openssl rand -hex 32. Keep this one: every device needs it.
5. Start everything: docker compose up -d --build. The first time takes a few minutes.
6. If you use a firewall, open it for the web: ufw allow 80,443/tcp && ufw allow 443/udp
7. Open https://billape.yourdomain.nl and set up BillApe.
8. Go to Sync. The server address is already filled in. Paste the sync token and press Connect.
9. On your other devices, open the same address and choose I already use BillApe with a sync server.

On your phone: open the same address in Safari and tap Share → Add to Home Screen.

Mac app: it syncs with this server too. Choose I already use BillApe with a sync server on its welcome screen.

Updating later: cd BillApp && git pull && cd deploy && docker compose up -d --build

Using aaPanel?

If your VPS runs aaPanel with nginx, you don't need Docker. Download the ready-made files from the BillApe server files release, upload them in aaPanel and paste two prepared nginx settings. Step by step: the aaPanel guide.

B. UGREEN NAS (DH2300)

Browsers only allow BillApe's encryption on HTTPS pages, so a plain http://192.168.x.x address on your home network won't work. Choose one of these:

Option 1 (easiest): VPS for sync, NAS for a readable copy

1. In UGOS, use Docker → Image → postgres:17-alpine, set a password and map port 5432.
2. Create a database called billape_readable.
3. Make sure the VPS can reach the NAS, for example with Tailscale or WireGuard on both.
4. In the VPS's .env, set MIRROR_DATABASE_URL=postgres://postgres:NAS_PASSWORD@NAS_TAILSCALE_IP:5432/billape_readable
5. Run docker compose up -d again, then turn on Sync → Keep a readable copy in BillApe.

Option 2: everything on the NAS

1. In UGOS, enable Docker and SSH.
2. Install Tailscale on the NAS and on your devices, and turn on HTTPS certificates in the Tailscale admin.
3. Follow the VPS steps above, with the NAS's Tailscale name (nas-name.tailnet-name.ts.net) as BILLAPE_DOMAIN.

How your data is protected

• Every record is encrypted on your device with AES-256-GCM before it is sent. The key comes from your password (PBKDF2-SHA-256, 600,000 rounds).
• The sync server and PostgreSQL only ever store the encrypted data. They can't read it.
• PostgreSQL is never open to the internet. Connect from your computer with an SSH tunnel: ssh -L 5432:127.0.0.1:5432 root@YOUR_VPS_IP
• The optional readable PostgreSQL copy is not encrypted. It is off by default.

Backing up the server

docker compose exec db pg_dump -U billape billape > billape-server.sql

This file is still encrypted: only your BillApe password can open the data inside.

Need help? Get in touch.