DEV Community: Shubham Sharma

Running Local LLMs with RamaLama and Docker on a Mac: A Hands-On Guide

Shubham Sharma — Mon, 31 Aug 2026 12:24:50 +0000

RamaLama runs large language models as OCI containers, so a single command (ramalama run smollm:135m) pulls a model and starts talking to it, with no Python environment to babysit. I spent an afternoon putting it through its paces on an Apple Silicon Mac (Apple M4 Pro, 48 GB RAM, macOS 26.6) with Docker 29.4 provided by OrbStack. This guide is what I actually saw: the install, the first model, an OpenAI-compatible server, and the one macOS-specific catch that isn't obvious from the docs. Every command and number below is from that run, on RamaLama 0.24.0.

What is RamaLama?

RamaLama is an open-source CLI from the container-tooling community that treats models like container images. Instead of assembling an inference stack yourself, it pulls a hardened OCI image containing llama.cpp (or vLLM/MLX) plus your chosen model and runs it with Podman or Docker. If you've used Ollama the ergonomics feel familiar (run, serve, list, pull), but the runtime and model live inside containers you can inspect and sign, and weights come straight from Hugging Face, Ollama, or any OCI registry.

Installing RamaLama on macOS

With Homebrew it's one command:

brew install ramalama

That pulled RamaLama 0.24.0 and, notably, its own copy of llama.cpp, ggml, and libomp as dependencies. Hold onto that detail; it matters for GPU acceleration later. Confirm the install:

ramalama version
# ramalama version 0.24.0

You also need a container engine running. I used Docker through OrbStack; Podman works too and is RamaLama's default on Linux.

Running your first model

The headline command:

ramalama run smollm:135m "In one sentence, what is a Linux container?"

Passing a prompt as an argument gives you one-shot output instead of dropping into a chat REPL. On first run this pulled the RamaLama container image, downloaded the model, and answered. smollm:135m resolves to hf://HuggingFaceTB/smollm-135M-instruct-v0.2-Q8_0-GGUF, a 138 MB, 8-bit quantized GGUF from Hugging Face.

First-run wall-clock was 2 minutes 56 seconds, but almost all of that was downloads (the ~1 GB image plus the model); the 135M model itself is near-instant on CPU. It is also not smart: asked about containers it invented "2048-bit containers" and a docker-compose up -v command that doesn't exist. That's expected at 135M parameters. Use a model this small to validate your setup, not to do real work; a 1B model like llama3.2:1b (a 770 MB Q4_K_M download) answers the same question correctly. (For which models are actually worth running today, see the open-weight coding leaderboard shake-up.)

Check what you've downloaded:

ramalama list
# SHORTNAME    NAME                                                    SIZE
# llama3.2:1b  hf://bartowski/Llama-3.2-1B-Instruct-GGUF               770.28 MB
# smollm:135m  hf://HuggingFaceTB/smollm-135M-instruct-v0.2-Q8_0-GGUF  138.1 MB

Models live under ~/.local/share/ramalama, separate from your container images.

What RamaLama actually runs

Before running anything for real, --dryrun prints the exact command without executing it:

ramalama --dryrun run smollm:135m "hi"

On my Mac that expands to a hardened docker run:

docker run ... --security-opt=label=disable --cap-drop=all \
  --security-opt=no-new-privileges --pull always -d -p 8080:8080 \
  --init quay.io/ramalama/ramalama:0.24 \
  llama-server --host :: --port 8080 --model /path/to/model --threads 7 ...

Note what it does by default: drops all Linux capabilities, disables privilege escalation, and starts llama-server, the same server that backs the OpenAI-compatible API below. The base image (quay.io/ramalama/ramalama:0.24) is about 1 GB, downloaded once and reused.

The macOS gotcha: containers run on the CPU

Here is the part that trips people up. On Apple Silicon, a model running inside a Linux container cannot reach the Mac's GPU, because Docker's Linux VM has no path to Metal. ramalama info reports the container engine's accelerator as none:

{ "Accelerator": "none", "Config": { "runtimes": { "llama_cpp": {}, "mlx": {} } } }

So the default containerized run is CPU-only. Fine for a 135M toy, painful for anything larger. The fix is --nocontainer, which runs the host's llama.cpp (the copy Homebrew installed) directly:

ramalama --nocontainer serve -p 8081 llama3.2:1b

I benchmarked the difference on the same model and prompt. Served natively, Llama-3.2-1B (Q4_K_M) loads straight onto the Apple GPU. Its startup log shows:

load_tensors: offloaded 17/17 layers to GPU
ggml_metal_init: found device: Apple M4 Pro

and it generated at ~206 tokens/sec. The same model served in the default container has no GPU to offload to and ran at ~102 tokens/sec on the CPU, about half the speed on this M4 Pro. RamaLama also exposes an mlx runtime if you'd rather use Apple's own inference framework than llama.cpp.

Mode	Command	Isolation	Acceleration	Llama-3.2-1B
Container (default)	`ramalama run`	Full (OCI, cap-drop)	CPU only	~102 tok/s
Native	`ramalama --nocontainer run`	None	Apple GPU (Metal) / MLX	~206 tok/s

The trade-off is genuine: containers give you isolation and reproducibility; native gives you the GPU. On a Mac doing real work, --nocontainer is usually what you want. On Linux with an NVIDIA GPU, the container path keeps both.

Serving an OpenAI-compatible API

This is where RamaLama earns its place. serve starts the same llama-server as a local endpoint:

ramalama serve -d --name tdm-lab -p 8080 smollm:135m

It speaks the OpenAI API, so anything that talks to OpenAI can point at it:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"smollm","messages":[{"role":"user","content":"Say hello."}]}'

The response is standard OpenAI JSON: choices[].message.content, a usage block, and timings. Swap the base URL in your existing OpenAI client and your app runs locally with no code changes. Stop it when done:

ramalama stop tdm-lab

If you'd rather wire a local endpoint into your editor, the same idea powers our guide on connecting Copilot Chat to a local API.

So, is RamaLama worth it?

If you already live in containers, yes. Its strengths are the security defaults (cap-drop, no-new-privileges, signed OCI images), pulling from Hugging Face, Ollama, and OCI registries interchangeably, and the zero-friction OpenAI server. If you just want the fastest local chat on a Mac with a GUI, LM Studio is gentler. The two aren't mutually exclusive: I keep LM Studio for exploring and RamaLama for scripting reproducible, servable model runs.

Plan for two things before you graduate from the toy model. Pick a real quantized model that fits your RAM (a 7–8B Q4 model wants roughly 6–8 GB free), and on a Mac decide up front whether you're optimizing for isolation (container, CPU) or speed (native, Apple GPU).

Key takeaways

Install: brew install ramalama (bundles llama.cpp); needs Docker or Podman running.
Run: ramalama run <model> "prompt" for one-shot output; models come from Hugging Face, Ollama, or OCI registries.
Inspect first: ramalama --dryrun run <model> prints the exact hardened docker run.
macOS catch: containerized runs are CPU-only; --nocontainer offloads to the Apple GPU (Metal). On this M4 Pro, Llama-3.2-1B ran ~206 tok/s native versus ~102 tok/s in-container, about 2x faster.
Serve: ramalama serve exposes a drop-in OpenAI-compatible API on port 8080.
Tested with RamaLama 0.24.0 on macOS 26.6 (Apple M4 Pro, 48 GB), Docker 29.4 via OrbStack; models smollm:135m and llama3.2:1b (Q4_K_M).

Put SSH Behind Tailscale and Close Port 22

Shubham Sharma — Mon, 31 Aug 2026 10:11:49 +0000

Once a VPS is hardened the usual way, keys only, firewalled, patched, there is a bigger move you can make: stop exposing SSH to the public internet at all. Instead of trusting that a strong key holds up against constant scanning, you put SSH on a private network the rest of the world cannot even see, and close port 22 to everyone else. This is my favorite upgrade for a small server in 2026, and it is genuinely less fragile than it sounds, as long as you keep one escape hatch.

This guide picks up where Setting Up Your Own VPS leaves off. If you have not done the baseline (non-root user, SSH keys, UFW), start there first.

Key takeaways

Tailscale gives your server a private address that only your own devices can reach.

Disable key expiry on the server in the admin console, or Tailscale logs you out in 180 days and you cannot reauth remotely.

Allow the tailscale0 interface in UFW, then remove the public port 22 rule.

Always test a new connection over Tailscale before you close the old one.

Keep your provider's browser console handy as a recovery path.

What "behind Tailscale" actually means

Tailscale builds a private mesh network (a "tailnet") between your machines using WireGuard. Every device you add gets a stable 100.x address that is reachable only by your other devices, never from the open internet. Put your server and your laptop on the same tailnet and you can SSH to the server over that private address. Once that works, public port 22 has no reason to exist, so you close it.

There are two ways to run SSH over the tailnet, and it is worth knowing which you are choosing:

Plain OpenSSH over Tailscale. You keep using normal OpenSSH and simply reach it through the private address. Your existing keys and hardening still apply. This is what I recommend for most people, because nothing about your battle-tested SSH setup changes.
Tailscale SSH. Tailscale's own daemon answers on port 22 of the tailnet address and authenticates with your Tailscale identity and access rules. It is convenient, especially for teams, but it hands authentication to Tailscale instead of OpenSSH. Reasonable people disagree here; pick based on how much you want to lean on one provider.

Either way, the firewall move is the same.

Step 1: Install Tailscale and connect

On the server, install Tailscale and bring it up. The install script supports every mainstream distro:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

The command prints a URL. Open it, sign in, and the server joins your tailnet. Install Tailscale on your laptop the same way and sign in with the same account. Check the server's private address with:

tailscale ip -4

You will get a 100.x.x.x address. From your laptop, confirm plain SSH works over it before changing anything:

ssh deploy@100.x.x.x

If you would rather use Tailscale SSH, enable it without dropping your session:

sudo tailscale set --ssh

Step 2: Disable key expiry (do not skip this)

This is the step people forget, and the one that locks them out. By default Tailscale expires a machine's key after 180 days and asks it to log in again. On your laptop that is a minor prompt, but on a headless server whose only door is Tailscale, it is a lockout you cannot fix remotely.

In the Tailscale admin console, open Machines, find the server, open the "..." menu, and choose Disable key expiry. Do this now, while you are thinking about it, for every server you put behind the tailnet.

Step 3: Let the tailnet through UFW, then close port 22

Now tell the firewall to trust the Tailscale interface and remove the public SSH rule. This order matters. Following Tailscale's own ufw lockdown guide:

# Allow everything arriving over the private Tailscale interface
sudo ufw allow in on tailscale0

# Keep the public web ports if you serve a site; otherwise skip this
sudo ufw allow 80,443/tcp

# Remove the public SSH opening
sudo ufw delete allow OpenSSH

Watch for a leftover blanket rule. If sudo ufw status still lists something like 22/tcp ALLOW IN Anywhere, delete it too:

sudo ufw delete allow 22/tcp

Confirm the rules took effect:

sudo ufw status verbose
sudo ss -tlnp | grep :22

ufw status verbose should show Default: deny (incoming), an ALLOW ... on tailscale0 line, and no rule for port 22. One point that trips people up: sshd keeps listening on 0.0.0.0:22, so ss still shows it there, and that is fine. With this approach UFW is what blocks the public side, not sshd, so you verify by behavior (the next step) rather than by the listen address. If you would rather sshd not listen on the public interface at all, you can add ListenAddress lines for your Tailscale and loopback addresses to the SSH drop-in, but leave that as optional hardening: if the tailnet interface is not up when sshd starts, binding fails, so the firewall rule is the safer primary control.

Step 4: Test before you trust it

Never close your working session until a fresh one succeeds. Keep your current SSH terminal open until you have confirmed a new connection works over the tailnet.

With your current SSH terminal still open, start a new terminal and connect over the tailnet:

ssh deploy@100.x.x.x

If that lands you on the server, public SSH is closed and private SSH works. Now you can close the old session. If it fails, you still have the original terminal to undo the firewall change.

Your safety net if it all goes wrong

Two things keep this from ever becoming a real lockout:

The provider console. Hostinger and most hosts include a browser based terminal in their control panel that reaches the server directly, not over SSH. If Tailscale is ever down or misconfigured, that is how you get in to fix it. This is the recovery path you were told to find in the baseline guide.
The reversal order. If you ever remove Tailscale from the server, re-open public SSH first (sudo ufw allow OpenSSH), or you will delete your only way in.

Is this actually a good idea? The trade-offs

I like this setup, but it is fair to name what you are trading:

You are trusting a third party. Tailscale and its coordination servers become part of your access path. Some people would rather depend only on OpenSSH, which is open source and among the most audited software in the world. That is a legitimate position.
You can own the control plane. If that worries you, run Headscale, an open source implementation of the Tailscale control server, or use NetBird as an alternative mesh. More work, less reliance on one company.
This is remote access, not everything. Public web traffic still needs a plan. You can keep serving 80 and 443 directly, or, to avoid opening even those, put the app behind a tunnel. That is a good topic for its own guide.

If you self-host a handful of services for yourself and value not watching your SSH port get scanned a thousand times a day, this is hard to beat.

Where to go next

Start here if you skipped it: Setting Up Your Own VPS: A Secure Starting Point.
Put something behind the tailnet: admin panels are perfect candidates. In the n8n guide you could keep the editor private on the tailnet and only expose webhooks publicly.

Final thoughts

The mental shift is simple: your server should not answer the door for strangers at all. Give it a private address, let only your own machines knock, and keep one emergency key (the provider console) for the bad day. Do that, and the daily reality of running a public VPS gets a lot quieter.

Verified end to end on a real Ubuntu 24.04.4 server: joined a tailnet, allowed tailscale0 in UFW, and removed the public port 22 rule. From a separate machine, SSH to the public IP then timed out while SSH over the tailnet address still logged in, and the kernel firewall log showed the public SYN dropped on eth0. The reversal step re-opened public SSH cleanly. See the linked lab notes.

Setting Up Your Own VPS: A Secure Starting Point

Shubham Sharma — Mon, 31 Aug 2026 09:39:20 +0000

Every self-hosted project I run starts the same way: a brand new VPS and about twenty minutes of setup before I install a single application. That twenty minutes is what separates "my server" from "someone else's crypto miner." A fresh box with a public IP starts getting probed within minutes, and the default configuration on most images is built for convenience, not safety.

This is the secure baseline I set up on every new server, before Docker, before n8n, before anything else. It is also the starting point our production n8n guide assumes you already have. Every command below was checked against current Ubuntu LTS documentation, and I flag the parts that genuinely need a real server to verify.

Key takeaways

Never do daily work as root. Create a sudo user and log in as that instead.

Use an SSH key and turn password login off, but only after you confirm the key works.

Deny everything at the firewall by default, then open only the ports you actually use.

Turn on automatic security updates so patches land while you sleep.

If you plan to run Docker, remember that published ports skip UFW. Bind them to 127.0.0.1.

Prerequisites

A VPS running a current Ubuntu LTS. Both 24.04 "Noble Numbat" and 26.04 "Resolute Raccoon" work well. I run long-lived boxes on Hostinger VPS hosting, which is also what powers the n8n guide.
An SSH key pair on your own machine. If you do not have one yet, Step 3 creates it.
A terminal, and a note of your provider's recovery console. Most hosts, Hostinger included, give you a browser based console in their control panel. That is your way back in if you ever lock yourself out, so find it before you start.

Disclosure: some links in this guide, including the Hostinger link above, are referral or affiliate links. If you sign up through them we may earn account credit or a commission, at no extra cost to you. We only point at tools we actually run.

Step 1: Log in and update the system

Right after the server boots, log in with the credentials your provider gave you and bring every package up to date:

ssh root@YOUR_SERVER_IP
apt update && apt upgrade -y

If the upgrade pulls a new kernel, reboot with reboot and log back in. Starting from a fully patched system means the rest of this guide is the only thing left between you and a solid baseline.

Step 2: Create a non-root user

Working as root all day is the single most common mistake on a new server. One typo or one bad script runs with full control of the machine. Create a normal user with sudo rights and use that from now on:

adduser deploy
usermod -aG sudo deploy

Swap deploy for whatever name you like. The adduser command asks for a password; pick a strong one, since sudo will ask for it.

Step 3: Set up SSH keys

From your own machine, not the server, create a key if you do not already have one:

ssh-keygen -t ed25519 -C "you@your-machine"

Copy the public half up to the new user, then log in as that user to confirm it works:

ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@YOUR_SERVER_IP
ssh deploy@YOUR_SERVER_IP

Do not move on until that last command logs you in without asking for the account password. The next step turns password login off completely, and if the key is not working you will lock yourself out.

Step 4: Harden SSH

Now lock SSH down to keys only and stop root from logging in over it. On Ubuntu, the clean way is a drop-in file, so a future package update cannot quietly overwrite your changes. As the deploy user:

sudo tee /etc/ssh/sshd_config.d/99-hardening.conf > /dev/null << 'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
LoginGraceTime 30
X11Forwarding no
EOF

There is one catch that trips people up. SSH reads its settings top to bottom and keeps the first value it finds for each one, and cloud images ship a lower numbered file that sets PasswordAuthentication for you. On Ubuntu 24.04 it is 60-cloudimg-settings.conf, which already sets it to no; older images used 50-cloud-init.conf and sometimes set it to yes. Because a lower numbered file loads first, whatever it says wins over your file. So do not trust the filename alone. Check the effective configuration, which is the real source of truth:

sudo sshd -t   # tests syntax; no output means it is fine
sudo sshd -T | grep -E "permitrootlogin|passwordauthentication|pubkeyauthentication"

You want to see passwordauthentication no and permitrootlogin no in that output. If password auth still says yes, open the offending lower numbered file, comment that line out, and check again. Once it reads correctly, reload SSH (this does not drop your current session):

sudo systemctl reload ssh

Keep your existing terminal open and log in from a second one to be sure. If anything is wrong, the open session is your safety net.

Step 5: Turn on a firewall

UFW is a friendly front end to the kernel firewall. It is present on the desktop and full server images, but a minimal cloud image often does not include it, so install it first (a no-op if it is already there). Then set it to deny everything coming in, allow your own traffic out, and open only SSH and the web ports:

sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable
sudo ufw status verbose

If you are not serving a website yet, skip the 80,443 line and add it later. The whole idea is that nothing is reachable unless you said so.

Step 6: Automatic security updates

Security patches are only useful once they are installed. The unattended-upgrades package applies them for you:

sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure --priority=low unattended-upgrades

Choose "Yes" at the prompt. You can preview what it would do without changing anything:

sudo unattended-upgrades --dry-run --debug

By default it installs security updates only, which is the sweet spot: you stay patched without surprise changes to everything else on the box.

Step 7: (Optional) Add fail2ban

With password login already off, brute force attempts against SSH are mostly noise, since there is no password to guess. If you still want to trim the log spam, fail2ban watches for repeated failures and bans the source for a while:

sudo apt install fail2ban -y

Its defaults enable an SSH jail out of the box. Treat this as a nicety, not a substitute for keys and a firewall.

The Docker trap almost everyone hits

Here is the one that surprises even experienced people, and it is why it belongs in the baseline.

Docker bypasses UFW. When you publish a container port, Docker writes its own firewall rules that skip UFW entirely. Your ufw status can look locked down while a database sits wide open to the internet.

The reason is where each tool sits in the network path. Docker sends published-port traffic through its own chain before it ever reaches the point UFW inspects, so UFW never gets a say. This is documented behavior, described in Docker's own packet filtering and firewalls page and flagged by the OWASP Docker Security Cheat Sheet.

The simplest, most reliable fix is to bind published ports to localhost instead of every interface. Compare:

# Exposed to the whole internet, even with UFW "on":
ports:
  - "5432:5432"

# Reachable only from the server itself:
ports:
  - "127.0.0.1:5432:5432"

Better still, do not publish internal services at all. Containers on the same Docker network reach each other by name, so a database that only your app talks to needs no host port. That is exactly the pattern in our n8n guide, where Postgres is never published and only Caddy faces the internet.

Where to go next

You now have a server that is patched, key-only, firewalled, and no longer running as root. Two natural next steps:

Take SSH off the public internet entirely. In the next guide I put SSH behind a private Tailscale network and close port 22 to the world: Put SSH behind Tailscale and close port 22.
Run something on it. Our production n8n guide uses this exact baseline as its foundation.

An honest word on trade-offs

None of this makes a server "unhackable," and anyone who tells you a checklist does is selling something. What it does is remove the easy wins: default passwords, root over SSH, exposed services, unpatched holes. That covers the overwhelming majority of automated attacks, which is what actually hits a small VPS. Keep your software updated, keep backups you have tested, and add depth (like the Tailscale step) as your setup grows.

Final thoughts

The shape of this never really changes: a real user, keys not passwords, a default-deny firewall, automatic patches, and an awareness of how Docker treats ports. Do it once, turn it into muscle memory, and every future box takes ten minutes. Then you get to the fun part, which is running your own software.

Verified on a real Ubuntu 24.04.4 server with Docker 29.1.3: the SSH hardening effective values (sshd -T), the default-deny UFW policy, the Docker-bypasses-UFW behavior and the 127.0.0.1 fix (an external request reached the 0.0.0.0-published port straight through an active firewall, then was refused once the port was bound to loopback), automatic security updates, and the fail2ban SSH jail. See the linked lab notes.

Self-Host n8n on a VPS with Docker, PostgreSQL, and Caddy (2026)

Shubham Sharma — Mon, 31 Aug 2026 09:39:17 +0000

I stood this exact stack up before writing a line of it: n8n 2.36.8 talking to PostgreSQL 16.13, fronted by Caddy 2.11.4 for automatic HTTPS. Every command and version below comes from that run. If you have only used the one-line docker run for n8n, this is the production version: a real database instead of the default SQLite, HTTPS without hand-managing certificates, and a layout you can back up and upgrade without losing your workflows.

Key takeaways

Use PostgreSQL, not the default SQLite: set DB_TYPE=postgresdb and the DB_POSTGRESDB_* variables.

Set a persistent N8N_ENCRYPTION_KEY before first launch, or you lock yourself out of saved credentials on the next redeploy.

Let Caddy own HTTPS: point your domain at the server and it provisions a Let's Encrypt certificate automatically.

Verified on n8n 2.36.8, PostgreSQL 16.13, Caddy 2.11.4.

Prerequisites

A VPS (1 vCPU and 2 GB RAM is enough to start) on a recent Linux, with a public IP. New to running a server? Our secure VPS setup guide gets you to a safe baseline first.
A domain or subdomain you control: an A record for n8n.example.com pointing at the VPS.
Docker Engine and the Compose plugin installed. New to Docker? Our RamaLama and Docker walkthrough covers the basics on your own machine first.
Ports 80 and 443 open to the internet (Caddy needs them for HTTPS). Keep 5678 closed.

Heads up: n8n.example.com is a placeholder. Replace it everywhere below (in .env, the Caddyfile, and your DNS record) with a subdomain you actually own, for example n8n.yourdomain.com. example.com is a reserved documentation domain, so it will never issue a TLS certificate.

Step 1: Create the project and secrets

SSH into the VPS, make a directory, and generate two secrets: a database password and n8n's encryption key. The encryption key is the one people forget. n8n uses it to encrypt saved credentials, so if it changes between deploys, every stored credential becomes unreadable.

mkdir -p ~/n8n && cd ~/n8n
{
  echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)"
  echo "N8N_ENCRYPTION_KEY=$(openssl rand -hex 24)"
  echo "N8N_HOST=n8n.example.com"
} > .env
chmod 600 .env

Swap n8n.example.com for your domain.

Step 2: Write the Compose file

Create docker-compose.yml with three services: Postgres (n8n's database), n8n, and Caddy as the HTTPS reverse proxy. Note that n8n's port 5678 is not published to the host; Caddy reaches it over the internal network, so it never faces the internet directly. Every n8n setting used below is documented in n8n's hosting docs.

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: n8n
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n -d n8n"]
      interval: 5s
      timeout: 5s
      retries: 12
    restart: unless-stopped

  n8n:
    image: n8nio/n8n:2.36.8
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      N8N_PORT: 5678
      WEBHOOK_URL: https://${N8N_HOST}/
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      N8N_RUNNERS_ENABLED: "true"
      GENERIC_TIMEZONE: UTC
    volumes:
      - n8ndata:/home/node/.n8n
    restart: unless-stopped

  caddy:
    image: caddy:2-alpine
    depends_on: [n8n]
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddydata:/data
      - caddyconfig:/config
    restart: unless-stopped

volumes:
  pgdata:
  n8ndata:
  caddydata:
  caddyconfig:

I pinned n8n to 2.36.8, the version I tested, so your deploy matches this guide. Bump it deliberately later rather than tracking latest blindly.

Step 3: Write the Caddyfile

n8n.example.com {
    reverse_proxy n8n:5678
}

That is the entire HTTPS setup. Once your domain resolves to the server and 80 and 443 are reachable, Caddy requests a Let's Encrypt certificate on the first visit and renews it on its own. No certbot, no cron job.

Step 4: Launch and verify

docker compose up -d

Compose starts Postgres first, waits for its healthcheck to pass, then starts n8n, which connects and runs its database migrations. Confirm both:

docker compose ps
docker compose logs -f n8n   # watch the migrations finish, then Ctrl-C

On my run, n8n 2.36.8 came up healthy in about ten seconds once the images were cached, and the log showed it running its migration set against Postgres 16.13. That is exactly what you want to see: n8n is using Postgres, not silently falling back to SQLite. If you temporarily add ports: ["127.0.0.1:5678:5678"] to the n8n service, curl http://localhost:5678/healthz returns {"status":"ok"}. Remove it once Caddy is serving.

Open https://n8n.example.com and n8n prompts you to create the owner account. Do that immediately, before anyone else finds the URL.

Once that is done you land on the workflow editor, ready to build your first automation:

Step 5: Harden it

A few settings separate a demo from something you leave running:

Encryption key: you set N8N_ENCRYPTION_KEY in Step 1. Keep .env backed up somewhere safe; losing it means re-entering every credential by hand.
Firewall: allow only SSH, 80, and 443. On Ubuntu: ufw allow OpenSSH && ufw allow 80,443/tcp && ufw enable. Never expose 5678.
Restart policy: restart: unless-stopped (already in the file) brings the stack back after a reboot.
Stay patched: keep the host updated, and treat n8n version bumps as a deliberate step.

Step 6: Back up and upgrade

Two volumes hold your state: pgdata (workflows, executions, credentials) and n8ndata (n8n's config). Back up both.

# database dump
docker compose exec -T postgres pg_dump -U n8n n8n | gzip > n8n-db-$(date +%F).sql.gz
# n8n data volume
docker run --rm -v n8n_n8ndata:/data -v "$PWD":/backup alpine \
  tar czf /backup/n8n-data-$(date +%F).tar.gz -C /data .

To upgrade, change the pinned tag in docker-compose.yml, then:

docker compose pull n8n
docker compose up -d n8n

n8n runs any new migrations on start. Because your data lives in the Postgres and n8ndata volumes, the container itself is disposable, which is the entire point of running it this way.

Common issues

Credentials read as broken after a redeploy. The N8N_ENCRYPTION_KEY changed. Restore the original key from your .env backup.
The certificate never issues. Caddy needs the domain's A record pointing at the server and ports 80 and 443 reachable. Check docker compose logs caddy for ACME errors.
n8n warns about task runners. n8n 2.x expects N8N_RUNNERS_ENABLED=true, which is already set above.

FAQ

Do I need PostgreSQL, or is SQLite fine? SQLite works for a hobby instance, but for anything you rely on, Postgres handles concurrent executions and backups far better. Switching later is a migration; starting on Postgres avoids it.

Can I use Nginx instead of Caddy? Yes, but Caddy's automatic HTTPS is the reason it is here: one line of config versus managing certbot and renewals.

How much server do I need? A 1 vCPU and 2 GB VPS runs a light instance. Heavy or highly concurrent workflows want more RAM and, eventually, n8n's queue mode with separate worker containers.

Final thoughts

The shape here, an application plus Postgres plus Caddy in one Compose file, is the same one you will reuse for most self-hosted tools. Set the encryption key, let Caddy own TLS, keep your state in named volumes, and upgrades become a two-line routine.

Verified end to end on n8n 2.36.8, PostgreSQL 16.13, and Caddy 2.11.4.