DEV Community

konsongong
konsongong

Posted on Originally published at vpsfolio.pages.dev

Self-Host Actual Budget with Docker: A Practical Guide

This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.

What Actual Budget does and what it needs

Actual Budget is a local-first personal finance app built around envelope budgeting. The server component (actualbudget/actual-server) stores your budget files and syncs changes between devices, while the client runs in your browser or as a desktop app. Everything is open source and written in Node.js.

The official Docker image is a single Node process. It does not need a separate database or cache container — budget data lives in files under /data. That makes the deployment simple: one container, one named volume, one port. The upstream project does not publish a minimum memory figure, so plan based on workload: an idle instance with a few budgets is tiny, but heavy imports, large transaction histories, and multiple concurrent sync clients will push memory and CPU up. A 1 GB VPS is a reasonable starting point for personal use; watch docker stats after a month of real data.

The upstream docker-compose.yml in the repo is for development only (bind-mounts the source tree, exposes port 3001, no persistence). Do not use it in production. The published image actualbudget/actual-server:latest is what you want.

Prerequisites, ports, and volume constraints

  • A Linux VPS with Docker Engine 24+ and the Compose plugin (docker compose version).
  • A domain name pointed at the server if you want HTTPS. You can test on 127.0.0.1:5006 over an SSH tunnel first.
  • Port 5006 is the container's HTTP port. Bind it to localhost and let a reverse proxy terminate TLS.
  • One named volume for /data. This holds the SQLite database, budget files, and server config. Back it up; losing it means losing your budgets.
  • No external database, Redis, or message queue is required.

Actual's server has no built-in user accounts beyond a single server password you set on first run. Treat the volume and the password as the entire security boundary.

Production Docker Compose setup

Create a directory and drop in the compose file and env file.

mkdir -p /opt/actual && cd /opt/actual
cat <<'EOF' > compose.yml
services:
  actual:
    image: actualbudget/actual-server:latest
    container_name: actual
    restart: unless-stopped
    environment:
      TZ: ${TZ:-UTC}
    ports:
      - "127.0.0.1:${ACTUAL_PORT:-5006}:5006"
    volumes:
      - actual_data:/data
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:5006/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

volumes:
  actual_data:
EOF
Enter fullscreen mode Exit fullscreen mode

Generate the env file. The only secret Actual itself needs is the server password, which you set through the web UI on first launch — but keep it in your password manager, not in .env. Use .env for non-secret settings:

cat <<'EOF' > .env
TZ=UTC
ACTUAL_PORT=5006
EOF
Enter fullscreen mode Exit fullscreen mode

If you plan to run behind a reverse proxy on the same host, leave ACTUAL_PORT at 5006 and point the proxy at 127.0.0.1:5006. To test without a domain, open an SSH tunnel from your laptop:

ssh -L 5006:127.0.0.1:5006 user@your-vps
Enter fullscreen mode Exit fullscreen mode

Then visit http://localhost:5006. Do not change the bind address to 0.0.0.0 on a public VPS — you would be serving budgets over plain HTTP.

Start the stack:

docker compose up -d
docker compose logs -f actual
Enter fullscreen mode Exit fullscreen mode

You should see the server report it is listening on port 5006. The first visit prompts you to set a server password. Pick a long random one (openssl rand -base64 24) and store it in your password manager. There is no password reset flow that doesn't involve wiping the volume.

Reverse proxy, HTTPS, and first-run hardening

Actual is a single-page app that talks to its own API over the same origin. It uses WebSockets for live sync between devices, so your proxy must forward Upgrade and Connection headers. It also serves large budget file uploads during import, so bump the body size limit above the default 1 MB.

Caddy example (/etc/caddy/Caddyfile):

budget.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:5006 {
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-For {remote_host}
    }
    request_body {
        max_size 100MB
    }
}
Enter fullscreen mode Exit fullscreen mode

Nginx equivalent:

server {
    listen 443 ssl http2;
    server_name budget.example.com;
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:5006;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 3600s;
    }
}
Enter fullscreen mode Exit fullscreen mode

First-run hardening checklist:

  1. Set the server password immediately after the container is up. Do not leave the instance reachable without one, even briefly.
  2. Confirm HTTPS works end-to-end before you import real data. Actual's sync client will happily talk to plain HTTP, but you don't want your bank transactions on the wire.
  3. If you don't need public access, put the proxy behind an IP allowlist or a VPN (WireGuard/Tailscale). Actual works fine over a private network.
  4. Keep the container bound to 127.0.0.1. If you ever need to expose it directly, do it through the proxy, not by changing the port mapping.

Updating, backups, and common pitfalls

Update to the latest release:

cd /opt/actual
docker compose pull
docker compose up -d
docker compose logs --tail=50 actual
Enter fullscreen mode Exit fullscreen mode

Actual's server is generally forward-compatible with budget files, but the client and server should be on the same version. Update the server first, then reload the web client. If you use the desktop app, update it too.

Back up the actual_data volume. A cold copy is safest:

docker compose stop actual
docker run --rm -v actual_actual_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/actual-$(date +%F).tar.gz -C /data .
docker compose start actual
Enter fullscreen mode Exit fullscreen mode

Adjust the volume name if your project directory differs (docker volume ls | grep actual). Copy the tarball off the VPS. Restoring is the reverse: stop the container, extract into the volume, start it.

Two pitfalls worth knowing:

  • The dev compose file is not production. The repo's docker-compose.yml bind-mounts .:/app and runs on port 3001 with restart: 'no'. If you copy it, your data lives in the source tree and disappears on rebuild. Use the published image and a named volume.
  • Nightly images can corrupt budgets. The Fly.io docs explicitly warn that actualbudget/actual-server:nightly may have known or unknown issues that could corrupt your budget. Stick to latest unless you're actively testing and have a recent backup.

Also note: the server has no multi-user auth. Anyone with the URL and the password has full access to every budget on the instance. If you share the instance, share the password deliberately.


Measured in our sandbox run: total memory 148.4 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 148.4 MB; published port(s) 5006; HTTP probe returned 200. The run took 60.3s including the image download.


Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.


Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/self-host-actual-budget-docker/.

Top comments (0)