The Minimal Service#

Create /etc/systemd/system/myapp.service:

[Unit]
Description=My Application
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node /opt/myapp/server.js
Restart=unless-stopped
RestartSec=5
WorkingDirectory=/opt/myapp

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable myapp
sudo systemctl start myapp

That is it. The app starts on boot, restarts on crash, and logs to journald.

Service Types#

Type=simple is correct for most things. The process you start is the service. But there are others:

# App forks into background (like old-school daemons)
Type=forking
PIDFile=/var/run/myapp.pid

# App signals readiness via sd_notify
Type=notify

# App is a one-shot script, not a long-running process
Type=oneshot
RemainAfterExit=yes

Use simple unless you have a specific reason not to. oneshot is useful for startup scripts that need to run once.

Environment Variables#

Three ways to pass them:

# Inline (good for a few vars)
[Service]
Environment=PORT=3000
Environment=NODE_ENV=production

# From a file (good for secrets)
[Service]
EnvironmentFile=/opt/myapp/.env

# Multiple files
[Service]
EnvironmentFile=/opt/myapp/.env
EnvironmentFile=/opt/myapp/.env.local

The EnvironmentFile approach keeps secrets out of the unit file. The unit file itself might be in version control or readable by any user. The .env file can be locked down with permissions.

Running As a Non-Root User#

[Service]
User=myapp
Group=myapp
ExecStart=/usr/bin/node /opt/myapp/server.js

Create the user first:

sudo useradd -r -s /usr/sbin/nologin -d /opt/myapp myapp
sudo chown -R myapp:myapp /opt/myapp

The -r flag creates a system user. -s /usr/sbin/nologin prevents interactive login.

Resource Limits#

Prevent a runaway process from eating all your RAM or CPU:

[Service]
MemoryMax=512M
CPUQuota=50%
TasksMax=100
LimitNOFILE=65535

MemoryMax kills the process if it exceeds the limit. CPUQuota throttles but does not kill. TasksMax limits the number of threads and child processes. LimitNOFILE sets the open file descriptor limit.

Restart Policies#

# Restart on any exit (crash, signal, clean exit)
Restart=always

# Restart on failure only (non-zero exit, signal)
Restart=on-failure

# Restart unless you explicitly stopped it
Restart=unless-stopped

I use unless-stopped for everything. It restarts on crashes but stays down when I manually stop the service for debugging.

Add rate limiting to prevent restart loops:

RestartSec=5
StartLimitIntervalSec=60
StartLimitBurst=5

This allows 5 restarts within 60 seconds. After that, the service enters a failed state and stops trying. Check what happened with journalctl -u myapp.

Logging#

systemd captures stdout and stderr automatically:

# View logs
journalctl -u myapp

# Follow in real time
journalctl -u myapp -f

# Last 50 lines
journalctl -u myapp -n 50

# Since last boot
journalctl -u myapp -b

# JSON output for parsing
journalctl -u myapp -o json-pretty

No log rotation config needed. journald handles it automatically based on disk space.

Dependencies and Ordering#

[Unit]
Description=My App
After=network.target postgresql.service
Requires=postgresql.service

After controls startup order. Requires means if PostgreSQL stops, myapp stops too. Use Wants instead of Requires for soft dependencies where your app can handle the other service being down.

Pre and Post Commands#

[Service]
ExecStartPre=/opt/myapp/migrate.sh
ExecStart=/usr/bin/node /opt/myapp/server.js
ExecStartPost=/usr/bin/curl -s http://localhost:3000/health
ExecStopPost=/opt/myapp/cleanup.sh

ExecStartPre runs before the main process. Good for database migrations or config validation. If it fails, the service does not start.

Debugging#

# Check service status
systemctl status myapp

# View full logs on failure
journalctl -u myapp -e --no-pager

# Check the actual unit file being used
systemctl cat myapp

# Verify unit file syntax
systemd-analyze verify myapp.service

The systemd-analyze verify command catches syntax errors without starting anything. Use it before reloading.

systemd is verbose and opinionated, but once you get past the initial learning curve, it handles all the edge cases that screen and nohup do not. Crashes, reboots, logging, resource limits, dependencies. Write the unit file once and forget about it.

Automatic TLS#

This is the obvious one. Caddy gets certificates from Let’s Encrypt automatically. But the real power is the DNS challenge with wildcard certs:

{
  acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

*.example.dev {
  tls {
    dns cloudflare {env.CLOUDFLARE_API_TOKEN}
  }

  @app host app.example.dev
  handle @app {
    reverse_proxy app:3000
  }
}

One wildcard cert covers every subdomain. No per-service cert management. No Certificate Transparency log leaking your internal subdomain names. And the DNS challenge means you do not even need port 80 open.

Host Matching#

Caddy lets you route by hostname inside a single server block:

*.example.dev {
  @git host git.example.dev
  handle @git {
    reverse_proxy gitea:3000
  }

  @chat host chat.example.dev
  handle @chat {
    reverse_proxy element:80
  }

  handle {
    respond "Not found" 404
  }
}

In Nginx, each of these would be a separate server block with its own SSL configuration. In Caddy, it is one block with named matchers.

VPN-Only Routes#

I restrict admin services to my VPN subnet:

@admin host admin.example.dev
handle @admin {
  @blocked not remote_ip 10.0.0.0/24
  respond @blocked "Access Denied" 403
  reverse_proxy admin:3001
}

If the request does not come from the VPN, it gets a 403. Combined with DNS that only resolves through the VPN, this is two layers of protection without any auth middleware.

SPA Fallback With Sub-Paths#

Serving a single-page app under a sub-path is surprisingly tricky. The app lives at /app/ but the client-side router handles routes like /app/settings:

handle_path /app* {
  reverse_proxy spa:3000 {
    @notfound status 404
    handle_response @notfound {
      rewrite * /index.html
      reverse_proxy spa:3000
    }
  }
}

handle_path strips the /app prefix before forwarding. If the upstream returns 404, we rewrite to index.html and try again. The SPA router takes over from there.

Gzip and Security Headers#

*.example.dev {
  encode gzip

  header {
    Strict-Transport-Security "max-age=31536000; includeSubDomains"
    X-Content-Type-Options "nosniff"
    X-Frame-Options "DENY"
    Referrer-Policy "strict-origin-when-cross-origin"
  }
}

These apply to every subdomain automatically. No copying the same headers into fifteen different location blocks.

Static Files With Custom 404#

@landing host example.dev
handle @landing {
  root * /srv/example.dev
  file_server
}

handle_errors {
  @404 expression {err.status_code} == 404
  handle @404 {
    root * /srv
    rewrite * /404.html
    file_server
  }
}

The handle_errors block catches 404s across all routes and serves a custom page. One error handler for the entire server.

WebSocket Proxying#

Caddy handles WebSocket upgrades automatically:

reverse_proxy game:3000

That is it. No proxy_http_version 1.1, no proxy_set_header Upgrade, no proxy_set_header Connection. Caddy detects the upgrade request and does the right thing.

Streaming Responses#

For Server-Sent Events or long-running responses:

reverse_proxy backend:3000 {
  flush_interval -1
  transport http {
    read_timeout 0
    write_timeout 0
  }
}

flush_interval -1 disables response buffering. The timeout overrides prevent Caddy from killing long-lived connections.

The Caddyfile syntax is not perfect. The matcher system takes some getting used to, and the documentation could be better organized. But the amount of boilerplate it eliminates compared to Nginx is staggering. My entire server config is under 120 lines, and it handles TLS, routing, static files, reverse proxying, WebSockets, and error pages for a dozen services.

It sounds like a mess, but it is actually pretty clean. The trick is structure: one compose file, two networks and some naming discipline.

One Compose File, Two Networks#

Every service lives in a single docker-compose.yml. I tried splitting it into multiple compose files early on and it was a nightmare. Services that need to talk to each other end up on different networks, you forget which file defines what, and debugging becomes archaeology.

One file means one place to look. The trade-off is that the file is about 200 lines long, but that is way better than hunting through five separate files.

The networking is simple: two Docker bridge networks. The first one connects Caddy to the internet. The second one connects Caddy to every backend service. Services that need to be reached by Caddy join the backend network. Services that need direct port access to the internet get explicit port mappings.

The WireGuard container is the exception. It runs with host networking because it needs raw access to the network stack for the VPN tunnel. Everything else uses the bridge networks.

Container Naming#

I name every container explicitly with container_name. Docker Compose generates names like wleeaf-caddy-1 by default, which is ugly in logs and hard to type in commands. Explicit names mean I can do docker logs caddy instead of docker logs wleeaf-caddy-1.

This also matters for DNS resolution inside Docker networks. When you give a container a name, other containers on the same network can reach it by that name. So my Caddy config just says reverse_proxy gitea:3000 and Docker handles the resolution.

Resource Reality#

People overestimate how much RAM you need. Here is what my containers actually use:

The reverse proxy sits at 15 megabytes. The git server uses about 110. The mail server is the hungriest at 160. The Matrix homeserver varies between 100 and 500 depending on federation activity. The database backing it uses 70. Everything else is under 50 each.

Total memory usage hovers around 2.5 gigabytes. That leaves five gigs free for spikes, builds, and the occasional agent session eating a gig for a few minutes.

CPU is basically idle. The load average rarely goes above 0.1 unless someone is building a Docker image or running a CI job. Four cores is overkill for this workload.

Secrets Management#

I keep secrets in a .env file next to the compose file. Docker Compose reads it automatically. Database passwords, API tokens, and hashed passwords all live there. The compose file references them with the dollar-sign-curly-brace syntax.

The .env file is not in any git repo. I back it up manually. Some people use Docker secrets or Vault for this, but for a single-server personal setup, a .env file is fine.

Restart Policies#

Every service has restart: unless-stopped. This means containers come back after a reboot or a crash, but stay down if I explicitly stop them. I used to use always but that fights you when you are debugging, because the container keeps restarting while you are trying to read the logs.

The one exception is the CI runner. It has restart: unless-stopped too, but I sometimes need to stop it to free resources during heavy builds. With unless-stopped, it stays down until I bring it back up.

Volume Strategy#

I mount named directories from the host filesystem, not Docker volumes. Every service gets a directory under the main project folder. Caddy gets ./caddy, Gitea gets ./gitea, the mail server gets ./stalwart, and so on.

This makes backups trivial. I can tar the entire project directory and I have everything: configs, data, and the compose file itself. Docker volumes are fine, but they hide the data in a location you have to look up every time.

The Upgrade Dance#

Upgrading a service usually means changing the image tag and running docker compose up -d. For services using latest, I pull first with docker compose pull and then bring them up.

I do not use Watchtower or any automatic update tool. I want to know exactly when things change. An automatic update at 3 AM that breaks the mail server is not a problem I want to have.

The whole setup has been running for months with essentially zero unplanned downtime. The only time services go down is when I am actively working on them. For a personal infrastructure project, that is more than good enough.

The usual advice goes something like this: spam filters will eat your messages, IP reputation is impossible to build, and you will spend your weekends debugging DKIM signatures instead of doing anything useful. After a couple weeks of running Stalwart on a cheap Hetzner VPS, I can say that some of those warnings are legitimate but most of them are outdated.

The Setup#

I went with Stalwart, which is a relatively new mail server written in Rust. It handles SMTP, IMAP, and JMAP out of the box, and the admin UI is surprisingly decent for a self-hosted project. The whole thing runs in a single Docker container with a RocksDB backend, which means no separate database to manage.

The stack looks like this:

• Stalwart for mail handling on ports 25, 465, 587, and 993
• Caddy as the reverse proxy with a wildcard TLS cert
• SnappyMail for webmail access
• Cloudflare for DNS on the free plan

The VPS itself is nothing special. 4 cores, 8 gigs of RAM, running Ubuntu 24.04. Stalwart barely touches the resources and sits at around 150MB of RAM even after a few thousand messages.

DNS Was the Easy Part#

Setting up DNS records is the part that scares most people, but it is genuinely straightforward if you take it step by step. You need an A record for your mail subdomain, an MX record pointing to it, SPF to declare which IPs can send for your domain, DKIM for cryptographic signature verification, and DMARC to set a policy for failed checks.

The Cloudflare API makes all of this scriptable. I wrote a shell script that creates all five records in about 30 seconds. The DKIM key was the only tricky part because Stalwart generates it internally and you have to copy it out of the admin panel and paste it into DNS.

The Reputation Problem#

This is the real challenge. When you spin up a brand new IP and start sending mail, every major provider treats you with suspicion. Gmail sent my first few messages straight to spam even though SPF, DKIM, and DMARC all passed perfectly.

The fix was not technical, it was behavioral. I marked those messages as not spam in my Gmail account, added the addresses to my contacts, and started having normal conversations. Within a few days, Gmail stopped flagging my messages. Google Postmaster Tools confirmed that the domain reputation was climbing.

One thing that helped: my VPS provider has decent IP reputation to begin with. If you are on a provider known for abuse, you will have a much harder time. Also make sure your reverse DNS is set correctly because Gmail checks that the PTR record for your IP matches your mail hostname.

TLS Certificate Sharing#

I did not want to manage separate certificates for the mail server. Caddy already handles TLS for all my subdomains using a wildcard cert from Lets Encrypt via DNS challenge. I just mounted the certificate directory read-only into the Stalwart container.

The only catch is that Caddy stores the cert in a specific directory structure and you need to figure out the exact path. Once you find that, a volume mount in Docker Compose is all you need.

Was It Worth It#

Honestly, yes. The total ongoing cost is zero beyond the VPS I was already paying for. I have full control over my email, the data never touches a third party, and the whole thing took an afternoon to set up.

The one thing I would do differently: I would have registered my domain and set up the mail server on the same day. Domain age matters for reputation, and the sooner you start sending from a domain, the sooner it builds trust with the big providers.

If you are already running a VPS for other things, adding a mail server is a no-brainer. If you are starting from scratch just for email, you might want to think about whether the learning experience is worth the first week of dealing with spam folders.