DEV Community: Edwin Sanjo Soji

Mastering Edge Routing: The Definitive Caddy Reverse Proxy Guide

Edwin Sanjo Soji — Sat, 07 Nov 2026 15:59:40 +0000

When exposing web applications, Docker containers, or internal services to the public internet, you need a reverse proxy. While Nginx is the legacy powerhouse, Caddy has become the modern standard due to its built-in, fully automated HTTPS and incredibly readable configuration files.

This guide will walk you through a proper installation, a basic setup that is more than enough for most solo developers, and an advanced modular setup designed for multi-user server environments.

Phase 1: The Proper Installation

Do not use the default Ubuntu package manager (apt) to install Caddy right away. The default repositories often host significantly outdated versions. Instead, we will add Caddy's official Cloudsmith repository to ensure we get the latest stable release with current security patches.

1. Install prerequisite tools:

sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

2. Download and add the official Caddy GPG keys:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

3. Add the Caddy repository to your system:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

4. Install Caddy:

sudo apt update
sudo apt install caddy

Phase 2: The Basic Setup (Enough for Most Users)

If you are running a single server with just one or two applications (like a personal portfolio and a single backend API), this basic setup is completely sufficient. You do not need to overcomplicate your architecture.

Caddy's entire routing logic lives in a single file called the Caddyfile.

1. Open the Caddyfile for editing:

sudo nano /etc/caddy/Caddyfile

2. Replace the default text with your routing blocks:

Delete whatever is in there and write your site configuration. Here is an example of routing a domain to a Next.js app running locally on port 3000:

yourdomain.com {
    reverse_proxy 127.0.0.1:3000
}

api.yourdomain.com {
    reverse_proxy 127.0.0.1:8080
}

3. Save the file and reload Caddy:

Press CTRL + O, then Enter to save, and CTRL + X to exit Nano. Then apply the changes:

sudo systemctl reload caddy

Caddy will instantly request SSL certificates for your domains and securely route your traffic. If you are a solo developer with a simple setup, stop here. You are done.

Phase 3: The Modular `conf.d` Setup

If you are hosting dozens of services, running a complex homelab, or collaborating with a team, cramming everything into one massive Caddyfile becomes messy and dangerous. A single typo could take down every site on the server.

Instead, we split our routes into a modular directory architecture.

1. Create a directory for individual configurations:

sudo mkdir -p /etc/caddy/conf.d

2. Edit the main Caddyfile to act as an importer:

sudo nano /etc/caddy/Caddyfile

Replace the contents with this exact structure:

{
    # Global administrative settings can go here
    # email admin@yourdomain.com
}

# Import all individual site configurations
import conf.d/*.caddy

Save and exit.

3. Create dedicated files for each service:

Now, whenever you add a new app, give it its own file. For example, to add code-server:

sudo nano /etc/caddy/conf.d/code-server.caddy

code.yourdomain.com {
    reverse_proxy 127.0.0.1:8080
}

Reload Caddy (sudo systemctl reload caddy). If you ever make a mistake in code-server.caddy, it won't break your other applications.

Phase 4: Scoped User Permissions (Zero-Downtime Reloads)

In a multi-user environment, you might have standard user accounts (like a CodexSandboxUsers group or a secondary developer account) that frequently deploy new apps. They need the ability to reload Caddy to apply their new .caddy files, but giving them full sudo access to the server is a massive security risk.

We can grant a specific user or group the exact permission to reload Caddy—and nothing else.

1. Create a dedicated sudoers rule:

[!info] Why visudo?
We use visudo instead of nano here because if you make a syntax error in a sudoers file, you can permanently lock yourself out of administrative access. visudo checks your work before saving.

sudo visudo -f /etc/sudoers.d/caddy-reload

2. Add the scoped privilege rule:

Add this line to allow the standard ubuntu user to reload Caddy without a password (adjust the username as needed for your specific setup):

ubuntu ALL=(root) NOPASSWD: /usr/bin/systemctl reload caddy

Save and exit (CTRL + O, Enter, CTRL + X).

Now, when your standard user deploys a new application, they can simply type sudo systemctl reload caddy. It will execute flawlessly without prompting for a password, and without giving them the keys to your entire infrastructure.

Zero to Production: Securing and Provisioning a Fresh Linux Server

Edwin Sanjo Soji — Sat, 07 Nov 2026 13:39:29 +0000

Deploying a self-hosted environment on a fresh Linux instance requires establishing a secure baseline before you start spinning up web services or databases. A naked Ubuntu server exposed to the public internet is vulnerable to automated scanning and brute-force attacks within minutes of deployment.

Read, Understand, and Apply Selectively
Please read this entire guide carefully before executing commands. Take the time to understand what each phase does, and only apply the configurations required for your specific architecture. Some steps (like strict cloud-provider rules or swap memory) may not be necessary for every environment. If a step doesn't fit your use case, skip it.

This guide establishes a chronological, production-ready DevSecOps baseline from the moment you first SSH into your new virtual machine.

Phase 1: Initial System Provisioning

Before configuring any services, you must ensure the base operating system is up-to-date and accurately tracking time. A fresh instance will likely have pending security patches.

1.1 System Update and Upgrade

Run a full system update and upgrade:

sudo apt update && sudo apt upgrade -y

Kernel Updates
Depending on the kernel updates, you may be prompted to restart certain services. It is generally safe to select the default options and press Enter.

1.2 Set System Timezone

Accurate system time is critical for security tools (like Fail2ban) to read log timestamps properly. Set your server to your local timezone (e.g., UTC or Asia/Kolkata):

sudo timedatectl set-timezone UTC

Phase 2: Core Security & Firewall Setup

Relying on raw iptables directly is dangerous—flushing them can result in an immediate SSH lockout. UFW (Uncomplicated Firewall) provides a safe abstraction layer, while Fail2ban prevents brute-force attacks.

2.1 Install & Automate Security Packages

First, install UFW, Fail2ban, and the automatic upgrade utility:

sudo apt install ufw fail2ban unattended-upgrades -y

Next, configure the system to actually execute those upgrades automatically in the background. Open the configuration file:

sudo nano /etc/apt/apt.conf.d/20auto-upgrades

Paste the following two lines into the file, then save and exit (Ctrl+O, Enter, Ctrl+X):

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

2.2 UFW and Port Management

Warning

SSH Lockout
You MUST explicitly allow OpenSSH before enabling UFW, or your active session will be immediately severed.

sudo ufw default deny incoming
sudo ufw default allow outgoing

# Infrastructure Allowances
sudo ufw allow OpenSSH
# Add other necessary ports here later, e.g., sudo ufw allow 80,443/tcp for web servers

sudo ufw enable

[!info] Optional: Strict Cloud Providers
Some cloud providers (like Oracle Cloud) enforce underlying iptables rules that can block web traffic even if UFW allows it. If you plan to host web applications and encounter blockages, run this to explicitly force ports 80 and 443 open:

sudo iptables -I INPUT -p tcp -m multiport --dports 80,443 -j ACCEPT

2.3 Fail2ban Integration

Force Fail2ban to utilize UFW instead of raw iptables to prevent firewall rule conflicts. Open a new local configuration file:

sudo nano /etc/fail2ban/jail.local

Paste the following configuration into the file, then save and exit:

[DEFAULT]
bantime = 1h
findtime = 10m
maxretry = 5
banaction = ufw
banaction_allports = ufw

[sshd]
enabled = true
backend = systemd

Enable and start the service:

sudo systemctl enable --now fail2ban

2.4 Disable SSH Password Authentication

Once you have verified that you can log into the server securely using your SSH key, you must disable password authentication. This renders brute-force dictionary attacks mathematically impossible.

Open the main SSH configuration file:

sudo nano /etc/ssh/sshd_config

Scroll through the file and look for these two settings. You may need to remove the # symbol at the start of the line to uncomment them, and ensure both are set to no:

PasswordAuthentication no
PermitRootLogin no

Save and exit the file. Then, restart the SSH service to apply the new rules:

sudo systemctl restart ssh

Phase 3: System Stability (Swap Memory)

Running memory-intensive applications can cause Out-Of-Memory (OOM) crashes on servers with limited RAM. Creating a dedicated swap file prevents catastrophic failures when your system memory maxes out by utilizing disk space as a safety net.

Create and mount an 8GB swap file (adjust the size based on your storage capacity):

sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

How to Set Up PostgreSQL with Docker on Ubuntu

Edwin Sanjo Soji — Thu, 16 Jul 2026 03:33:18 +0000

TL;DR

This post walks through running PostgreSQL 18 on a fresh Ubuntu server using Docker
Compose, with a named volume for data persistence, secrets in a .env file, a
healthcheck, and the port bound to localhost only (with an SSH tunnel for remote
access). By the end you'll have a Postgres instance that survives container
restarts, isn't exposed to the open internet, and is easy to back up.

You need a Postgres instance on a server for an app, a side project, or a homelab
setup. Docker Compose is the fastest way to get a reproducible setup — no manual
apt install postgresql, no fighting with system package versions, and the whole
config lives in one file you can commit to git (minus secrets).

Environment

- Ubuntu 22.04 or 24.04 LTS
- Docker Engine (installed via Docker's official apt repo)
- Docker Compose v2 (the `docker compose` plugin, not the old standalone docker-compose)
- PostgreSQL 18 (official image from Docker Hub)

Approach / Key Decisions

A few choices worth calling out before the config, since they're the parts people
usually get wrong on the first try:

Pin the image tag (postgres:18.4), not latest — reproducibility matters more than convenience once you have real data in the volume.
Named volume, not bind mount, for the data directory — avoids permission headaches between the container's internal user and the host filesystem.
Secrets in .env, never hardcoded in docker-compose.yml — so the compose file itself is safe to commit to git.
Bind the port to 127.0.0.1 only — Postgres has no business listening on 0.0.0.0 on a public server. If you need remote access, use an SSH tunnel or a VPN, not an open port.
Add a healthcheck — so anything depending on Postgres (an app container, a CI job) can wait for "actually ready to accept queries," not just "container started."

Solution / Implementation

1. Install Docker Engine + Compose plugin

# refresh package index and install packages needed to add a new apt repo over HTTPS
sudo apt update
sudo apt install -y ca-certificates curl gnupg

# create the directory that will hold Docker's GPG key
sudo install -m 0755 -d /etc/apt/keyrings
# download Docker's official GPG key and make it readable by apt
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# add Docker's apt repo, matching your CPU arch and Ubuntu codename automatically
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# pick up the new repo, then install Docker Engine + the Compose v2 plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Let your user run docker without sudo (log out/in, or newgrp docker, after this):

# add your user to the docker group so you don't need sudo for every docker command
sudo usermod -aG docker $USER
# refresh your shell's group membership without needing to fully log out
newgrp docker

Verify:

docker --version         # confirm Docker Engine installed correctly
docker compose version   # confirm the Compose v2 plugin is available

2. Set up the project directory

# init-scripts/ will hold optional setup SQL/shell scripts (explained below)
mkdir -p ~/postgres-docker/init-scripts
cd ~/postgres-docker

init-scripts/ is optional — anything in there (.sql or .sh files) runs once,
automatically, the first time the container initializes an empty data directory.
Useful for creating extra databases, extensions, or seed data.

3. Create the `.env` file

# writes a .env file that docker-compose.yml will read via ${VAR} substitution.
# NOTE: docker compose's .env parser doesn't strip inline "# comments" after a
# value, so don't add trailing comments on these lines — they'd become part of
# the value itself. Generate a real password with: openssl rand -base64 24
cat > .env << 'EOF'
POSTGRES_USER=appuser
POSTGRES_PASSWORD=change_this_to_a_long_random_password
POSTGRES_DB=appdb
POSTGRES_PORT=5432
EOF

# keep secrets out of git
echo ".env" >> .gitignore

4. Create `docker-compose.yml`

services:
  postgres:
    image: postgres:18.4          # pinned version, not `latest` — see "Key Decisions" above
    container_name: postgres_db
    restart: unless-stopped        # auto-restart on crash or host reboot (as long as Docker itself starts on boot)
    environment:
      # values are pulled from .env in the same directory via ${VAR} substitution
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    ports:
      # bind to localhost only — NOT "5432:5432", which would expose it on all interfaces
      - "127.0.0.1:${POSTGRES_PORT}:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data              # named volume — persists data across container recreation
      - ./init-scripts:/docker-entrypoint-initdb.d   # optional: runs once against an empty data dir
    healthcheck:
      # checks Postgres can actually accept queries, not just that the process is running
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s   # how often to run the check
      timeout: 5s     # how long to wait for a response before counting it as failed
      retries: 5      # consecutive failures before marking the container "unhealthy"

volumes:
  pgdata:   # declares the named volume used above; Docker manages the storage location

5. Bring it up

docker compose up -d        # start the container in the background, reading .env + docker-compose.yml
docker compose ps           # check it's running (and, once healthchecks pass, "healthy")
docker compose logs -f postgres   # tail the logs; Ctrl+C to stop watching (container keeps running)

Wait for database system is ready to accept connections in the logs, or check
the healthcheck status in docker compose ps (it should show healthy).

Verification

From inside the container:

# -it gives you an interactive terminal attached to the psql session
docker exec -it postgres_db psql -U appuser -d appdb

Once in psql, sanity-check the connection:

\conninfo  -- shows which user/db/host/port you're connected as
\l         -- lists all databases visible to this user
\q         -- exit psql

Healthcheck directly:

# same check docker-compose.yml's healthcheck runs internally — useful for manual debugging
docker exec postgres_db pg_isready -U appuser

From the host (if you have psql installed locally — sudo apt install postgresql-client):

# works because the port is bound to 127.0.0.1, i.e. reachable from the host itself
psql -h 127.0.0.1 -p 5432 -U appuser -d appdb

From a remote machine, since the port is bound to localhost only, tunnel in first:

# forwards local port 5432 through SSH to the server's 127.0.0.1:5432
ssh -L 5432:127.0.0.1:5432 youruser@your-server-ip

# then, in a separate terminal on your local machine, connect as if Postgres were local:
psql -h 127.0.0.1 -p 5432 -U appuser -d appdb

Lessons Learned / Gotchas

docker compose down vs docker compose down -v — the first keeps your named volume (data survives); the second deletes it too. Easy to fumble this when you're tearing down containers to "start fresh."
Changing POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB after the volume already has data does nothing — those env vars only take effect on first init of an empty data directory. To change them later, update the values with SQL directly, or wipe the volume and start over.
Never expose 5432 to 0.0.0.0 on a public server. Postgres auth is not designed to be your only line of defense against internet-wide scanning and brute-force attempts.
Backups are still your job. A container restart is not a backup strategy.

  # dumps the database to a plain SQL file on the host, named with today's date
  docker exec postgres_db pg_dump -U appuser appdb > backup_$(date +%F).sql

  # restore into a fresh instance (-i keeps stdin open so the file content reaches psql)
  cat backup_2026-07-16.sql | docker exec -i postgres_db psql -U appuser -d appdb

restart: unless-stopped means Postgres comes back up after a server reboot — but only if the Docker daemon itself is set to start on boot (sudo systemctl enable docker, usually on by default after the apt install).