DEV Community: byteguard

How to Set Up Nginx Proxy Manager with Docker

byteguard — Tue, 23 Jun 2026 20:18:02 +0000

Originally published on byte-guard.net.

TL;DR: Nginx Proxy Manager (NPM) is a free, open-source web GUI for Nginx that gives every self-hosted app a clean domain and an auto-renewing Let's Encrypt certificate without touching a config file. Run it as one Docker container, open ports 80 and 443, point your DNS at the server, and you can have your first HTTPS proxy host live in under five minutes.

The moment you self-host more than one thing — Vaultwarden, a dashboard, a photo server — you hit the same wall: everything wants port 443, you're juggling certificates by hand, and exposing raw IP:port to the internet is both ugly and unsafe. Nginx Proxy Manager solves all three. It puts a friendly web UI on top of Nginx and Let's Encrypt, so you map vault.yourdomain.com to an internal container in a few clicks and get a valid TLS certificate that renews itself.

I run NPM in front of every public service on byte-guard.net, and on my Hetzner box the whole stack idles at about 95 MB of RAM. By the end of this guide you'll have it running in Docker, your first app behind HTTPS, and the admin panel locked down the way it should be. Tested on Ubuntu 24.04 LTS with Docker Engine 27.x and the jc21/nginx-proxy-manager v2.12 image on 23 June 2026.

Prerequisites

Before you start, you'll need:

A VPS or home server with a public IP (a small one is plenty — see my VPS comparison for what I'd pick today).
Docker and Docker Compose installed.
A domain name with an A record pointing at your server's IP (and a wildcard or per-app subdomain record for each service).
Ports 80 and 443 open on the server firewall.
A hardened base server — if this is a fresh box, run through hardening your Linux VPS and SSH hardening first.

What Is Nginx Proxy Manager and Why Use It?

Nginx Proxy Manager is a Dockerized reverse proxy that wraps the Nginx engine in a point-and-click dashboard with built-in Let's Encrypt automation. Instead of hand-writing server blocks and running certbot, you fill in a form: domain in, forward host and port out, tick "request a new SSL certificate," done.

It's genuinely free and open source — there's no paid tier, and your only cost is the server it runs on. The trade-off versus a config-driven proxy is flexibility: if you want infrastructure-as-code or label-based routing, you'll prefer Traefik or Caddy. I break down exactly when to pick each one in Nginx Proxy Manager vs Traefik vs Caddy. For most self-hosters who want a GUI and zero config files, NPM is the fastest path to clean HTTPS.

How Do You Install Nginx Proxy Manager with Docker?

You install Nginx Proxy Manager by running a single Docker Compose service with two persistent volumes. Create a project folder and a docker-compose.yml:

mkdir -p /opt/npm && cd /opt/npm

# /opt/npm/docker-compose.yml
services:
  nginx-proxy-manager:
    image: jc21/nginx-proxy-manager:latest
    container_name: npm
    restart: unless-stopped
    ports:
      - "80:80"     # HTTP — needed for sites + Let's Encrypt HTTP-01 challenge
      - "443:443"   # HTTPS
      - "81:81"     # Admin UI (we lock this down in the Security section)
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

Recent NPM versions ship with an embedded SQLite database, so you don't need a separate MariaDB container the way older tutorials show — fewer moving parts, less RAM. The two volumes are the only state that matters: ./data holds your hosts, users, and the SQLite file; ./letsencrypt holds your certificates. Back up those two folders and you've backed up everything.

Bring it up:

docker compose up -d
docker compose logs -f

The first start takes 20–30 seconds while it initialises the database. When the logs settle, the container is ready.

Note: If you're on an older install with a version: line at the top of the Compose file, drop it — the Compose spec ignores it now and newer Docker prints a warning.

How Do You Log In and Add Your First Proxy Host?

You log in at http://<YOUR_SERVER_IP>:81 with the default credentials, then create a Proxy Host pointing at your app. Open that URL in a browser and sign in with:

Email: admin@example.com
Password: changeme

NPM immediately forces you to set a real email and a strong password — do it now, because this panel controls every certificate and route on the box.

To expose your first app, go to Hosts → Proxy Hosts → Add Proxy Host:

Domain Names: vault.yourdomain.com (the subdomain whose DNS already points at this server).
Scheme: http, Forward Hostname / IP: the container name or internal IP, Forward Port: the app's internal port (for example vaultwarden and 80).
Tick Block Common Exploits and, for apps that need it, Websockets Support.
Switch to the SSL tab → Request a new SSL Certificate → enable Force SSL, HTTP/2 Support, and HSTS. Agree to the Let's Encrypt terms and save.

A few seconds later NPM provisions the certificate and your app is live over HTTPS. For this to work, NPM has to reach the app — the cleanest way is to put both containers on the same Docker network and forward by container name:

docker network create proxy
docker network connect proxy npm
# add `networks: [proxy]` to each app's compose service, then reference it by name

That's the whole loop: add a DNS record, add a Proxy Host, get a certificate. Repeat for Vaultwarden, n8n, Nextcloud, or anything else you run.

How Do You Secure Nginx Proxy Manager?

You secure Nginx Proxy Manager by keeping its admin panel off the public internet, using strong credentials, and patching it regularly. The proxy ports (80/443) belong to the world; the admin port (81) does not.

Lock down port 81. This is the single most important step. Either firewall it to your home IP, or rebind it to localhost and reach it over a VPN. Rebinding is the safer default:

    ports:
      - "80:80"
      - "443:443"
      - "127.0.0.1:81:81"   # admin UI no longer reachable from the internet

After docker compose up -d, reach the panel through an SSH tunnel (ssh -L 8181:localhost:81 user@server) or, better, over your own WireGuard VPN so the dashboard never touches the public internet at all.

The rest of the checklist:

Use a long, unique admin password (a password manager makes this painless).
Patch on a schedule — docker compose pull && docker compose up -d pulls the latest image; NPM ships security fixes regularly.
Add an Access List (Hosts → Access Lists) with HTTP Basic Auth or IP allow-listing in front of admin-only services.
Run a host firewall so only 80, 443, and SSH are open — see hardening your Linux VPS.

Note: NPM has no built-in two-factor auth, which is exactly why port 81 should never be publicly reachable. Treat network isolation as your second factor.

Troubleshooting Common Nginx Proxy Manager Problems

Most NPM issues come down to networking or DNS. Here are the ones I hit most often.

Can't reach the admin UI on port 81. The port isn't published, a firewall is blocking it, or you're using https:// — the admin panel is plain http on 81. Confirm with docker compose ps that the port is mapped, and check your firewall rules.

SSL certificate won't issue. Let's Encrypt's HTTP-01 challenge needs port 80 reachable from the internet and DNS that has actually propagated. If you're behind Cloudflare's orange-cloud proxy, the challenge fails — grey-cloud the record during issuance or switch to a DNS-challenge certificate.

502 Bad Gateway. NPM can't reach your app. The forward hostname or port is wrong, or the two containers aren't on the same Docker network. Use the container name (not localhost) as the forward host and put both on a shared network.

WebSocket apps (like code editors or chat) won't connect. Edit the Proxy Host and enable Websockets Support.

Lost the admin password. NPM re-creates the default admin@example.com / changeme account if the users table is empty. Back up ./data/database.sqlite, remove your user row with the sqlite3 CLI, restart the container, and log in with the defaults — then set a new password right away.

Nginx Proxy Manager FAQ

Is Nginx Proxy Manager free?

Yes. Nginx Proxy Manager is free and open source — there is no paid tier or license fee. Your only cost is the server you run it on, and a small VPS is plenty.

What ports does Nginx Proxy Manager use?

The admin dashboard runs on port 81, while the proxy itself listens on 80 (HTTP) and 443 (HTTPS). Expose 80 and 443 to the internet for Let's Encrypt and your sites, but keep port 81 restricted to your LAN or VPN.

What is the default Nginx Proxy Manager login?

The default credentials are email admin@example.com and password changeme. NPM forces you to set a real email and a strong password the first time you sign in.

Can I run Nginx Proxy Manager on Proxmox?

Yes. Run it as a Docker container inside a VM or LXC on Proxmox — the same Compose file above works unchanged. Many homelabbers use the Proxmox community helper scripts to spin it up in minutes.

Is Nginx Proxy Manager secure to expose to the internet?

The proxy ports (80/443) are designed to face the internet; the admin panel on port 81 is not. As long as you rebind or firewall port 81, keep the image patched, and use a strong password, NPM is safe to run as your public front door.

Conclusion

Nginx Proxy Manager turns the fiddly parts of self-hosting — TLS certificates, renewals, and clean domains — into a form you fill out once per app. You've now got it running in Docker, your first service behind auto-renewing HTTPS, and the admin panel isolated from the public internet. From here, point a few more subdomains at it and put the rest of your stack behind it.

If you're still choosing a proxy, read Nginx Proxy Manager vs Traefik vs Caddy before you commit. And if you'd rather not wire all this up yourself, I'll set up your VPS and reverse proxy for you — Vaultwarden, n8n, or Nextcloud behind NPM, done for you.

Affiliate disclosure

This post links to a VPS comparison that contains affiliate links. I only recommend providers I actually run production workloads on, and it costs you nothing extra.

— enim

How I Built byte-guard.net from Scratch on a Hetzner VPS

byteguard — Tue, 23 Jun 2026 18:24:09 +0000

Originally published on byte-guard.net.

I wanted a security blog that I fully controlled — no managed platforms, no vendor lock-in, just a VPS and a stack I could understand end to end. This is how I built byte-guard.net from scratch on a Hetzner cloud server using Ghost, Nginx Proxy Manager, and Uptime Kuma, all running in Docker.

Why Self-Host?

Platforms like Medium or WordPress.com are fine for getting started, but they come with trade-offs: limited customization, no control over your data, and someone else's rules about what you can publish. For a security-focused blog, I wanted:

Full ownership of my content and data
The ability to run additional tools on the same server (status pages, paste bins, CVE trackers)
A setup I could document and teach others to replicate
Low monthly cost

Choosing the Server

I went with a Hetzner CPX22 in their Helsinki data center. The specs:

3 vCPUs (AMD)
4 GB RAM
80 GB NVMe storage
20 TB traffic

This is more than enough for a Ghost blog, a reverse proxy, and a monitoring dashboard. Hetzner's pricing is hard to beat for what you get, and their Helsinki location gives solid latency across Europe.

The Stack

Here's what runs on the server:

Service	Purpose	Port
Ghost	Blog engine	2368
Nginx Proxy Manager	Reverse proxy + SSL	80, 443, 81
Uptime Kuma	Status/monitoring page	3001

The byte-guard.net stack: NPM terminates TLS and reverse-proxies Ghost and Uptime Kuma over a shared Docker bridge network.

Everything runs in Docker, managed by a single Docker Compose file at /opt/byteguard/docker-compose.yml.

Want the full list of tools and services powering this site — VPS providers, security tools, the self-hosted stack, and the books I learned from? See my resources page.

Step 1: Initial Server Setup

After provisioning the VPS from the Hetzner Cloud console, I SSH'd in and did the basics:

# Update the system apt update && apt upgrade -y Create a non-root user adduser $user usermod -aG sudo $user Set up SSH key authentication mkdir -p /home/$user/.ssh cp ~/.ssh/authorized_keys /home/amine/.ssh/ chown -R amine:amine /home/$user/.ssh Disable password authentication

sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config systemctl restart sshd

Then I configured the firewall:

ufw allow OpenSSH


ufw allow 80/tcp


ufw allow 443/tcp


ufw enable

Step 2: Install Docker and Docker Compose

# Install Docker curl -fsSL https://get.docker.com | sh usermod -aG docker amine Verify

docker --version docker compose version

Step 3: Set Up the Project Directory

mkdir -p /opt/byteguard


cd /opt/byteguard

Step 4: Write the Docker Compose File

Here's the docker-compose.yml that powers the entire site:

version: "3.8" services: ghost: image: ghost:5 container_name: ghost restart: always environment: url: https://blog.byte-guard.net database_client: sqlite3 databaseconnection_filename: /var/lib/ghost/content/data/ghost.db volumes: - ghost_data:/var/lib/ghost/content networks: - byteguard npm: image: jc21/nginx-proxy-manager:latest container_name: nginx-proxy-manager restart: always ports: - "80:80" - "443:443" - "81:81" volumes: - npm_data:/data - npm_letsencrypt:/etc/letsencrypt networks: - byteguard uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma restart: always volumes: - kuma_data:/app/data networks: - byteguard volumes: ghost_data: npm_data: npm_letsencrypt: kuma_data:

networks: byteguard: driver: bridge

Key decisions here:

SQLite over MySQL — Ghost supports SQLite natively, and for a single-author blog the performance is identical with zero extra resource usage.
Shared Docker network — All services communicate internally over the byteguard bridge network. Only Nginx Proxy Manager exposes ports to the internet.
Named volumes — Data persists across container rebuilds.

Bring it all up:

cd /opt/byteguard


docker compose up -d

Step 5: Configure DNS

Over at my domain registrar, I added three A records pointing to the Hetzner VPS IP:

blog.byte-guard.net    → <VPS_IP>


status.byte-guard.net  → <VPS_IP>


byte-guard.net         → <VPS_IP>

Step 6: Configure Nginx Proxy Manager

Nginx Proxy Manager (NPM) has a web UI at port 81. After logging in with the default credentials and changing them immediately, I set up proxy hosts:

For Ghost (blog.byte-guard.net):

Forward hostname: ghost
Forward port: 2368
SSL: Request a new Let's Encrypt certificate, force SSL

For Uptime Kuma (status.byte-guard.net):

Forward hostname: uptime-kuma
Forward port: 3001
SSL: Request a new Let's Encrypt certificate, force SSL

Because all containers share the byteguard Docker network, NPM can reach them by container name. No need to expose individual service ports to the host.

Nginx Proxy Manager after the Ghost and Uptime Kuma proxy hosts are configured. NPM talks to each container by name over the shared Docker network.

Step 7: Set Up Uptime Kuma

With Uptime Kuma running at status.byte-guard.net, I added monitors for:

blog.byte-guard.net — HTTP(S) check every 60 seconds
Ghost container — Docker host check
The VPS itself — Ping check

I also set up a public status page so anyone can check if the blog is up.

Uptime Kuma watching byte-guard.net and blog.byte-guard.net — two green monitors, zero incidents. Takes about 5 minutes to set up.

Step 8: Lock Down the Admin Panel

A few important security steps after everything was running:

# Restrict NPM admin panel to my IP (via UFW)


ufw allow from <MY_IP> to any port 81


  
  
  Block port 81 from everyone else


ufw deny 81/tcp

I also enabled 2FA on the Ghost admin panel and Nginx Proxy Manager.

What It Costs

Item	Monthly Cost
Hetzner CPX22	~€7.50
Domain (byte-guard.net)	~€1/mo amortized
SSL certificates	Free (Let's Encrypt)
Total	~€8.50/mo

A fully self-hosted blog with monitoring and SSL for under €10/month.

What's Next

This is just the foundation. Upcoming additions:

tools.byte-guard.net — Security utilities built with FastAPI
cve.byte-guard.net — A lightweight CVE tracker
paste.byte-guard.net — A self-hosted paste bin for sharing code
Arabic translations — Bilingual content starting in a few months
N8N automation — Already running on a separate Contabo VPS for content workflows

Lessons Learned

Start simple. Docker Compose with SQLite is plenty for a blog. You can always add complexity later.
Nginx Proxy Manager saves hours. Manually configuring Nginx and Certbot is educational but NPM gets you to the same place with a GUI and auto-renewal.
Monitor from day one. Uptime Kuma took 5 minutes to set up and has already caught a DNS propagation issue I would have missed.
Document everything. This blog post is as much for future-me as it is for you. When I inevitably need to rebuild or migrate, I'll have a complete reference.

If you're thinking about self-hosting your own blog, I hope this helps you get started. The whole setup took an afternoon, and running costs are minimal. Feel free to check out the status page to see it all in action.

Once your server is running, I'd recommend hardening your VPS as the very next step — it takes 10 minutes and closes the most common attack vectors. Then lock down your containers with Docker security best practices so your self-hosted stack isn't running with dangerous defaults.

Free download: I compiled every hardening step into a printable checklist you can pin next to your monitor. Grab the Server Hardening Checklist (PDF) — no signup required.

How to Use Nmap Like a Pro — Beginner's Guide

byteguard — Tue, 23 Jun 2026 18:23:20 +0000

Originally published on byte-guard.net.

Every time I set up a new server, the first thing I do before hardening anything is figure out what's actually exposed. Open ports I forgot about, services running on default configs, legacy daemons nobody disabled — that's the stuff attackers find first. Nmap (Network Mapper) is the tool that answers the question: "What does my network look like from the outside?"

This guide is part of our Security Tools Series — hands-on guides for the tools every security-minded developer needs.

This nmap tutorial for beginners walks you through everything from installation to advanced NSE scripts. By the end, you'll know how to scan your own infrastructure, interpret the results, and use that information to lock things down.

Legal Warning: Only scan networks and systems you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions and can get you fired, fined, or prosecuted. This entire tutorial assumes you're scanning your own lab or have a signed authorization.

Prerequisites

A Linux machine (Ubuntu/Debian used in examples) or macOS
Root/sudo access (many scan types require it)
A target system you own or have permission to scan (a second VM, your VPS, etc.)
Basic comfort with the terminal
If you need a VPS to practice on, I covered setting one up in my Hetzner VPS build guide

Installing Nmap

Nmap is available in every major package manager. Here's how to get it on common systems.

Ubuntu/Debian:

sudo apt update && sudo apt install nmap -y

Fedora/RHEL:

sudo dnf install nmap -y

macOS (Homebrew):

brew install nmap

Arch Linux:

sudo pacman -S nmap

Verify the installation:

nmap --version

You should see output showing Nmap version 7.9x or later, along with the compiled libraries (Npcap/libpcap, OpenSSL, etc.). If nmap isn't found, make sure /usr/bin or /usr/local/bin is in your $PATH.

Understanding How Nmap Scanning Works

Before firing off commands, it helps to understand what Nmap actually does under the hood.

When you scan a target, Nmap sends carefully crafted packets to ports on the target machine and analyzes the responses. Based on how the target replies (or doesn't), Nmap determines whether a port is:

Open — A service is actively listening and accepting connections.
Closed — The port is reachable but no service is listening. The host responds with a RST packet.
Filtered — Nmap can't determine the state because a firewall is silently dropping packets. No response comes back, or an ICMP unreachable message does.

This distinction matters. An open port is an attack surface. A filtered port means a firewall is doing its job. A closed port means the service isn't running but the port is reachable — which still tells an attacker something about the system.

Basic Nmap Scans for Beginners

Let's start with the fundamentals. I'll use 192.168.1.100 as an example target — replace it with your own IP.

Simple Host Discovery (Ping Scan)

nmap -sn 192.168.1.0/24

This sends ICMP echo requests, TCP SYN to port 443, TCP ACK to port 80, and ICMP timestamps to every host in the subnet. It tells you which hosts are alive without scanning any ports. Useful for mapping your local network.

Expected output:

Nmap scan report for 192.168.1.1
Host is up (0.0023s latency).
Nmap scan report for 192.168.1.100
Host is up (0.0015s latency).
Nmap done: 256 IP addresses (2 hosts up) scanned in 3.42 seconds

Default Port Scan

nmap 192.168.1.100

Without any flags, Nmap scans the top 1,000 most common TCP ports using a SYN scan (if run as root) or a connect scan (as a regular user). This is the scan most beginners start with.

Scanning Specific Ports

# Single port
nmap -p 22 192.168.1.100

# Port range
nmap -p 1-1000 192.168.1.100

# Multiple specific ports
nmap -p 22,80,443,8080 192.168.1.100

# All 65535 ports
nmap -p- 192.168.1.100

The -p- flag is important. The default 1,000-port scan misses services running on non-standard ports. If you're auditing a server, always run a full port scan at least once. It takes longer (a few minutes depending on the network), but it catches things like databases on port 27017, admin panels on port 8443, or forgotten dev servers on high ports.

TCP SYN Scan (Stealth Scan)

sudo nmap -sS 192.168.1.100

The SYN scan sends a SYN packet and waits for a SYN-ACK (open) or RST (closed). It never completes the TCP handshake, which is why it's called "half-open" or "stealth" scanning. This is the default when running as root and is the fastest reliable scan type.

Note: Despite the name "stealth scan," modern intrusion detection systems (IDS) detect SYN scans easily. Don't rely on this for actual stealth — it's called that for historical reasons.

UDP Scan

sudo nmap -sU --top-ports 100 192.168.1.100

UDP scanning is painfully slow because UDP is connectionless — Nmap has to wait for timeouts to determine if a port is filtered. I typically limit it to the top 100 ports. Services like DNS (53), SNMP (161), DHCP (67/68), and NTP (123) use UDP, so skipping UDP scanning entirely means you're missing real attack surface.

Nmap Service and Version Detection

Knowing a port is open is step one. Knowing what's running on it is where things get useful.

nmap -sV 192.168.1.100

The -sV flag probes open ports to determine the service name and version. Instead of just seeing "port 22 open," you'll see something like:

PORT    STATE SERVICE  VERSION
22/tcp  open  ssh      OpenSSH 9.6p1 Ubuntu 3ubuntu13
80/tcp  open  http     nginx 1.24.0
443/tcp open  ssl/http nginx 1.24.0

This is critical for security auditing. If you see OpenSSH 7.2 running, you know it's vulnerable to several CVEs. If you see Apache 2.4.49, that's the path traversal vulnerability (CVE-2021-41773). Version detection turns a port list into an actionable vulnerability report.

You can control the intensity of version detection:

# Light probe (faster, less accurate)
nmap -sV --version-intensity 2 192.168.1.100

# Aggressive probe (slower, more accurate)
nmap -sV --version-intensity 9 192.168.1.100

Nmap OS Detection

sudo nmap -O 192.168.1.100

OS detection uses TCP/IP stack fingerprinting — analyzing things like TCP window sizes, TTL values, and how the target handles specific packet flags. It requires at least one open and one closed port to work reliably.

For a more aggressive and comprehensive scan that combines OS detection, version detection, script scanning, and traceroute:

sudo nmap -A 192.168.1.100

The -A flag is the "aggressive" scan. I use it when auditing my own servers because it gives the most complete picture in one command. Don't use it on networks you're trying to be quiet on — it's noisy.

Nmap NSE Scripts — The Real Power

The Nmap Scripting Engine (NSE) is what separates Nmap from a basic port scanner. NSE ships with hundreds of scripts for vulnerability detection, brute forcing, service enumeration, and more.

Running Default Scripts

nmap -sC 192.168.1.100

The -sC flag runs the "default" category of scripts — things like grabbing SSH host keys, checking HTTP titles, enumerating SSL certificates. These are considered safe and non-intrusive.

Running Specific Scripts

# Check for a specific vulnerability
nmap --script vuln 192.168.1.100

# Run a specific script
nmap --script http-headers 192.168.1.100

# Run multiple scripts
nmap --script "http-headers,http-title,ssl-enum-ciphers" -p 80,443 192.168.1.100

Useful NSE Scripts I Run Regularly

Check HTTP security headers (pairs well with my security headers guide):

nmap --script http-security-headers -p 80,443 <YOUR_SERVER_IP>

Enumerate SSL/TLS ciphers:

nmap --script ssl-enum-ciphers -p 443 <YOUR_SERVER_IP>

This reveals weak cipher suites, outdated TLS versions, and certificate issues. If you see TLSv1.0 or TLSv1.1 in the output, you need to fix your web server configuration.

Check for common vulnerabilities:

nmap --script vulners -sV -p 22,80,443 <YOUR_SERVER_IP>

The vulners script cross-references detected service versions against the Vulners database and reports known CVEs. It's not a replacement for a proper vulnerability scanner, but it's a fast first check.

Brute-force SSH (on your own systems only):

nmap --script ssh-brute -p 22 <YOUR_SERVER_IP>

This tests for weak SSH passwords. If it succeeds, you need to disable password authentication immediately — I covered how in my SSH hardening guide.

Finding All Available Scripts

ls /usr/share/nmap/scripts/ | wc -l

On a current install, you'll see 600+ scripts. Browse them by category:

ls /usr/share/nmap/scripts/ | grep http
ls /usr/share/nmap/scripts/ | grep ssh
ls /usr/share/nmap/scripts/ | grep vuln

Nmap Output Formats

Scan results are useless if you can't save and review them. Nmap supports multiple output formats.

# Normal text output
nmap -oN scan_results.txt 192.168.1.100

# XML output (for parsing with other tools)
nmap -oX scan_results.xml 192.168.1.100

# Grepable output (one host per line, easy to pipe)
nmap -oG scan_results.gnmap 192.168.1.100

# All formats at once
nmap -oA scan_results 192.168.1.100

I always use -oA for any serious scan. The XML output can be imported into tools like Metasploit or parsed with scripts. The grepable format is perfect for quick filtering:

# Find all hosts with port 22 open
grep "22/open" scan_results.gnmap

Real-World Nmap Scanning Examples

Here are the scans I actually run on my own infrastructure.

Full Audit of a Single Server

sudo nmap -sS -sV -sC -O -p- -oA full_audit <YOUR_SERVER_IP>

This combines a SYN scan, version detection, default scripts, and OS detection across all 65,535 ports. Takes 5-15 minutes depending on the network. I run this after every major configuration change.

Quick Check After Firewall Changes

nmap -sS -p 22,80,443 <YOUR_SERVER_IP>

After modifying firewall rules (iptables, ufw, etc.), I run a quick scan to verify only the intended ports are open. If you've been following my VPS hardening guide, you should see only SSH (22), HTTP (80), and HTTPS (443).

Network Sweep for Rogue Devices

sudo nmap -sn -oG alive_hosts.gnmap 192.168.1.0/24

Run this on your home or office network periodically. Compare the output over time. New hosts appearing that you don't recognize deserve investigation.

Scanning for a Specific Vulnerability

nmap --script smb-vuln-ms17-010 -p 445 192.168.1.0/24

This checks an entire subnet for EternalBlue (the vulnerability behind WannaCry). Replace with whatever CVE you're investigating. The OWASP Top 10 I covered in my OWASP guide often ties back to the kind of service misconfigurations Nmap reveals.

Nmap Scan Timing and Performance

Nmap has six timing templates, from T0 (paranoid) to T5 (insane):

# Slow and careful (IDS evasion)
nmap -T2 192.168.1.100

# Default (balanced)
nmap -T3 192.168.1.100

# Aggressive (fast, might miss things on slow networks)
nmap -T4 192.168.1.100

For scanning your own servers, T4 is the sweet spot — fast enough to not waste your time, reliable enough to not miss open ports. I only use T2 or lower when testing IDS detection capabilities on my own network.

You can also control parallelism directly:

# Scan with minimum 1000 packets per second
nmap --min-rate 1000 -p- 192.168.1.100

The --min-rate flag guarantees a minimum packet rate. This can dramatically speed up full port scans.

Security Considerations

Nmap is a double-edged tool. Everything in this nmap tutorial can be used offensively or defensively. Here's how to stay on the right side:

Document your scope. Before scanning, write down exactly what you're authorized to scan. Keep this documentation.
Never scan production systems during peak hours unless you've tested the impact. Aggressive scans can crash fragile services or trigger rate-limiting that affects real users.
Monitor your own systems for scans. Tools like Fail2ban (covered in my Fail2ban guide) and Suricata can alert you when someone scans your infrastructure.
Keep Nmap updated. New NSE scripts and fingerprints are added regularly. An outdated Nmap misses things.
Treat scan results as sensitive data. A full scan of your infrastructure is a roadmap for attackers. Store results securely and don't post them publicly.

Troubleshooting Common Nmap Issues

Problem: Nmap reports all ports as "filtered." Cause: A firewall (host-based or network) is dropping all probes. Cloud providers like AWS and Azure have security groups that block by default. Fix: Check your firewall rules (sudo ufw status or sudo iptables -L -n). If scanning a cloud instance, verify the security group allows inbound from your scanning IP.

Problem: OS detection returns "No exact OS matches." Cause: OS fingerprinting needs at least one open and one closed port. If every port is either open or filtered, it can't get a reliable fingerprint. Fix: Run a full port scan first (-p-) to find at least one closed port, or accept that OS detection won't work behind strict firewalls.

Problem: Scans are extremely slow. Cause: Network congestion, aggressive firewall rate-limiting, or scanning too many ports with version detection enabled. Fix: Use -T4 for faster timing. Split large scans into phases — do a quick port discovery first (-sS -p-), then run -sV only on open ports.

Problem: "Nmap requires root privileges for this scan type." Cause: SYN scans, OS detection, and UDP scans require raw socket access, which needs root. Fix: Use sudo before the command. Alternatively, use -sT (TCP connect scan), which works without root but is slower and more detectable.

Problem: NSE scripts are not found or fail to load. Cause: Script database is outdated or scripts weren't installed. Fix: Update the script database with sudo nmap --script-updatedb. On minimal installs, you may need to install nmap-scripts separately (sudo apt install nmap-common).

Conclusion

Nmap is one of those tools that scales with your skill. You can start with nmap <target> and get useful results, or go deep with NSE scripts and custom timing to audit entire networks. The key is understanding what each scan type does and when to use it.

If you're building out your security toolkit, start with the scans in this guide on your own infrastructure. Pair the results with the hardening steps in my VPS hardening guide and SSH hardening guide to close whatever Nmap finds.

The best defense starts with knowing what's exposed. Nmap tells you exactly that.

Self-Hosting Nextcloud with Docker Compose

byteguard — Tue, 23 Jun 2026 18:22:44 +0000

Originally published on byte-guard.net.

Google Drive gives you 15 GB for free and sells you convenience. In exchange, it scans your files, trains AI on your data, and can lock you out of your own account with no explanation and no appeal. If you have ever wondered what it takes to own your files entirely, Nextcloud is the answer.

This guide is part of our Self-Hosting Series — step-by-step guides for running your own services on a VPS.

Nextcloud is a self-hosted cloud platform that replaces Google Drive, Google Calendar, Google Contacts, and a dozen other SaaS tools -- all running on hardware you control. The catch? Setting it up properly takes more than a quick docker run. Misconfigure the database, skip the caching layer, or ignore PHP tuning, and you end up with something painfully slow.

In this guide, I will walk through how to self-host Nextcloud with Docker Compose, backed by MariaDB, fronted by Nginx as a reverse proxy with SSL, and tuned for actual usable performance. By the end, you will have a production-ready Nextcloud instance that you would actually want to use daily.

Prerequisites

A VPS with at least 2 CPU cores and 4 GB RAM -- Nextcloud with MariaDB and Redis needs room to breathe. I recommend Hetzner's CPX21 or higher. If you do not have a VPS yet, my guide on building a VPS from scratch covers the setup.
A domain name pointed at your server's IP (e.g., cloud.yourdomain.com)
Docker and Docker Compose installed (Docker security guide covers secure installation)
Ports 80 and 443 open on your firewall
SSH access to your server

Setting Up the Project Structure

Start by creating a directory for the Nextcloud stack:

mkdir -p /opt/nextcloud && cd /opt/nextcloud

Create an environment file to store sensitive values. Never hardcode credentials in your compose file.

touch .env
chmod 600 .env

Add the following to .env:

# /opt/nextcloud/.env
MYSQL_ROOT_PASSWORD=<GENERATE_A_STRONG_PASSWORD>
MYSQL_PASSWORD=<GENERATE_ANOTHER_STRONG_PASSWORD>
MYSQL_DATABASE=nextcloud
MYSQL_USER=nextcloud
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=<YOUR_ADMIN_PASSWORD>
NEXTCLOUD_TRUSTED_DOMAINS=cloud.<YOUR_DOMAIN>

Generate strong passwords with:

openssl rand -base64 32

The Docker Compose Configuration

Here is the complete docker-compose.yml with Nextcloud, MariaDB, and Redis:

# /opt/nextcloud/docker-compose.yml
version: "3.8"

services:
  db:
    image: mariadb:11
    container_name: nextcloud-db
    restart: unless-stopped
    command: >
      --transaction-isolation=READ-COMMITTED
      --log-bin=binlog
      --binlog-format=ROW
      --innodb-file-per-table=1
      --innodb-buffer-pool-size=256M
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
    networks:
      - nextcloud_net
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: nextcloud-redis
    restart: unless-stopped
    command: redis-server --requirepass redis_secret_password
    volumes:
      - redis_data:/data
    networks:
      - nextcloud_net
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "redis_secret_password", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: nextcloud:29-apache
    container_name: nextcloud-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - nextcloud_data:/var/www/html
      - ./custom-php.ini:/usr/local/etc/php/conf.d/zzz-custom.ini:ro
    environment:
      MYSQL_HOST: db
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      NEXTCLOUD_ADMIN_USER: ${NEXTCLOUD_ADMIN_USER}
      NEXTCLOUD_ADMIN_PASSWORD: ${NEXTCLOUD_ADMIN_PASSWORD}
      NEXTCLOUD_TRUSTED_DOMAINS: ${NEXTCLOUD_TRUSTED_DOMAINS}
      REDIS_HOST: redis
      REDIS_HOST_PASSWORD: redis_secret_password
      APACHE_DISABLE_REWRITE_IP: 1
      TRUSTED_PROXIES: 172.0.0.0/8
      OVERWRITEPROTOCOL: https
      OVERWRITECLIURL: https://${NEXTCLOUD_TRUSTED_DOMAINS}
    networks:
      - nextcloud_net
    ports:
      - "127.0.0.1:8080:80"

  cron:
    image: nextcloud:29-apache
    container_name: nextcloud-cron
    restart: unless-stopped
    depends_on:
      - app
    volumes:
      - nextcloud_data:/var/www/html
    entrypoint: /cron.sh
    networks:
      - nextcloud_net

volumes:
  db_data:
  redis_data:
  nextcloud_data:

networks:
  nextcloud_net:
    driver: bridge

Let me break down the key decisions:

MariaDB over SQLite: Nextcloud supports SQLite, but it falls apart with more than one user or any concurrent file operations. MariaDB is the recommended production database. The --transaction-isolation=READ-COMMITTED flag is specifically required by Nextcloud.

Redis for caching and locking: Without Redis, Nextcloud uses the database for file locking and caching, which kills performance. Redis handles both file locking (preventing conflicts during sync) and memory caching.

Dedicated cron container: Nextcloud needs background jobs for file scanning, notifications, and cleanup. Running a separate container with /cron.sh is more reliable than AJAX-based cron, which depends on users visiting the web interface.

Port binding to 127.0.0.1: The 127.0.0.1:8080:80 binding ensures Nextcloud is only accessible through the reverse proxy, not directly on port 8080 from the internet.

PHP Performance Tuning

Create the custom PHP configuration file referenced in the compose file:

; /opt/nextcloud/custom-php.ini
; Memory and upload limits
memory_limit = 1024M
upload_max_filesize = 16G
post_max_size = 16G
max_execution_time = 3600
max_input_time = 3600

; OPcache settings (critical for performance)
opcache.enable = 1
opcache.interned_strings_buffer = 32
opcache.max_accelerated_files = 10000
opcache.memory_consumption = 256
opcache.save_comments = 1
opcache.revalidate_freq = 60
opcache.jit = 1255
opcache.jit_buffer_size = 128M

; Output buffering
output_buffering = Off

Why this matters: The default PHP memory_limit of 128 MB causes Nextcloud to choke on file previews and large uploads. OPcache is the single biggest performance improvement you can make -- it caches compiled PHP code in memory so it does not need to be recompiled on every request. The JIT compiler (available in PHP 8+) adds another layer of optimization.

The upload_max_filesize of 16 GB lets you upload large files. Adjust this based on your storage capacity.

Configuring the Nginx Reverse Proxy

If you are using Nginx Proxy Manager (which I compared against Traefik and Caddy in my reverse proxy comparison), you can create a new proxy host through the UI pointing to http://127.0.0.1:8080 with SSL enabled.

For a manual Nginx configuration:

# /etc/nginx/sites-available/nextcloud.conf

upstream nextcloud_backend {
    server 127.0.0.1:8080;
    keepalive 64;
}

server {
    listen 80;
    server_name cloud.<YOUR_DOMAIN>;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name cloud.<YOUR_DOMAIN>;

    # SSL certificates (use certbot or your preferred method)
    ssl_certificate /etc/letsencrypt/live/cloud.<YOUR_DOMAIN>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cloud.<YOUR_DOMAIN>/privkey.pem;

    # SSL hardening
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers off;

    # Upload size -- must match PHP settings
    client_max_body_size 16G;
    client_body_buffer_size 512k;

    # Timeouts for large file operations
    proxy_connect_timeout 3600;
    proxy_send_timeout 3600;
    proxy_read_timeout 3600;
    send_timeout 3600;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # CalDAV/CardDAV discovery
    location /.well-known/carddav {
        return 301 $scheme://$host/remote.php/dav;
    }
    location /.well-known/caldav {
        return 301 $scheme://$host/remote.php/dav;
    }
    location /.well-known/webfinger {
        return 301 $scheme://$host/index.php/.well-known/webfinger;
    }
    location /.well-known/nodeinfo {
        return 301 $scheme://$host/index.php/.well-known/nodeinfo;
    }

    location / {
        proxy_pass http://nextcloud_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # WebSocket support (for Notify Push)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the site and obtain an SSL certificate:

ln -s /etc/nginx/sites-available/nextcloud.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

# Get SSL certificate with certbot
certbot --nginx -d cloud.<YOUR_DOMAIN>

Note: The .well-known redirects are essential for CalDAV and CardDAV discovery. Without them, calendar and contact sync will fail on mobile devices. The client_max_body_size must match your PHP upload_max_filesize setting, or Nginx will reject large uploads before PHP even sees them.

Launching Nextcloud

Bring up the stack:

cd /opt/nextcloud
docker compose up -d

Watch the logs to verify everything starts cleanly:

docker compose logs -f app

You should see Nextcloud's installation routine run automatically (creating the admin user and configuring the database). This takes 30-60 seconds on first launch.

Once the logs settle, visit https://cloud.<YOUR_DOMAIN> in your browser. You should see the Nextcloud login page. Sign in with the admin credentials from your .env file.

Post-Installation Configuration

Verify Redis Caching

After logging in as admin, go to Administration Settings > Overview. Check that there are no warnings about the caching backend. You can also verify Redis is connected:

docker exec nextcloud-redis redis-cli -a redis_secret_password INFO clients

You should see at least one connected client (the Nextcloud app).

Configure the Nextcloud Config File

Some settings need to be added directly to Nextcloud's config.php. Access it through the Docker volume:

docker exec -it nextcloud-app cat /var/www/html/config/config.php

If you need to edit it:

docker exec -it nextcloud-app vi /var/www/html/config/config.php

Verify these settings are present (most should be set automatically by the environment variables):

'trusted_domains' =>
  array (
    0 => 'cloud.<YOUR_DOMAIN>',
  ),
'overwrite.cli.url' => 'https://cloud.<YOUR_DOMAIN>',
'overwriteprotocol' => 'https',
'memcache.local' => '\\OC\\Memcache\\APCu',
'memcache.distributed' => '\\OC\\Memcache\\Redis',
'memcache.locking' => '\\OC\\Memcache\\Redis',
'redis' =>
  array (
    'host' => 'redis',
    'password' => 'redis_secret_password',
    'port' => 6379,
  ),
'default_phone_region' => 'US',
'maintenance_window_start' => 1,

The maintenance_window_start tells Nextcloud when to run heavy background tasks (value is UTC hour, so 1 means 1:00 AM UTC).

Set Background Jobs to Cron

Go to Administration Settings > Basic settings and set the background jobs method to Cron. Since we have a dedicated cron container, this is already handled -- but you need to tell Nextcloud to expect it.

Verify cron is running:

docker exec nextcloud-app php -f /var/www/html/cron.php
docker logs nextcloud-cron --tail 5

Essential Apps to Enable

Nextcloud has a large app ecosystem. Here are the ones I consider essential for a production setup:

# Install apps via the command line (faster than the web UI)
docker exec -u www-data nextcloud-app php occ app:install calendar
docker exec -u www-data nextcloud-app php occ app:install contacts
docker exec -u www-data nextcloud-app php occ app:install tasks
docker exec -u www-data nextcloud-app php occ app:install notes
docker exec -u www-data nextcloud-app php occ app:install deck
docker exec -u www-data nextcloud-app php occ app:install previewgenerator

App	Replaces	Why Install It
Calendar	Google Calendar	CalDAV-based, syncs with any calendar app
Contacts	Google Contacts	CardDAV-based, syncs with phone contacts
Tasks	Google Tasks, Todoist	Integrates with Calendar
Notes	Google Keep	Markdown support, folder organization
Deck	Trello	Kanban boards with Calendar integration
Preview Generator	--	Pre-generates image thumbnails for faster browsing

After installing Preview Generator, run the initial generation:

docker exec -u www-data nextcloud-app php occ preview:generate-all

This takes a while if you have existing files. After the initial run, the cron job handles new files automatically.

Security Considerations

Brute force protection is built into Nextcloud and enabled by default. It rate-limits login attempts per IP. Verify it is active under Administration Settings > Security.

Two-factor authentication -- enable it immediately for the admin account. Go to Personal Settings > Security and set up TOTP (works with any authenticator app). For other users, you can enforce 2FA under Administration Settings > Security.

File encryption -- Nextcloud supports server-side encryption, but think carefully before enabling it. It protects files at rest (useful if someone steals your disk), but it adds CPU overhead, makes disaster recovery harder, and does not protect against a compromised server (since the keys are stored on the same server). For most self-hosting scenarios, full-disk encryption (LUKS) at the OS level is a better approach.

Expose only what you need. The Docker Compose file already binds Nextcloud to 127.0.0.1:8080, so it is only accessible through the reverse proxy. Make sure your firewall blocks direct access to port 8080 from outside.

Keep it updated. Nextcloud publishes security advisories regularly. Check for updates in the admin panel or via CLI:

docker exec -u www-data nextcloud-app php occ update:check

To upgrade, update the image tag in docker-compose.yml and recreate the container:

docker compose pull app cron
docker compose up -d app cron

Warning: Always back up your database and data volume before upgrading. Major version upgrades (e.g., 28 to 29) sometimes require manual migration steps.

Troubleshooting

Problem: "Access through untrusted domain" error when visiting the site. Cause: The domain you are accessing is not listed in Nextcloud's trusted_domains array. Fix: Edit config.php inside the container and add your domain to the trusted_domains array. Or set the NEXTCLOUD_TRUSTED_DOMAINS environment variable and recreate the container.

Problem: File uploads fail for files larger than a few megabytes. Cause: Either Nginx's client_max_body_size, PHP's upload_max_filesize, or PHP's post_max_size is too low. Fix: All three values must match. Check your custom-php.ini and your Nginx configuration. After changes, restart both Nginx and the Nextcloud container.

Problem: Nextcloud dashboard shows "No memory cache configured" warning. Cause: Redis connection failed or the caching configuration is missing from config.php. Fix: Verify Redis is running (docker logs nextcloud-redis). Check that the Redis password in config.php matches the one in docker-compose.yml. Test connectivity: docker exec nextcloud-app apt-get update && apt-get install -y redis-tools && redis-cli -h redis -a redis_secret_password ping.

Problem: Calendar and contact sync fails on mobile devices. Cause: Missing .well-known redirects for CalDAV and CardDAV discovery. Fix: Add the .well-known location blocks to your Nginx configuration (shown in the reverse proxy section above). The URLs /.well-known/carddav and /.well-known/caldav must redirect to /remote.php/dav.

Problem: Nextcloud is extremely slow, pages take 5-10 seconds to load. Cause: OPcache is not enabled, or the cron container is not running (causing background jobs to pile up). Fix: Verify custom-php.ini is mounted correctly: docker exec nextcloud-app php -i | grep opcache.enable. It should show opcache.enable => On. Also verify the cron container is running: docker compose ps cron.

Conclusion

You now have a fully functional, performance-tuned Nextcloud instance running on Docker with MariaDB for the database, Redis for caching, and Nginx handling SSL termination. This setup replaces Google Drive, Calendar, Contacts, and several other services -- all on infrastructure you own.

The key performance wins: Redis for caching and file locking, OPcache with JIT enabled, and a dedicated cron container for background jobs. Without these three, Nextcloud feels sluggish. With them, it is genuinely pleasant to use.

For next steps, consider setting up automated backups (a pg_dump equivalent for MariaDB is mariadb-dump), connecting the Nextcloud desktop and mobile sync clients, and exploring the app ecosystem.

If you are choosing a reverse proxy for your setup, I compared the top three options in my Nginx Proxy Manager vs Traefik vs Caddy post. And if you need a reliable VPS to host Nextcloud, I run all my projects on Hetzner -- great performance, fair pricing, and EU-based data centers. Check out Hetzner's cloud plans.

How to Self-Host Gitea with Docker Compose

byteguard — Tue, 23 Jun 2026 18:22:07 +0000

Originally published on byte-guard.net.

GitHub is free, reliable, and deeply integrated into every developer's workflow. So why would anyone self-host Gitea as an alternative? Control. Your code, your data, your rules. No surprise policy changes, no training AI models on your private repositories, no vendor lock-in. If Microsoft decides tomorrow that free private repos require a new plan, you are stuck. With Gitea running on your own VPS, you answer to no one.

This guide is part of our Self-Hosting Series — step-by-step guides for running your own services on a VPS.

Gitea is a lightweight, self-hosted Git service written in Go. It consumes around 200MB of RAM under normal usage — a fraction of what GitLab demands. It includes pull requests, issues, a package registry, and since version 1.19, Gitea Actions — a CI/CD system compatible with GitHub Actions workflows. For a personal or small-team setup, it is the best self-hosted Git option available.

In this guide, I will walk through a complete production-ready Gitea deployment: Docker Compose with PostgreSQL, reverse proxy configuration, SSH passthrough for Git operations, CI/CD with Gitea Actions, and migrating your existing repositories from GitHub.

Prerequisites

A Linux VPS (Ubuntu 22.04 or Debian 12) with at least 1 GB RAM and 20 GB storage
Docker Engine 24+ and Docker Compose v2 installed
A domain name pointing to your VPS (e.g., git.yourdomain.com)
A reverse proxy (Nginx Proxy Manager, Caddy, or Traefik) — I use Nginx Proxy Manager as described in my VPS setup guide
Basic familiarity with Docker and Git
SSH access to your server — see my Vaultwarden guide for managing credentials securely

If you need a VPS, I run all my self-hosted services on a Hetzner CPX22. It handles Ghost, Uptime Kuma, Nginx Proxy Manager, and Gitea without breaking a sweat.

Setting Up the Directory Structure

Create a dedicated directory for Gitea:

sudo mkdir -p /opt/gitea
cd /opt/gitea

I keep all my Docker services under /opt/ with one directory per service. This makes backups and management predictable.

Docker Compose Configuration

Create the Compose file:

# /opt/gitea/docker-compose.yml
services:
  gitea:
    image: gitea/gitea:1.22-rootless
    container_name: gitea
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${DB_PASSWORD}
      - GITEA__server__ROOT_URL=https://<YOUR_DOMAIN>/
      - GITEA__server__SSH_DOMAIN=<YOUR_DOMAIN>
      - GITEA__server__SSH_PORT=2222
      - GITEA__server__LFS_START_SERVER=true
      - GITEA__service__DISABLE_REGISTRATION=true
      - GITEA__mailer__ENABLED=false
      - GITEA__openid__ENABLE_OPENID_SIGNIN=false
    volumes:
      - gitea-data:/var/lib/gitea
      - gitea-config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:2222"
    networks:
      - gitea-net

  db:
    image: postgres:16-alpine
    container_name: gitea-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=gitea
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - gitea-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  gitea-data:
  gitea-config:
  postgres-data:

networks:
  gitea-net:
    driver: bridge

A few important decisions in this configuration:

Rootless image (gitea/gitea:1.22-rootless): The container runs as a non-root user. This is a security best practice I covered in my Docker security guide. If an attacker escapes the Gitea process, they land as an unprivileged user.
PostgreSQL over SQLite: SQLite works for personal use, but PostgreSQL handles concurrent connections better and makes backups more reliable. The overhead is minimal — PostgreSQL Alpine uses about 30MB of RAM.
Registration disabled: DISABLE_REGISTRATION=true prevents random people from creating accounts on your instance. You create accounts via the admin panel or CLI.
Health check on PostgreSQL: The depends_on with condition: service_healthy ensures Gitea does not start before the database is ready. Without this, Gitea may crash on first boot and require a manual restart.

Creating the Environment File

cat > /opt/gitea/.env << 'EOF'
DB_PASSWORD=<YOUR_SECURE_PASSWORD>
EOF
chmod 600 /opt/gitea/.env

Generate a strong password:

openssl rand -base64 32

Replace <YOUR_SECURE_PASSWORD> with the generated value. Replace <YOUR_DOMAIN> in the Compose file with your actual domain (e.g., git.byte-guard.net).

Note: Never commit .env files to version control. The chmod 600 ensures only the file owner can read it.

Starting Gitea

cd /opt/gitea && docker compose up -d

Check that both containers are running:

docker compose ps

Expected output:

NAME        SERVICE   STATUS
gitea       gitea     Up (healthy)
gitea-db    db        Up (healthy)

Gitea is now listening on port 3000 (HTTP) and port 2222 (SSH).

Reverse Proxy Configuration

You should never expose Gitea directly on port 3000. Put it behind a reverse proxy with TLS.

Nginx Proxy Manager

If you use Nginx Proxy Manager (as I do on all my projects):

Add a new proxy host
Domain: git.yourdomain.com
Forward Hostname: gitea (or the server IP if NPM runs in a different Docker network)
Forward Port: 3000
SSL: Request a new Let's Encrypt certificate, force SSL

If NPM and Gitea are on different Docker networks, either add Gitea to NPM's network or use the host IP:

# Add to the gitea service in docker-compose.yml
networks:
  - gitea-net
  - npm-network

# Add at the bottom
networks:
  gitea-net:
    driver: bridge
  npm-network:
    external: true

Caddy (Alternative)

If you prefer Caddy as your reverse proxy:

git.yourdomain.com {
    reverse_proxy gitea:3000
}

Caddy handles TLS automatically — no certificate configuration needed.

Initial Setup

Open https://git.yourdomain.com in your browser. On first visit, Gitea shows an installation page. Most settings are already configured via environment variables, but verify:

Site Title: Your preferred name (e.g., "ByteGuard Git")
Admin Account: Create your admin user here — this is the only chance to do it through the web UI before registration is disabled

Click "Install Gitea." The page will redirect to the login screen.

Creating Additional Users via CLI

Since registration is disabled, add users through the Gitea CLI:

docker exec -it gitea gitea admin user create \
  --username developer \
  --password '<STRONG_PASSWORD>' \
  --email developer@yourdomain.com

SSH Passthrough for Git Operations

Git over HTTPS works immediately through the reverse proxy. But serious Git users prefer SSH for authentication — no password prompts, no token management, better performance for large pushes.

The Compose file already maps port 2222 from the container to the host. Configure your SSH client to use this port:

cat >> ~/.ssh/config << 'EOF'

Host git.yourdomain.com
    HostName git.yourdomain.com
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
EOF

Add your public key to Gitea through the web UI: Settings → SSH / GPG Keys → Add Key.

Test the connection:

ssh -T git@git.yourdomain.com

Expected output:

Hi there, <username>! You've successfully authenticated, but Gitea does not provide shell access.

Now clone repositories using SSH:

git clone git@git.yourdomain.com:<username>/<repo>.git

Using Port 22 Instead of 2222

If you want standard SSH Git operations on port 22, you have two options:

Option A: Move your system SSH to a different port (e.g., 2222) and give port 22 to Gitea. Update your server's SSH config in /etc/ssh/sshd_config:

Port 2200

Then change the Gitea port mapping to "22:2222".

Option B (recommended): Use SSH passthrough. This is more complex but lets both system SSH and Gitea SSH coexist on port 22. It requires adding the git user on the host and configuring AuthorizedKeysCommand in sshd. The Gitea documentation covers this in detail — I recommend Option A for most self-hosters because it is simpler to maintain.

CI/CD with Gitea Actions

Gitea Actions (available since v1.19) is compatible with GitHub Actions workflow syntax. If you have existing GitHub Actions workflows, they work in Gitea with minimal changes.

Enabling Actions

Add the Actions configuration to your Gitea environment variables:

# Add to the gitea service environment in docker-compose.yml
- GITEA__actions__ENABLED=true

Restart Gitea:

cd /opt/gitea && docker compose up -d

Setting Up an Actions Runner

Gitea Actions requires a runner — a separate process that picks up jobs and executes them. This is identical to GitHub's self-hosted runner concept.

First, get a registration token from Gitea. Navigate to Site Administration → Runners and copy the registration token.

Add the runner to your Compose file:

  runner:
    image: gitea/act_runner:latest
    container_name: gitea-runner
    restart: unless-stopped
    depends_on:
      - gitea
    environment:
      - GITEA_INSTANCE_URL=http://gitea:3000
      - GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
      - GITEA_RUNNER_NAME=local-runner
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - runner-data:/data
    networks:
      - gitea-net

Add runner-data to the volumes section and RUNNER_TOKEN to your .env file.

Note: The runner needs Docker socket access because it launches job containers. This is a security consideration — review my Docker security guide section on socket protection. For a personal instance, the risk is manageable. For a team, consider running the runner on a separate host.

Creating a Workflow

In any repository, create .gitea/workflows/ci.yml:

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          echo "Running tests..."
          # Replace with your actual test command
          make test

Push this file, and Gitea Actions will pick it up automatically. Check the Actions tab in your repository to see the workflow status.

Migrating Repositories from GitHub

Gitea has a built-in migration tool that imports repositories including issues, pull requests, labels, milestones, releases, and wiki pages.

Via the Web UI

Click + → New Migration
Select GitHub as the source
Enter the repository URL (e.g., https://github.com/youruser/yourrepo)
For private repos, provide a GitHub Personal Access Token with repo scope
Select what to migrate (issues, PRs, labels, etc.)
Click Migrate Repository

Via the API (Bulk Migration)

For migrating many repositories, use the Gitea API:

#!/bin/bash
# migrate-repos.sh
GITEA_URL="https://git.yourdomain.com"
GITEA_TOKEN="<YOUR_GITEA_API_TOKEN>"
GITHUB_TOKEN="<YOUR_GITHUB_TOKEN>"
GITHUB_USER="<YOUR_GITHUB_USERNAME>"

# Get list of GitHub repos
repos=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/user/repos?per_page=100&type=owner" | \
  jq -r '.[].clone_url')

for repo_url in $repos; do
  repo_name=$(basename "$repo_url" .git)
  echo "Migrating $repo_name..."

  curl -s -X POST "$GITEA_URL/api/v1/repos/migrate" \
    -H "Authorization: token $GITEA_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"clone_addr\": \"$repo_url\",
      \"auth_token\": \"$GITHUB_TOKEN\",
      \"repo_name\": \"$repo_name\",
      \"repo_owner\": \"$(echo $GITEA_TOKEN | cut -d: -f1)\",
      \"service\": \"github\",
      \"mirror\": false,
      \"issues\": true,
      \"pull_requests\": true,
      \"labels\": true,
      \"milestones\": true,
      \"releases\": true
    }"

  echo " Done."
done

Set "mirror": true if you want Gitea to periodically sync from GitHub rather than making a one-time copy. Mirroring is useful during a transition period when you are still pushing to both.

Backup Strategy

Your Git repositories contain irreplaceable work. Back them up.

Database Backup

docker exec gitea-db pg_dump -U gitea gitea > /opt/gitea/backups/gitea-db-$(date +%Y%m%d).sql

Repository Data Backup

docker run --rm \
  -v gitea-data:/data:ro \
  -v /opt/gitea/backups:/backup \
  alpine tar czf /backup/gitea-data-$(date +%Y%m%d).tar.gz -C /data .

Automated Daily Backups

Create a cron job:

cat > /etc/cron.daily/gitea-backup << 'SCRIPT'
#!/bin/bash
BACKUP_DIR="/opt/gitea/backups"
mkdir -p "$BACKUP_DIR"

# Database
docker exec gitea-db pg_dump -U gitea gitea > "$BACKUP_DIR/gitea-db-$(date +%Y%m%d).sql"

# Data volumes
docker run --rm \
  -v gitea-data:/data:ro \
  -v "$BACKUP_DIR":/backup \
  alpine tar czf "/backup/gitea-data-$(date +%Y%m%d).tar.gz" -C /data .

# Retain 30 days
find "$BACKUP_DIR" -name "*.sql" -mtime +30 -delete
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

echo "$(date): Gitea backup completed" >> /var/log/gitea-backup.log
SCRIPT
chmod +x /etc/cron.daily/gitea-backup

Security Considerations

Self-hosting a Git server means you are responsible for its security. Here is what matters most:

Disable public registration. I set DISABLE_REGISTRATION=true in the Compose file. If you leave registration open, bots will create accounts within hours.

Use the rootless image. The gitea/gitea:1.22-rootless image runs as UID 1000 instead of root. If an attacker exploits a Gitea vulnerability, they cannot escalate to root inside the container.

Restrict SSH access. Only expose the SSH port (2222) if you need Git-over-SSH. If HTTPS-only is acceptable for your workflow, remove the SSH port mapping entirely.

Keep Gitea updated. Gitea releases security patches frequently. Pin a minor version (e.g., 1.22) rather than latest to avoid surprise breaking changes, but update regularly:

cd /opt/gitea
docker compose pull
docker compose up -d

Protect the runner. The Actions runner has Docker socket access. Do not run untrusted workflows. For a personal instance, this is fine. For a team, restrict who can create workflows via repository permissions.

Enable two-factor authentication. In Gitea's admin panel, you can require 2FA for all users. Do this — passwords alone are not enough.

Troubleshooting

Problem: Gitea shows "502 Bad Gateway" behind the reverse proxy. Cause: The reverse proxy cannot reach Gitea on port 3000, usually because they are on different Docker networks. Fix: Either add both services to the same Docker network (shown in the Nginx Proxy Manager section above) or use host.docker.internal as the forward hostname. Verify with docker exec npm curl -s http://gitea:3000.

Problem: SSH clone fails with "Connection refused" on port 2222. Cause: The port mapping is not working, or your firewall blocks port 2222. Fix: Verify the port is listening with ss -tlnp | grep 2222. If not, check docker compose ps to confirm the container is running. If the port is listening but connections fail, open it in your firewall: sudo ufw allow 2222/tcp.

Problem: Gitea Actions workflow stuck in "Waiting" status. Cause: No runner is registered, or the runner is offline. Fix: Check runner status in Site Administration → Runners. If no runner is listed, verify the GITEA_RUNNER_REGISTRATION_TOKEN matches what Gitea shows. Check runner logs with docker logs gitea-runner.

Problem: Migration from GitHub fails with "401 Unauthorized." Cause: The GitHub Personal Access Token has expired or lacks the repo scope. Fix: Generate a new token at github.com/settings/tokens with the repo scope. Classic tokens work more reliably than fine-grained tokens for migration.

Problem: PostgreSQL container fails to start with "could not access directory." Cause: The volume permissions are wrong, usually after restoring from a backup. Fix: Check ownership inside the volume: docker run --rm -v postgres-data:/data alpine ls -la /data. PostgreSQL requires the data directory to be owned by UID 70 (the postgres user in Alpine). Fix with docker run --rm -v postgres-data:/data alpine chown -R 70:70 /data.

Conclusion

You now have a fully functional, self-hosted Git service with PostgreSQL for reliability, SSH passthrough for developer convenience, CI/CD with Gitea Actions, and automated backups. The entire stack uses around 300MB of RAM and runs comfortably on the smallest VPS tier.

Gitea is not a GitHub replacement in terms of social features and ecosystem. It is a GitHub replacement in terms of functionality you actually use daily: hosting code, reviewing pull requests, tracking issues, and running CI pipelines. The trade-off is maintenance responsibility — you own the uptime, the backups, and the security updates.

For related self-hosting guides, check out my post on self-hosting Vaultwarden for password management alongside your Git server, and my Docker security best practices for hardening the containers running Gitea.

If you are setting up a self-hosted development environment, you will need a reliable VPS. I use Hetzner for all my projects — the CPX22 in Helsinki gives me solid performance for around 5 euros per month, and you can follow my infrastructure guide to get the base setup running.

How to Build a Home Lab with Proxmox VE

byteguard — Tue, 23 Jun 2026 18:21:30 +0000

Originally published on byte-guard.net.

A VPS is great for running production services, but for learning, testing, and breaking things on purpose, nothing beats a home lab. I run my production blog on a Hetzner VPS, but my Proxmox home lab is where I test Docker configs, spin up vulnerable machines for CTF practice, and experiment with networking — all without risking anything that matters.

Proxmox VE (Virtual Environment) is a free, open-source hypervisor built on Debian that supports both full virtual machines (KVM) and lightweight containers (LXC). It has a web-based management interface, built-in backup tools, and clustering support. If you want a proxmox home lab setup that grows with your skills, this guide gets you from bare hardware to running VMs and containers.

Prerequisites

Hardware: A dedicated machine with at least 8GB RAM, a 64-bit CPU with virtualization support (Intel VT-x or AMD-V), and 120GB+ storage. An old desktop, a mini PC (like an Intel NUC or Beelink), or a used Dell Optiplex all work well.
A USB drive (2GB+) for the Proxmox installer
Network access (Ethernet recommended — WiFi is possible but painful)
A separate computer to access the Proxmox web interface
Basic Linux familiarity — if you need a refresher, my VPS hardening guide covers core Linux admin concepts

Note: Proxmox is a bare-metal hypervisor. It replaces whatever OS is currently on the machine. Don't install it on your daily-use computer. Dedicate hardware to it.

What Is Proxmox VE and Why Use It

Proxmox VE is a Type 1 hypervisor — it runs directly on hardware, not inside another operating system. This gives it better performance than Type 2 hypervisors like VirtualBox or VMware Workstation that run on top of Windows or Linux.

Here's what makes Proxmox the best choice for a home lab:

Free and open source. The enterprise subscription is optional — it unlocks the stable update repository and support, but the free "no-subscription" repository works fine for home use.
Full VMs (KVM) and containers (LXC) on the same platform. Use VMs when you need full OS isolation, containers when you want lightweight services.
Web-based management. Everything is done through a browser. No GUI installed on the host.
Snapshots and backups built in. Break something? Roll back in seconds.
Clustering. Start with one node, add more later. Proxmox scales from a single NUC to a rack of servers.

The trade-off: Proxmox's learning curve is steeper than spinning up a VM in VirtualBox. You're managing a real hypervisor with networking, storage pools, and resource allocation. That's also exactly why it's worth learning — these are production skills.

Hardware Recommendations for a Proxmox Home Lab

You don't need expensive hardware. Here's what I recommend at three budget levels:

Budget ($50-100 — used hardware): - Dell Optiplex 7050 or HP EliteDesk 800 G3 (used on eBay) - 16GB DDR4 RAM (upgrade from stock) - 256GB SSD - Runs 3-5 lightweight VMs or 10+ containers comfortably

Mid-range ($200-400 — mini PC): - Beelink SER5 or Intel NUC 12/13 - 32GB DDR4/DDR5 RAM - 500GB NVMe SSD - Runs 8-10 VMs or 20+ containers, enough for a serious lab

Performance ($500+ — enterprise surplus): - Dell PowerEdge T340/R640 or HP DL360 - 64GB+ ECC RAM - Multiple SSDs in ZFS mirror - Enterprise networking (IPMI/iDRAC for remote management)

My advice: Start cheap. A $75 used Optiplex with a RAM upgrade teaches you everything. Upgrade when you hit limits, not before.

Installing Proxmox VE

Step 1: Download the ISO

Grab the latest Proxmox VE ISO from the official site:

https://www.proxmox.com/en/downloads/proxmox-virtual-environment/iso

Download the .iso file (about 1.2GB).

Step 2: Create a Bootable USB

On Linux:

# Find your USB drive (be CAREFUL — wrong device = data loss)
lsblk

# Write the ISO (replace sdX with your USB device)
sudo dd bs=4M if=proxmox-ve_8.x-x.iso of=/dev/sdX conv=fsync status=progress

On Windows, use Rufus or Etcher. Select "DD mode" if Rufus asks — ISO mode won't boot correctly for Proxmox.

Warning: The dd command will destroy all data on the target device. Triple-check the device name with lsblk before running it. If your main drive is /dev/sda, your USB is probably /dev/sdb — but verify.

Step 3: Boot and Install

Plug the USB into your Proxmox machine and boot from it (F2/F12/Del for BIOS/boot menu, varies by manufacturer).
Select Install Proxmox VE (Graphical).
Accept the EULA.
Select the target disk. Proxmox will format this entire disk. If you have multiple drives, pick the one you want as the boot/system drive. For the filesystem, choose ext4 for simplicity or ZFS if you have multiple drives and want redundancy.
Set your country, timezone, and keyboard layout.
Set a strong root password and enter an email address (used for alerts).
Configure networking: - Management Interface: Select your Ethernet adapter - Hostname: Something like pve.homelab.local - IP Address: Assign a static IP on your LAN (e.g., 192.168.1.50/24) - Gateway: Your router's IP (usually 192.168.1.1) - DNS Server: Your router or 1.1.1.1
Review the summary and click Install.

Installation takes 3-5 minutes. When done, remove the USB and reboot.

Step 4: Access the Web Interface

From another computer on the same network, open a browser and go to:

https://192.168.1.50:8006

Replace with the IP you set during installation. You'll get a certificate warning — that's expected (Proxmox uses a self-signed cert). Accept it and log in with:

Username: root
Realm: Linux PAM standard authentication
Password: The password you set during install

You're in. The Proxmox dashboard shows your node's CPU, RAM, storage, and network usage.

Post-Install Configuration

Disable the Enterprise Repository (Free Users)

By default, Proxmox is configured to use the enterprise repository, which requires a paid subscription. Without it, you'll get errors on apt update. Fix this:

# SSH into your Proxmox host
ssh root@192.168.1.50

# Disable the enterprise repo
sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list

# Add the free no-subscription repo
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-no-subscription.list

# Update and upgrade
apt update && apt full-upgrade -y

Remove the Subscription Nag (Optional)

Every time you log into the web UI, a popup reminds you that you don't have a subscription. It's harmless but annoying. To remove it:

sed -Ezi.bak "s/(Ext\.Msg\.show\(\{\s+title: gettext\('No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js
systemctl restart pveproxy.service

Note: This change gets overwritten on Proxmox updates. You'll need to reapply it after upgrades. If you use Proxmox professionally, consider buying a subscription — it supports the project.

Enable IOMMU (For GPU/PCI Passthrough)

If you plan to pass physical hardware (like a GPU) into a VM, enable IOMMU now:

# For Intel CPUs, edit GRUB
nano_is_not_allowed  # edit with vim instead
vim /etc/default/grub

Change the GRUB_CMDLINE_LINUX_DEFAULT line:

For Intel CPUs:

GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on"

For AMD CPUs:

GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on"

Then update GRUB and reboot:

update-grub
reboot

Creating Your First Virtual Machine

Let's create an Ubuntu Server VM — the most common starting point.

Step 1: Upload an ISO

In the Proxmox web UI, click your node in the left sidebar.
Click local (pve) storage → ISO Images → Upload.
Upload the Ubuntu Server 24.04 LTS ISO (download from ubuntu.com if you don't have it).

Alternatively, download directly on the Proxmox host:

cd /var/lib/vz/template/iso/
wget https://releases.ubuntu.com/24.04/ubuntu-24.04-live-server-amd64.iso

Step 2: Create the VM

Click Create VM (top right of the web UI).
General: Give it a name (e.g., ubuntu-server) and a VM ID.
OS: Select the ISO you uploaded. Guest OS type: Linux, version: 6.x - 2.6 Kernel.
System: Leave defaults. Check Qemu Agent if you plan to install it (recommended).
Disks: Set disk size (32GB minimum for Ubuntu, I usually do 50GB). Use VirtIO Block for best performance. Enable Discard if using SSD storage.
CPU: Allocate cores (2 is fine for testing, 4 for heavier workloads). Set type to host for best performance.
Memory: Allocate RAM in MiB (2048 = 2GB minimum, 4096 = 4GB recommended).
Network: Leave default bridge (vmbr0), model VirtIO (paravirtualized).
Confirm and check Start after created.

Step 3: Install the OS

Click on your new VM → Console. You'll see the Ubuntu installer. Go through the standard installation — select language, configure networking (DHCP is fine for now), create a user, install OpenSSH server when prompted.

Once installed, you can SSH into the VM from your main computer:

ssh your-user@<VM_IP_ADDRESS>

Tip: Install the QEMU guest agent inside the VM for better integration (graceful shutdown, IP reporting, etc.):

bash sudo apt install qemu-guest-agent -y sudo systemctl enable qemu-guest-agent --now

Creating LXC Containers — Lightweight Alternative to VMs

LXC containers share the host kernel, which makes them use far less RAM and CPU than full VMs. They start in seconds instead of minutes. For services like web servers, databases, DNS, or monitoring tools, containers are the better choice.

Download a Container Template

Click local (pve) storage → CT Templates → Templates.
Search for "ubuntu" or "debian" and download the template you want.

Or via CLI:

pveam update
pveam available --section system | grep ubuntu
pveam download local ubuntu-24.04-standard_24.04-2_amd64.tar.zst

Create the Container

Click Create CT (top right).
General: Set hostname (e.g., docker-host), set a root password.
Template: Select the template you downloaded.
Disks: 8-20GB depending on use case.
CPU: 1-2 cores.
Memory: 512MB-2048MB depending on what you're running.
Network: Bridge vmbr0, DHCP or static IP.
DNS: Use host settings or set custom.
Confirm and start.

The container boots in under 5 seconds. Access it via the console or SSH.

Running Docker Inside LXC

This is a common home lab pattern — run Docker inside an LXC container to keep things isolated without the overhead of a full VM. I use this setup for many of my services.

You need to enable nesting and a few features on the container. In the Proxmox web UI: select the container → Options → Features → enable Nesting and keyctl.

Or edit the container config directly:

# On the Proxmox host
vim /etc/pve/lxc/<CT_ID>.conf

Add or modify:

features: nesting=1,keyctl=1

Then inside the container, install Docker:

apt update && apt install -y curl
curl -fsSL https://get.docker.com | sh

Docker inside LXC works well for most use cases. For more on securing your Docker setup, see my Docker security best practices.

Networking in Proxmox

Default Bridge (vmbr0)

Out of the box, Proxmox creates a Linux bridge called vmbr0 that connects to your physical NIC. All VMs and containers attached to this bridge get IPs on your LAN — they're visible to other devices on your network.

This is the simplest setup and works for most home labs.

Creating an Internal Network

For isolated lab environments (like a pentesting lab), create a bridge without a physical interface:

Go to your Node → Network → Create → Linux Bridge.
Name it vmbr1.
Leave Bridge ports empty (no physical NIC).
Assign a subnet: 10.10.10.1/24 as the bridge IP.

VMs connected to vmbr1 can talk to each other but not to your LAN or the internet — perfect for vulnerable machine labs.

To give them internet access through the Proxmox host (NAT), run on the host:

# Enable IP forwarding
echo 'net.ipv4.ip_forward=1' >> /etc/sysctl.conf
sysctl -p

# Add NAT rule
iptables -t nat -A POSTROUTING -s 10.10.10.0/24 -o vmbr0 -j MASQUERADE

To make the iptables rule persistent:

apt install iptables-persistent -y
netfilter-persistent save

If you've set up WireGuard before (I covered it in my WireGuard VPN guide), the networking concepts here — bridges, NAT, forwarding — are the same principles.

Storage Configuration

Understanding Proxmox Storage Types

Proxmox supports multiple storage backends:

Storage Type	Best For	Supports Snapshots	Notes
Local (dir)	ISOs, backups, container templates	No	Default, always available
LVM	VM disks	No (use LVM-Thin instead)	Created during install
LVM-Thin	VM disks, efficient snapshots	Yes	Recommended for VM storage
ZFS	Everything, data integrity	Yes	Needs more RAM (1GB per TB of storage)
NFS/CIFS	Shared storage, backups	Depends on backend	For NAS integration

For a single-disk home lab, the default LVM-Thin partition created during installation is fine. If you add a second drive later, I recommend ZFS mirror for redundancy:

# Create a ZFS mirror from two drives
zpool create tank mirror /dev/sdb /dev/sdc

# Add it to Proxmox
pvesm add zfspool tank-pool --pool tank --content images,rootdir

Backups — Don't Skip This

The number one advantage of running a home lab on Proxmox is the ability to snapshot and back up everything. Use it.

Manual Backup

In the web UI: select a VM or container → Backup → Backup now. Choose: - Storage: Where to store the backup (local or NFS) - Mode: Snapshot (no downtime), Suspend, or Stop - Compression: ZSTD (best ratio/speed balance)

Scheduled Backups

Go to Datacenter → Backup → Add.
Set the schedule (e.g., daily at 2:00 AM).
Select which VMs/containers to include.
Set retention (e.g., keep last 3 backups).

# Check existing backup jobs via CLI
cat /etc/pve/jobs.cfg

Snapshots

Snapshots capture the current state of a VM or container. They're instant and stored on the same disk.

# Create a snapshot
qm snapshot <VMID> pre-update --description "Before apt upgrade"

# Roll back to a snapshot
qm rollback <VMID> pre-update

Use snapshots before risky changes — kernel upgrades, config rewrites, experimental software installs. If something breaks, roll back in seconds.

Warning: Snapshots are not backups. They live on the same disk as the VM. If the disk fails, snapshots are gone too. Use both: snapshots for quick rollback, backups for disaster recovery.

Security Considerations

Your Proxmox host is the single most important machine in your home lab. If it's compromised, every VM and container on it is compromised. Treat it accordingly:

Change the default web UI port from 8006 if exposing to the internet (though you shouldn't expose it).
Create a non-root user for daily management. Go to Datacenter → Permissions → Users → Add.
Enable the firewall. Proxmox has a built-in firewall configurable from the web UI. At minimum, restrict management access to your LAN.
Keep Proxmox updated. Run apt update && apt full-upgrade regularly.
Don't expose the web interface to the internet. If you need remote access, use a VPN (like WireGuard) to connect to your home network first.
Use strong passwords and consider two-factor authentication. Proxmox supports TOTP 2FA out of the box. Enable it under Datacenter → Permissions → Two Factor.

Troubleshooting

Problem: Web interface unreachable after installation. Cause: Incorrect IP configuration during install, or the machine is on a different subnet than your computer. Fix: Connect a monitor and keyboard directly. Check the IP with ip addr show vmbr0. Verify your computer is on the same subnet. Test with ping 192.168.1.50.

Problem: VM boots but gets no network connectivity. Cause: The VM's network interface isn't connected to the bridge, or DHCP isn't available on the bridged network. Fix: Check that the VM's network device is set to bridge vmbr0. Inside the VM, verify the interface is up with ip link. Try a static IP configuration if DHCP isn't working.

Problem: "No valid subscription" error on apt update. Cause: The enterprise repository is enabled but you don't have a subscription key. Fix: Disable the enterprise repo and enable the no-subscription repo as shown in the post-install section above.

Problem: LXC container can't run Docker. Cause: Nesting and keyctl features aren't enabled on the container. Fix: Enable nesting in the container options: Options → Features → check Nesting and keyctl. Restart the container.

Problem: ZFS is using too much RAM. Cause: ZFS uses RAM for its ARC (Adaptive Replacement Cache) and defaults to claiming up to 50% of system RAM. Fix: Limit the ARC size. Add to /etc/modprobe.d/zfs.conf: options zfs zfs_arc_max=2147483648 (2GB limit). Run update-initramfs -u and reboot.

Conclusion

A Proxmox home lab is the best investment you can make in your technical skills. It costs less than a month of cloud hosting, runs on hardware you probably already have, and gives you a safe environment to learn virtualization, networking, containers, and security — all on real infrastructure, not simulators.

Start with a single machine, create a few VMs and containers, and experiment. Break things on purpose. That's what a lab is for. When you're ready to run production services, the skills transfer directly to cloud VPS management.

For next steps, harden your Proxmox host using my Linux hardening guide, run Docker inside an LXC container following my Docker security guide, and set up WireGuard for remote access using my VPN setup tutorial.

Your lab. Your rules. No monthly bill.

Hetzner Review 2026: My Honest Experience

byteguard — Tue, 23 Jun 2026 18:20:53 +0000

Originally published on byte-guard.net.

I've been running the entire ByteGuard stack on a Hetzner CPX22 in Helsinki for months. Ghost blog, Nginx Proxy Manager, Uptime Kuma, Vaultwarden, WireGuard — all on a single VPS. This isn't a spec-sheet comparison or a regurgitation of their marketing page. This is a Hetzner review based on actual daily use, real benchmarks, and real support interactions.

If you're shopping for a VPS for self-hosting, development, or a small production workload, here's what you need to know about Hetzner Cloud in 2026.

What I'm Running

My setup for context:

Plan: CPX22 (3 vCPU AMD, 4GB RAM, 80GB NVMe SSD)
Location: Helsinki, Finland (eu-central)
OS: Ubuntu 24.04 LTS
Workload: 6 Docker containers (Ghost, NPM, Uptime Kuma, Vaultwarden, WireGuard, plus occasional tools)
Monthly cost: €5.39/month (billed hourly)

I chose Hetzner over DigitalOcean, Vultr, and Contabo. I documented the full comparison in my VPS comparison post, and walked through the initial setup in my building ByteGuard guide.

Performance Benchmarks

These are real numbers from my CPX22, not theoretical maximums.

Disk I/O

fio --name=write --ioengine=libaio --rw=write --bs=1M --size=1G --numjobs=1 --runtime=10 --group_reporting
fio --name=read --ioengine=libaio --rw=read --bs=1M --size=1G --numjobs=1 --runtime=10 --group_reporting

Metric	Result
Sequential write	1.1 GB/s
Sequential read	788 MB/s
Random 4K write (IOPS)	~45,000
Random 4K read (IOPS)	~52,000

These are NVMe numbers. For comparison, my Contabo VPS with "SSD" storage gets 1.0 GB/s write and 1.1 GB/s read — but the random IOPS tell the real story. Hetzner's NVMe consistently outperforms in real workloads where random I/O matters (databases, Docker overlay storage).

CPU Performance

openssl speed -evp aes-256-gcm

Metric	Result
AES-256-GCM throughput	~10.24 GB/s
CPU model	AMD EPYC (Genoa)

The EPYC Genoa processors Hetzner uses are current-gen server CPUs. The AES-NI performance is excellent — relevant for VPN, SSL termination, and encrypted storage. For comparison, Contabo's older EPYC processors hit about 3.05 GB/s on the same test.

Network

speedtest-cli --simple

Metric	Result
Download	~920 Mbps
Upload	~890 Mbps
Ping to Frankfurt	~12ms
Ping to New York	~110ms

Hetzner includes 20TB of outbound traffic per month on the CPX22. For a blog and a handful of services, I've never come close to using even 1% of that. Inbound traffic is unlimited and free.

Pricing Breakdown

Hetzner Cloud pricing as of 2026:

Plan	vCPU	RAM	SSD	Traffic	Price
CX22	2 (Intel)	4GB	40GB	20TB	€3.99/mo
CPX22	3 (AMD)	4GB	80GB	20TB	€5.39/mo
CPX32	4 (AMD)	8GB	160GB	20TB	€8.49/mo
CPX42	8 (AMD)	16GB	240GB	20TB	€15.99/mo

The CPX (AMD) line offers better performance per euro than the CX (Intel) line. The AMD EPYC processors consistently benchmark higher, and you get more SSD storage at the same price point.

Hidden costs? Almost none. Snapshots are €0.012/GB/month. Floating IPs are €0.50/month. Load balancers start at €5.39/month. But for a self-hosting setup, the base VPS price is likely all you'll pay.

Billing: Hourly, capped at the monthly price. Spin up a server, test for 3 hours, destroy it, pay cents. This is great for experimentation.

Dashboard and UX

The Hetzner Cloud Console is minimal but functional. It's not as polished as DigitalOcean's, but it has everything you need:

Server management — start, stop, reboot, resize, rebuild
Networking — private networks, floating IPs, firewall rules
Snapshots — create, restore, schedule
Graphs — CPU, disk I/O, network (basic but useful)
Console — web-based VNC console for emergency access (saved me once when I locked myself out of SSH)

What I appreciate:

Fast provisioning. A new server is ready in under 30 seconds.
Firewall rules in the cloud console. These apply at the network level, before traffic reaches your VPS. Combined with UFW on the server, it's defense in depth.
API and CLI. The hcloud CLI tool handles everything the dashboard does. Useful for scripting and automation.

What I wish was better:

No managed databases. DigitalOcean and Vultr offer managed PostgreSQL/MySQL. Hetzner doesn't. For self-hosters this doesn't matter (you run your own), but it's a gap in the product line.
Monitoring is basic. The built-in graphs show CPU, disk, and network at a high level. No alerting, no custom metrics. I use Uptime Kuma instead.
Two-factor auth is SMS-only. In 2026, not offering TOTP for account security is a miss. Use a strong, unique password and watch your account email.

Support Experience

I've contacted Hetzner support twice:

Network routing issue (Helsinki DC) — submitted ticket at 2am, got a human response in 4 hours, issue resolved in 6. Not instant, but competent and professional.
Billing question about snapshot costs — responded within 2 hours with a clear breakdown.

Support is ticket-based only. No live chat, no phone. For the price point, this is expected. The responses are technical and direct — no "have you tried restarting?" tier-1 scripts.

The community forum is also active and helpful for non-urgent questions.

Pros

Price-to-performance ratio is unbeatable. The CPX22 at €5.39/month with AMD EPYC, NVMe storage, and 20TB traffic competes with providers charging 2-3x more.
Honest resource allocation. No "burstable" CPU nonsense. What you see is what you get. The 3 vCPUs on my CPX22 are consistently available.
European data centers with GDPR compliance. Helsinki, Falkenstein, Nuremberg, Ashburn (US). All EU data centers are GDPR-compliant, which matters if you host anything with user data.
20TB traffic included. Most self-hosters will never hit this. DigitalOcean includes less and charges for overages.
Hourly billing. Spin up, test, destroy. No commitment.

Cons

Limited US presence. Only Ashburn (Virginia). If your audience is primarily US West Coast or Asia-Pacific, latency will be noticeable. Consider Vultr or DigitalOcean for those regions.
No managed services. No managed databases, no managed Kubernetes (they have basic k8s but it's not fully managed), no app platform. You manage everything yourself.
SMS-only 2FA. A genuine security concern for your hosting account. Mitigate with a strong password and monitoring for unauthorized access.
Support is slow for urgent issues. If your production server is down at 3am, a 4-hour response time feels long. Enterprise users should look elsewhere.
Community/ecosystem is smaller than DigitalOcean. Fewer one-click apps, fewer tutorials, fewer integrations. This matters less if you're comfortable with manual setup.

Who Should Use Hetzner

Self-hosters running Docker stacks on a budget. This is Hetzner's sweet spot.
Developers who need cheap, powerful VMs for testing and side projects.
Small businesses in Europe who need GDPR-compliant hosting.
Anyone who wants the most compute per dollar and is comfortable managing their own server.

Who Should Skip Hetzner

Beginners who want managed services, one-click deploys, and hand-holding. DigitalOcean's App Platform is better for that.
US-focused products needing low-latency West Coast or Asia presence.
Enterprise teams needing guaranteed SLAs, phone support, and managed infrastructure. Look at AWS, GCP, or a managed provider.

Troubleshooting

Problem: Server unreachable after creation. Cause: Cloud firewall blocking SSH or your IP. Fix: Check Hetzner Cloud Console → Firewall Rules. The default firewall blocks everything. Add a rule allowing SSH (port 22/tcp) from your IP.

Problem: Slow disk I/O compared to benchmarks. Cause: Using local SSD storage instead of NVMe, or noisy neighbors. Fix: Verify you're on a CPX (AMD) plan, not CX (Intel). The CPX line uses newer hardware. If performance is consistently below spec, contact support — you might be on degraded hardware.

Problem: Can't connect to web console. Cause: Browser blocking popups or WebSocket connections. Fix: Allow popups from console.hetzner.cloud. Try a different browser. The console uses VNC over WebSocket.

Verdict

Hetzner is my default recommendation for anyone self-hosting on a budget. The CPX22 at €5.39/month punches well above its weight — AMD EPYC, NVMe storage, generous traffic, and honest resource allocation.

It's not perfect. The US presence is limited, managed services are nonexistent, and support is slower than premium providers. But for the self-hosting audience — people who enjoy running their own infrastructure — these trade-offs are acceptable.

I run my entire blog, monitoring, VPN, and password manager on a single Hetzner CPX22. Total monthly cost: €5.39. That's less than a Notion subscription.

My recommendation: Start with a CPX22. If you outgrow it, resize to CPX32 in the dashboard — it takes about 30 seconds and preserves all your data.

Get started with Hetzner Cloud →

For a deeper comparison with Contabo and Vultr, check my VPS comparison post. And if you're setting up a new server from scratch, start with my building ByteGuard guide.

How to Set Up Fail2Ban on Your Server

byteguard — Tue, 23 Jun 2026 18:20:17 +0000

Originally published on byte-guard.net.

TL;DR

Install and configure Fail2Ban to automatically block IPs that brute-force your SSH, Nginx, or other services. Includes custom jails for web services, aggressive repeat-offender banning, Docker integration, and email alert setup.

Every public-facing server is a target. SSH brute-force bots, WordPress login scanners, API credential stuffers — they run 24/7 against every IP on the internet. Your firewall blocks unauthorized ports, but what about the ports you intentionally keep open?

This guide is part of our Self-Hosting Series — step-by-step guides for running your own services on a VPS.

Fail2Ban watches your log files for failed authentication attempts and automatically bans offending IPs. It's the automated bouncer for your server. This Fail2Ban setup guide covers installation, SSH jail configuration, custom jails for web services, Docker integration, and email alerts.

I run Fail2Ban on the same Hetzner VPS that hosts this blog, and it bans hundreds of IPs per week — all without any manual intervention.

What Do You Need to Set Up Fail2Ban?

A Linux VPS running Ubuntu 22.04/24.04 or Debian 12
Root or sudo access
SSH hardened (my SSH hardening guide covers the full setup)
Basic understanding of log files and firewall rules

How Do You Install Fail2Ban on Ubuntu/Debian?

sudo apt update && sudo apt install fail2ban -y

Fail2Ban installs but doesn't configure any jails by default (on modern Ubuntu/Debian). Start and enable the service:

sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Check it's running:

sudo systemctl status fail2ban

How Does Fail2Ban Work?

Before configuring, understand how the pieces fit together:

Jails — define what to monitor and what to do. Each jail watches a specific log file with a specific filter.
Filters — regex patterns that match failed authentication attempts in log files.
Actions — what happens when the threshold is reached (ban IP, send email, etc.).
Ban logic — if an IP triggers maxretry failures within findtime seconds, it's banned for bantime seconds.

Config files: - /etc/fail2ban/jail.conf — defaults. Never edit this — it gets overwritten on updates. - /etc/fail2ban/jail.local — your overrides. This is where all your config goes. - /etc/fail2ban/jail.d/*.conf — additional jail files (also override-safe). - /etc/fail2ban/filter.d/*.conf — filter definitions (regex patterns).

How Do You Configure the Fail2Ban SSH Jail?

Create your local config:

sudo tee /etc/fail2ban/jail.local << 'EOF'
[DEFAULT]
# Ban for 1 hour
bantime = 3600
# Window of time to count failures
findtime = 600
# Max failures before ban
maxretry = 3
# Use UFW for banning (change to iptables if not using UFW)
banaction = ufw
# Ignore your own IP (replace with yours)
ignoreip = 127.0.0.1/8 ::1

[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
bantime = 3600
EOF

If you changed your SSH port (as recommended in my SSH hardening guide), update the port:

[sshd]
enabled = true
port = 2222
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
bantime = 3600

Restart Fail2Ban to apply:

sudo systemctl restart fail2ban

Check the jail status:

sudo fail2ban-client status sshd

Expected output:

Status for the jail: sshd
|- Filter
|  |- Currently failed: 2
|  |- Total failed:     47
|  `- File list:        /var/log/auth.log
`- Actions
   |- Currently banned: 1
   |- Total banned:     12
   `- Banned IP list:   203.0.113.42

How Do You Set Up Aggressive Banning for Repeat Offenders?

The default 1-hour ban is fine for casual bots. But some IPs come back repeatedly. Add a recidive jail that escalates bans:

sudo tee -a /etc/fail2ban/jail.local << 'EOF'

[recidive]
enabled = true
filter = recidive
logpath = /var/log/fail2ban.log
bantime = 604800    # 1 week
findtime = 86400    # 24 hours
maxretry = 3        # 3 bans in 24 hours = 1 week ban
banaction = ufw
EOF

This watches Fail2Ban's own log. If an IP gets banned 3 times in 24 hours, it gets a 1-week ban. Persistent attackers get escalating consequences.

How Do You Create Custom Fail2Ban Jails for Web Services?

Nginx HTTP Auth

If you protect any web services with HTTP basic auth:

sudo tee -a /etc/fail2ban/jail.local << 'EOF'

[nginx-http-auth]
enabled = true
filter = nginx-http-auth
logpath = /var/log/nginx/error.log
maxretry = 3
bantime = 3600
EOF

Nginx Rate Limiting

Create a custom filter for Nginx 429 responses:

sudo tee /etc/fail2ban/filter.d/nginx-limit-req.conf << 'EOF'
[Definition]
failregex = limiting requests, excess:.* by zone.*client: <HOST>
ignoreregex =
EOF

Add the jail:

sudo tee -a /etc/fail2ban/jail.local << 'EOF'

[nginx-limit-req]
enabled = true
filter = nginx-limit-req
logpath = /var/log/nginx/error.log
maxretry = 5
bantime = 600
EOF

Create a custom filter that watches for repeated 401/403 responses:

sudo tee /etc/fail2ban/filter.d/ghost-login.conf << 'EOF'
[Definition]
failregex = ^<HOST> .* "POST /ghost/api/.*/session" (401|403)
ignoreregex =
EOF

Add the jail (adjust the log path to your Nginx access log):

sudo tee -a /etc/fail2ban/jail.local << 'EOF'

[ghost-login]
enabled = true
filter = ghost-login
logpath = /var/log/nginx/access.log
maxretry = 5
bantime = 1800
EOF

How Do You Use Fail2Ban with Docker Services?

Docker containers log to Docker's logging driver, not system log files. If your web server runs in Docker, you need to either:

Option A: Mount logs from the container to the host and point Fail2Ban at them.

services:
  nginx:
    image: nginx:latest
    volumes:
      - /var/log/nginx:/var/log/nginx

Option B: Use Docker's JSON log files directly:

# Find the container's log file
docker inspect --format='{{.LogPath}}' nginx
# Output: /var/lib/docker/containers/<id>/<id>-json.log

Point Fail2Ban at this file. You'll need a custom filter that handles Docker's JSON log format:

sudo tee /etc/fail2ban/filter.d/docker-nginx.conf << 'EOF'
[Definition]
failregex = .*"log":"<HOST> .* (401|403).*
ignoreregex =
EOF

Option A is simpler and more reliable. I recommend mounting log volumes from your containers.

How Do You Set Up Fail2Ban Email Notifications?

Get notified when Fail2Ban bans someone:

sudo apt install mailutils -y

Update your jail.local [DEFAULT] section:

[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 3
banaction = ufw
ignoreip = 127.0.0.1/8 ::1

# Email notifications
destemail = you@yourdomain.com
sender = fail2ban@yourdomain.com
mta = mail
action = %(action_mwl)s

The action_mwl action bans the IP and sends an email with the whois info and relevant log lines. It's the most informative option.

Note: Email requires a working MTA (mail transfer agent) on your server. If you don't have one configured, use sendmail or integrate with an external SMTP service. For my setup, I use Brevo's SMTP relay.

What Are the Most Useful Fail2Ban Commands?

# Check overall status
sudo fail2ban-client status

# Check a specific jail
sudo fail2ban-client status sshd

# Manually ban an IP
sudo fail2ban-client set sshd banip 203.0.113.42

# Manually unban an IP
sudo fail2ban-client set sshd unbanip 203.0.113.42

# Check which IPs are banned
sudo fail2ban-client get sshd banned

# Test a filter against a log file (dry run)
sudo fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf

# Reload config without restarting
sudo fail2ban-client reload

The fail2ban-regex command is invaluable when creating custom filters. Test your regex against the actual log file before enabling the jail.

What Are the Key Fail2Ban Security Considerations?

Don't ban yourself. Always add your own IP (or IP range) to ignoreip. If you get locked out, you'll need console access from your hosting provider to fix it.
Ban duration trade-offs. Short bans (10 minutes) reduce bot noise but don't deter determined attackers. Long bans (1 week) are more effective but risk banning legitimate users behind shared IPs (NAT, corporate networks). The recidive jail offers a good middle ground.
Log rotation. Fail2Ban follows log files. If your log rotation setup creates new files (instead of truncating), Fail2Ban might lose track. Verify with fail2ban-client status <jail> that the file list is correct after rotation.
Resource usage. Fail2Ban uses regex on log files, which can be CPU-intensive on busy servers with verbose logs. Keep your filter regexes efficient and avoid overly broad patterns.
Fail2Ban as a complement, not a replacement. Fail2Ban is reactive — it bans after failed attempts. Combine it with proactive measures: SSH key-based auth, strong passwords, and Docker security practices.

How Do You Troubleshoot Fail2Ban Configuration Issues?

Problem: Fail2Ban service won't start. Cause: Syntax error in jail.local. Fix: Check the logs: sudo journalctl -u fail2ban -n 50. Common issues: missing enabled = true, wrong log path, or invalid regex in custom filters.

Problem: IPs aren't getting banned despite failed attempts. Cause: Wrong log path, wrong filter, or the log format doesn't match the filter regex. Fix: Run sudo fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf to test. If matches are 0, the filter doesn't match your log format.

Problem: Banned myself. Cause: Too many failed SSH attempts from your IP, or ignoreip not configured. Fix: Access via your hosting provider's console. Run sudo fail2ban-client set sshd unbanip YOUR_IP. Add your IP to ignoreip in jail.local.

Problem: Bans don't persist after Fail2Ban restart. Cause: Fail2Ban clears its ban list on restart by default. Fix: Set bantime = -1 for permanent bans (use with caution), or use the dbpurgeage setting in jail.local to control how long ban records are kept.

Problem: UFW ban action fails. Cause: UFW isn't installed or the banaction is misconfigured. Fix: Verify sudo ufw status shows UFW is active. If you're not using UFW, change banaction to iptables-multiport.

What Is the Result of a Properly Configured Fail2Ban Setup?

Fail2Ban is one of those tools that runs quietly in the background and makes a measurable difference. On my server, it bans 200+ IPs per week — that's 200+ fewer bots hammering my SSH port and web services.

The setup takes 15 minutes. The SSH jail alone is worth it. Add the recidive jail and custom web service jails as your stack grows.

For the complete server security picture, pair Fail2Ban with:

SSH hardening — disable password auth, key-based only
VPS hardening basics — firewall, updates, user setup
Docker security practices — if your services run in containers

If you need a VPS, I use Hetzner for everything — affordable and reliable.

How to Check Your Website's Security Headers

byteguard — Tue, 23 Jun 2026 18:19:39 +0000

Originally published on byte-guard.net.

Every HTTP response your server sends includes headers that browsers use to decide how to handle your content. Get them wrong -- or leave them out entirely -- and you are handing attackers an open invitation. Clickjacking, cross-site scripting, MIME-type sniffing, protocol downgrade attacks: security headers are the first line of defense against all of these.

This guide is part of our Security Tools Series — hands-on guides for the tools every security-minded developer needs.

The problem is that most default server configurations ship with almost none of these headers set. I have audited dozens of self-hosted services, and the majority score an F on security header scanners. The good news: fixing this takes about fifteen minutes once you understand what each header does.

By the end of this post, you will know how to check security headers on any website, understand what each critical header does, and configure all of them in Nginx, Apache, and Caddy.

Prerequisites

A live website or web application you control
SSH access to your server (if you plan to add headers)
One of: Nginx, Apache, or Caddy as your web server or reverse proxy
Basic familiarity with your server's configuration files

If you are starting from scratch, my guide on setting up a VPS from scratch covers the initial server setup.

How to Check Security Headers on Any Website

Using Online Scanners

The fastest way to check security headers is with a dedicated scanner. Here are the tools I actually use:

securityheaders.com -- Gives you a letter grade (A+ to F) and lists every missing header. Free, instant results.
Mozilla Observatory (observatory.mozilla.org) -- More comprehensive. Checks headers, TLS, and other best practices. Scores out of 100.
tools.byte-guard.net -- Our own header checker tool gives you a clean breakdown of what is present, what is missing, and exact configuration snippets to fix each issue.

Using curl from the Command Line

For a quick check without leaving your terminal:

curl -I https://your-domain.com

The -I flag fetches only the headers. You will see something like:

HTTP/2 200
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN

If you do not see headers like Strict-Transport-Security, Content-Security-Policy, or X-Content-Type-Options in that output, your site is missing critical protections.

Using Browser Developer Tools

Open your browser's developer tools (F12), go to the Network tab, reload the page, click on the main document request, and check the Response Headers section. This is useful when you need to verify headers on pages that require authentication.

The Six Security Headers That Matter Most

Let me walk through each header, what it protects against, and how to configure it across all three major web servers.

Strict-Transport-Security (HSTS)

What it does: Tells browsers to only connect to your site over HTTPS. Once a browser sees this header, it will refuse to load your site over plain HTTP for the specified duration -- even if the user types http://.

What it prevents: Protocol downgrade attacks, SSL stripping, cookie hijacking over unencrypted connections.

Nginx:

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

Apache:

Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

Caddy:

header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

Note: The preload directive submits your domain to browser preload lists (hstspreload.org). Only add it if you are certain every subdomain supports HTTPS. Removing a domain from the preload list takes months.

The max-age=31536000 value is one year in seconds. Start with a shorter value like 86400 (one day) while testing, then increase it once you have confirmed everything works.

Content-Security-Policy (CSP)

Content-Security-Policy is the most powerful -- and most complex -- security header. It tells the browser exactly which sources are allowed to load scripts, styles, images, fonts, and other resources on your page.

What it prevents: Cross-site scripting (XSS), data injection, clickjacking (partially), and unauthorized resource loading.

A restrictive CSP looks like this:

Nginx:

add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'" always;

Apache:

Header always set Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"

Caddy:

header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"

Breaking down the directives:

Directive	Controls	Example Value
`default-src`	Fallback for all resource types	`'self'`
`script-src`	JavaScript sources	`'self' https://cdn.example.com`
`style-src`	CSS sources	`'self' 'unsafe-inline'`
`img-src`	Image sources	`'self' data: https:`
`font-src`	Font file sources	`'self' https://fonts.gstatic.com`
`frame-ancestors`	Who can embed your page	`'none'`
`form-action`	Where forms can submit	`'self'`

Warning: A misconfigured CSP will break your site. Start with Content-Security-Policy-Report-Only to log violations without blocking anything. Check the browser console for blocked resources, adjust your policy, then switch to the enforcing header.

If you run Docker containers behind a reverse proxy (as I covered in my Docker security guide), CSP is especially important because each container may serve content from different origins.

X-Frame-Options

What it does: Controls whether your site can be embedded in <iframe>, <frame>, or <object> elements on other sites.

What it prevents: Clickjacking attacks, where an attacker overlays your site with invisible frames to trick users into clicking things they did not intend to.

Nginx:

add_header X-Frame-Options "SAMEORIGIN" always;

Apache:

Header always set X-Frame-Options "SAMEORIGIN"

Caddy:

header X-Frame-Options "SAMEORIGIN"

The three possible values:

DENY -- No one can frame your page, not even your own site
SAMEORIGIN -- Only pages on the same origin can frame it
ALLOW-FROM https://example.com -- Only the specified origin (deprecated in modern browsers)

For most sites, SAMEORIGIN is the right choice. Use DENY if you have no reason to embed your own pages.

Note: The frame-ancestors directive in CSP is the modern replacement for X-Frame-Options. Set both for backward compatibility.

X-Content-Type-Options

What it does: Prevents browsers from MIME-type sniffing -- guessing the content type of a response instead of trusting the Content-Type header.

What it prevents: Drive-by downloads, where a browser interprets an uploaded file (say, a .txt that contains JavaScript) as executable content.

Nginx:

add_header X-Content-Type-Options "nosniff" always;

Apache:

Header always set X-Content-Type-Options "nosniff"

Caddy:

header X-Content-Type-Options "nosniff"

This one is simple: the only valid value is nosniff. There is no reason not to set it on every site.

Referrer-Policy

What it does: Controls how much referrer information is sent when users navigate away from your site.

Why it matters: Without this header, the full URL (including query parameters that may contain tokens, session IDs, or other sensitive data) gets sent to external sites.

Nginx:

add_header Referrer-Policy "strict-origin-when-cross-origin" always;

Apache:

Header always set Referrer-Policy "strict-origin-when-cross-origin"

Caddy:

header Referrer-Policy "strict-origin-when-cross-origin"

The most common values:

Value	Behavior
`no-referrer`	Never send referrer info
`same-origin`	Only send referrer for same-origin requests
`strict-origin-when-cross-origin`	Send full URL for same-origin, only origin for cross-origin, nothing for HTTPS-to-HTTP
`no-referrer-when-downgrade`	Browser default -- send everything except on HTTPS-to-HTTP

I recommend strict-origin-when-cross-origin for most sites. It preserves analytics functionality while protecting sensitive URL paths.

Permissions-Policy

What it does: Controls which browser features and APIs your site can use -- camera, microphone, geolocation, payment, and more.

What it prevents: Malicious scripts or embedded content from accessing device features without your knowledge.

Nginx:

add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()" always;

Apache:

Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()"

Caddy:

header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()"

The () value means the feature is disabled entirely. If your site needs camera access (for a video chat feature, for example), you would use camera=(self) to allow it only from your own origin.

Putting It All Together: Complete Configuration

Here is a complete configuration block for each web server with all six headers. If you are choosing a reverse proxy, I compared Nginx Proxy Manager, Traefik, and Caddy in a separate post.

Complete Nginx Configuration

# /etc/nginx/snippets/security-headers.conf
# Include this in your server blocks: include /etc/nginx/snippets/security-headers.conf;

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()" always;

Then in each server block:

server {
    listen 443 ssl http2;
    server_name <YOUR_DOMAIN>;

    include /etc/nginx/snippets/security-headers.conf;

    # ... rest of your config
}

Complete Apache Configuration

# /etc/apache2/conf-available/security-headers.conf
# Enable with: a2enconf security-headers && systemctl reload apache2

<IfModule mod_headers.c>
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    Header always set Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set Referrer-Policy "strict-origin-when-cross-origin"
    Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()"
</IfModule>

Note: Apache requires mod_headers to be enabled. Run a2enmod headers && systemctl restart apache2 if it is not already active.

Complete Caddy Configuration

<YOUR_DOMAIN> {
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
        X-Frame-Options "SAMEORIGIN"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()"
    }

    reverse_proxy localhost:8080
}

Caddy's configuration is the most concise. It also handles HTTPS automatically, which means HSTS is already partially covered -- but you should still set the header explicitly for preloading.

Security Considerations

Order matters with reverse proxies. If you are running Nginx Proxy Manager in front of an application that also sets security headers, the proxy's headers may override or duplicate the application's headers. Always check the final response with curl -I to verify what the browser actually receives.

CSP can break third-party integrations. If you use analytics (Plausible, Umami), comment systems (Giscus, Disqus), or embed YouTube videos, you need to whitelist those domains in the relevant CSP directives. Do not disable CSP because one widget broke -- add the specific source.

HSTS preloading is a commitment. Once your domain is on the preload list, browsers will refuse HTTP connections to any subdomain. If you have internal services running on HTTP behind a VPN, preloading will cause problems. Consider whether includeSubDomains is appropriate for your setup.

If you have followed my VPS hardening guide, security headers are the natural next step -- your server is locked down at the OS level, and now you are locking down the application layer.

Troubleshooting

Problem: Headers are not showing up in curl -I output after adding them. Cause: Configuration file not loaded, or syntax error preventing reload. Fix: Check for errors with nginx -t (Nginx), apachectl configtest (Apache), or caddy validate (Caddy). Then reload the service. Do not restart -- reload is sufficient and avoids downtime.

Problem: Site breaks after adding Content-Security-Policy. Cause: The CSP is blocking legitimate resources (scripts, styles, fonts) that your site needs. Fix: Open browser developer tools, check the Console tab for CSP violation messages. Each message tells you exactly which resource was blocked and which directive blocked it. Add the source to the appropriate directive.

Problem: Security header scanner still shows a low grade after adding all headers. Cause: Your application or CDN is overriding headers set by the web server, or the scanner is checking a different URL than where you added the headers. Fix: Verify with curl -I https://your-exact-url.com that the headers appear in the raw response. If using a CDN like Cloudflare, check their dashboard -- some CDNs strip or modify security headers.

Problem: X-Frame-Options set to DENY but you need to embed your own pages. Cause: DENY blocks all framing, including same-origin. Fix: Switch to SAMEORIGIN and set frame-ancestors 'self' in your CSP.

Problem: HSTS causing issues on development/staging environments. Cause: Browser cached the HSTS policy from a previous visit and now refuses HTTP. Fix: In Chrome, go to chrome://net-internals/#hsts, enter your domain under "Delete domain security policies", and click Delete. In Firefox, clear your browsing history for that domain. Never set HSTS headers on non-production environments.

Conclusion

Setting up security headers is one of the highest-impact, lowest-effort security improvements you can make. Six headers, a few lines of configuration, and your site goes from an F to an A+ on security scanners.

The key takeaway: start with everything except CSP, verify with curl -I, then build your CSP gradually using Content-Security-Policy-Report-Only before switching to enforcement.

If you are running self-hosted services behind a reverse proxy, check out my comparison of Nginx Proxy Manager, Traefik, and Caddy to pick the right proxy for your setup. And if your server itself is not hardened yet, start with my VPS hardening guide before worrying about HTTP headers.

Need a reliable VPS to host your projects? I run all of ByteGuard on Hetzner -- solid performance, fair pricing, and European data centers. Check out Hetzner's cloud plans.

Advanced Docker Container Security Guide

byteguard — Tue, 23 Jun 2026 18:19:02 +0000

Originally published on byte-guard.net.

If you followed my earlier post on Docker security best practices, you already know the fundamentals: non-root users, read-only filesystems, dropped capabilities. Those practices eliminate the low-hanging fruit. But containers run in production, face real attackers, and the basics are table stakes, not a finish line. Advanced Docker container security requires tools and techniques that go deeper — kernel-level restrictions, image provenance verification, runtime anomaly detection, and automated vulnerability scanning baked into your pipeline.

This guide covers the next layer. By the end, you will have seccomp profiles restricting system calls, AppArmor policies limiting file access, Trivy scanning your images for CVEs, Falco watching for suspicious runtime behavior, and Docker Content Trust verifying image signatures. These are the techniques that separate a hobbyist Docker setup from a hardened production deployment.

Prerequisites

A Linux server running Docker Engine 24+ (Ubuntu 22.04 or Debian 12 recommended)
Docker Compose v2 installed
Basic familiarity with Docker (images, containers, volumes, networking)
Completion of the fundamentals from my Docker security best practices guide
A VPS or home lab — if you need one, my VPS setup guide covers the infrastructure

Seccomp Profiles — Restricting System Calls

Seccomp (Secure Computing Mode) filters which Linux system calls a container can make. Docker ships with a default seccomp profile that blocks around 44 of the 300+ available syscalls — things like reboot, mount, and clock_settime. But the default profile is permissive by design. A custom profile lets you whitelist only the syscalls your application actually needs.

Why This Matters

If an attacker gains code execution inside a container, their first move is often to escape to the host. Most container escape techniques rely on specific syscalls — ptrace, unshare, mount. A tight seccomp profile makes these escapes impossible even if the container runtime has a zero-day.

Creating a Custom Seccomp Profile

Start by examining what syscalls your application uses. Run your container with the default profile and audit:

docker run --rm --security-opt seccomp=unconfined \
  strace -cf -S calls your-image your-command 2>&1 | tail -20

This gives you a frequency count of every syscall your process makes. Build your allowlist from this output.

Here is a minimal seccomp profile for a typical Node.js web application:

{
  "defaultAction": "SCMP_ACT_ERRNO",
  "architectures": ["SCMP_ARCH_X86_64"],
  "syscalls": [
    {
      "names": [
        "accept", "accept4", "access", "arch_prctl", "bind", "brk",
        "capget", "capset", "chdir", "clock_getres", "clock_gettime",
        "clone", "close", "connect", "dup", "dup2", "dup3",
        "epoll_create1", "epoll_ctl", "epoll_wait", "eventfd2",
        "execve", "exit", "exit_group", "faccessat", "fchmod",
        "fchown", "fcntl", "fstat", "fstatfs", "futex",
        "getcwd", "getdents64", "getegid", "geteuid", "getgid",
        "getpeername", "getpid", "getppid", "getrandom", "getsockname",
        "getsockopt", "getuid", "ioctl", "listen", "lseek",
        "madvise", "memfd_create", "mmap", "mprotect", "mremap",
        "munmap", "newfstatat", "openat", "pipe2", "poll",
        "prctl", "pread64", "prlimit64", "read", "readlink",
        "recvfrom", "recvmsg", "rename", "rt_sigaction",
        "rt_sigprocmask", "rt_sigreturn", "sched_getaffinity",
        "sched_yield", "sendmsg", "sendto", "set_robust_list",
        "set_tid_address", "setgid", "setgroups", "setsockopt",
        "setuid", "shutdown", "sigaltstack", "socket", "statfs",
        "sysinfo", "tgkill", "umask", "uname", "unlink",
        "wait4", "write", "writev"
      ],
      "action": "SCMP_ACT_ALLOW"
    }
  ]
}

Save this as seccomp-nodejs.json and apply it:

docker run --rm \
  --security-opt seccomp=seccomp-nodejs.json \
  your-node-app

In Docker Compose:

services:
  web:
    image: your-node-app
    security_opt:
      - seccomp=./seccomp-nodejs.json

Note: Start with the default Docker profile and remove syscalls rather than building from scratch. The default profile is at /etc/docker/seccomp/default.json on most installations, or you can export it from the Moby repository on GitHub.

Testing Your Profile

Run your application's full test suite with the profile applied. If a syscall is blocked, you will see EPERM (Operation not permitted) errors in your application logs. Add the missing syscall to your allowlist and retest.

AppArmor Policies — Restricting File and Network Access

While seccomp controls what syscalls a process can make, AppArmor controls what resources it can access — files, directories, network operations, capabilities. They complement each other: seccomp is the verb filter, AppArmor is the noun filter.

Creating a Custom AppArmor Profile

Here is an AppArmor profile for a container running a Python web API that should only read from /app and write to /tmp:

cat > /etc/apparmor.d/docker-python-api << 'PROFILE'
#include <tunables/global>

profile docker-python-api flags=(attach_disconnected,mediate_deleted) {
  #include <abstractions/base>
  #include <abstractions/python>

  # Allow reading application code
  /app/** r,

  # Allow writing to tmp only
  /tmp/** rw,

  # Allow network access (TCP)
  network inet tcp,
  network inet6 tcp,

  # Deny everything else by default
  deny /etc/shadow r,
  deny /etc/passwd w,
  deny /proc/*/mem rw,
  deny /sys/** w,
}
PROFILE

Load the profile:

sudo apparmor_parser -r /etc/apparmor.d/docker-python-api

Apply it to your container:

docker run --rm \
  --security-opt apparmor=docker-python-api \
  your-python-api

Verifying AppArmor Is Active

Check the status of loaded profiles:

sudo aa-status | grep docker

You should see your profile listed under "enforced." If it appears under "complain," the profile logs violations but does not block them — useful for testing but not for production.

Docker Content Trust — Image Signing and Verification

How do you know the image you pulled is the one the author published? Docker Content Trust (DCT) uses digital signatures to verify image integrity and publisher identity. Without it, you trust the registry implicitly — and registries have been compromised before.

Enabling Docker Content Trust

export DOCKER_CONTENT_TRUST=1

With this set, docker pull and docker push will enforce signature verification. Unsigned images will be rejected.

For permanent enforcement, add this to /etc/environment or your shell profile:

echo 'DOCKER_CONTENT_TRUST=1' | sudo tee -a /etc/environment

Signing Your Own Images

Generate a signing key:

docker trust key generate <YOUR_NAME>

Add yourself as a signer for a repository:

docker trust signer add --key <YOUR_NAME>.pub <YOUR_NAME> <YOUR_REGISTRY>/<YOUR_REPO>

Sign and push:

docker trust sign <YOUR_REGISTRY>/<YOUR_REPO>:latest

Inspecting Trust Data

docker trust inspect --pretty <YOUR_REGISTRY>/<YOUR_REPO>

This shows who signed the image and when. In a team environment, require multiple signers before an image can be deployed — this prevents a single compromised CI/CD pipeline from pushing malicious images.

Note: Docker Content Trust does not verify the contents of the image are vulnerability-free. It only verifies that the image has not been tampered with since signing. You still need vulnerability scanning, which is covered next.

Vulnerability Scanning with Trivy

Trivy is an open-source scanner from Aqua Security that finds CVEs in OS packages, language-specific dependencies, and misconfigurations inside container images. It is fast, accurate, and integrates into CI/CD pipelines with zero configuration.

Installation

sudo apt install -y wget apt-transport-https gnupg lsb-release
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/trivy.list
sudo apt update && sudo apt install -y trivy

Scanning an Image

trivy image nginx:latest

Sample output:

nginx:latest (debian 12.4)
Total: 85 (UNKNOWN: 0, LOW: 52, MEDIUM: 27, HIGH: 5, CRITICAL: 1)

┌──────────────────┬──────────────────┬──────────┬───────────────────┐
│     Library      │  Vulnerability   │ Severity │  Fixed Version    │
├──────────────────┼──────────────────┼──────────┼───────────────────┤
│ libssl3          │ CVE-2024-XXXXX   │ CRITICAL │ 3.0.13-1~deb12u2  │
│ curl             │ CVE-2024-XXXXX   │ HIGH     │ 7.88.1-10+deb12u6 │
└──────────────────┴──────────────────┴──────────┴───────────────────┘

Failing CI/CD on Critical Vulnerabilities

Add Trivy to your build pipeline with a severity threshold:

trivy image --exit-code 1 --severity CRITICAL,HIGH your-image:latest

Exit code 1 means vulnerabilities were found at the specified severity. Your CI pipeline treats this as a build failure.

Scanning Docker Compose Projects

Scan every image in a Compose file:

for image in $(docker compose config --images); do
  echo "=== Scanning $image ==="
  trivy image --severity HIGH,CRITICAL "$image"
done

Scanning Filesystem and Config Files

Trivy also detects misconfigurations in Dockerfiles and Compose files:

trivy config .

This catches issues like running as root, using latest tags, and missing health checks — problems I covered in the fundamentals post.

Runtime Security with Falco

Everything so far operates at build time or deploy time. Falco is the runtime layer — it watches what containers actually do and alerts on suspicious behavior. Think of it as an intrusion detection system for containers.

Falco monitors Linux system calls in real time using eBPF and triggers alerts when behavior matches predefined rules. Examples: a shell spawning inside a container, a process reading /etc/shadow, an outbound connection to a known malicious IP.

Installation via Docker

Ironically, the best way to run Falco is in a container — with the required privileges:

services:
  falco:
    image: falcosecurity/falco:latest
    container_name: falco
    privileged: true
    volumes:
      - /var/run/docker.sock:/host/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - /dev:/host/dev
      - /etc:/host/etc:ro
      - ./falco-rules:/etc/falco/rules.d:ro
    environment:
      - HOST_ROOT=/host

Note: Yes, Falco requires privileged mode and access to the Docker socket. This is the trade-off — to monitor all containers, the monitoring tool itself needs elevated access. Isolate Falco on a dedicated network and restrict access to its container.

Custom Falco Rules

Create a rules file to detect common attack patterns:

# falco-rules/custom-rules.yaml
- rule: Shell Spawned in Container
  desc: Detect shell process started in a container
  condition: >
    spawned_process and container and
    proc.name in (bash, sh, zsh, dash, ash) and
    not proc.pname in (cron, supervisord, entrypoint.sh)
  output: >
    Shell spawned in container
    (user=%user.name container=%container.name shell=%proc.name
     parent=%proc.pname cmdline=%proc.cmdline)
  priority: WARNING

- rule: Sensitive File Read in Container
  desc: Detect reads of sensitive files
  condition: >
    open_read and container and
    fd.name in (/etc/shadow, /etc/sudoers, /proc/1/environ)
  output: >
    Sensitive file read in container
    (user=%user.name file=%fd.name container=%container.name)
  priority: ERROR

- rule: Outbound Connection to Non-Standard Port
  desc: Detect containers connecting to unusual ports
  condition: >
    outbound and container and
    not fd.sport in (80, 443, 53, 5432, 3306, 6379, 27017)
  output: >
    Unexpected outbound connection
    (container=%container.name connection=%fd.name port=%fd.sport)
  priority: WARNING

Monitoring Falco Alerts

docker logs -f falco

In production, pipe Falco alerts to a SIEM or alerting system. Falco supports output to Slack, PagerDuty, and generic webhooks out of the box.

Docker Socket Protection

The Docker socket (/var/run/docker.sock) is the single most dangerous file on a Docker host. Any process with access to the socket has full control over the Docker daemon — it can create privileged containers, mount the host filesystem, and effectively gain root on the host.

Never Mount the Socket Unless Required

Review your Docker Compose files and remove socket mounts from any container that does not strictly need them:

grep -r "docker.sock" /opt/*/docker-compose.yml

Use a Socket Proxy

If a container needs limited Docker API access (monitoring, auto-updates), use a socket proxy like Tecnativa's docker-socket-proxy:

services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: docker-socket-proxy
    environment:
      - CONTAINERS=1      # Allow listing containers
      - IMAGES=0          # Deny image operations
      - NETWORKS=0        # Deny network operations
      - VOLUMES=0         # Deny volume operations
      - POST=0            # Deny all POST requests (read-only)
      - BUILD=0
      - COMMIT=0
      - EXEC=0            # Deny exec into containers
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - docker-proxy

  watchtower:
    image: containrrr/watchtower
    environment:
      - DOCKER_HOST=tcp://docker-proxy:2375
    depends_on:
      - docker-proxy
    networks:
      - docker-proxy

networks:
  docker-proxy:
    driver: bridge

This gives Watchtower the ability to list containers but prevents it from executing commands, building images, or managing networks. If Watchtower is compromised, the blast radius is minimal.

Multi-Stage Builds for Minimal Attack Surface

The fewer files in your final image, the fewer things an attacker can exploit. Multi-stage builds let you compile your application in a fat builder image, then copy only the binary into a minimal runtime image.

# Stage 1: Build
FROM golang:1.22-bookworm AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server .

# Stage 2: Runtime
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=builder /app/server /server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/server"]

The final image contains only the compiled binary and CA certificates. No shell, no package manager, no curl, no wget. An attacker who gains code execution has almost nothing to work with.

Compare the image sizes:

docker images | grep myapp
# myapp-full     latest   850MB
# myapp-minimal  latest   12MB

A smaller image is faster to pull, cheaper to store, and has a dramatically smaller CVE surface.

Security Headers for Containerized Web Apps

If your containers serve web traffic, verify they return proper security headers. I covered this in detail in my security headers guide, but here is the container-specific angle.

Add headers in your reverse proxy configuration rather than in each application. In Nginx:

add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self'" always;

Security Considerations

Docker container security is not a single tool or configuration — it is a layered approach:

Build time: Multi-stage builds, Trivy scanning, minimal base images
Deploy time: Seccomp profiles, AppArmor policies, Content Trust, dropped capabilities
Runtime: Falco monitoring, socket protection, read-only filesystems, network policies

The biggest risk I see in self-hosted environments is complacency after initial setup. Security is not a checklist you complete once. Schedule weekly Trivy scans, review Falco alerts daily, and update base images monthly at minimum.

When running on a VPS, these container-level protections layer on top of host-level hardening. If you have not secured your host yet, start with my Linux VPS hardening guide — container security means nothing if the host is compromised.

Troubleshooting

Problem: Container crashes with EPERM after applying a seccomp profile. Cause: Your custom seccomp profile is missing a required syscall. Fix: Run the container temporarily with --security-opt seccomp=unconfined and strace to identify the blocked syscall. Add it to your profile and retest.

Problem: Trivy scan shows vulnerabilities in the base image that have no fix available. Cause: The upstream distribution has not released a patch yet. Fix: Switch to a different base image (e.g., Alpine instead of Debian, or distroless). If the CVE does not apply to your use case (e.g., a library vulnerability in a package your app does not use), document the exception.

Problem: Falco generates excessive alerts for normal container behavior. Cause: Default Falco rules are broad and trigger on legitimate operations. Fix: Create exception lists in your custom rules using the not operator. Start Falco in "tap" mode to observe before enforcing.

Problem: Docker Content Trust blocks pulls of images you know are safe. Cause: The image publisher has not signed their images. Fix: Temporarily disable DCT for that pull with DOCKER_CONTENT_TRUST=0 docker pull image:tag, then re-enable it. Long-term, prefer signed images or build your own from a trusted Dockerfile.

Problem: Socket proxy blocks a legitimate API call from a monitoring tool. Cause: The proxy's environment variables are too restrictive for the tool's requirements. Fix: Review the tool's documentation for required Docker API endpoints and enable only those in the proxy configuration. Never set POST=1 unless the tool genuinely needs write access.

Conclusion

The fundamentals from my Docker security best practices post give you a solid foundation. This guide adds the advanced layers: seccomp restricts system calls, AppArmor restricts resource access, Trivy catches vulnerabilities before deployment, Falco detects threats at runtime, and Content Trust ensures image integrity.

No single tool makes containers secure. The strength is in layering — each control catches what the others miss. Start by adding Trivy to your build pipeline (it takes five minutes) and work outward from there.

If you are running these containers on a VPS, I use Hetzner for all my projects. The CPX22 handles a full Docker stack with monitoring comfortably, and you can follow my VPS setup guide to get started.

OWASP Top 10 Explained with Real Examples

byteguard — Tue, 23 Jun 2026 18:18:25 +0000

Originally published on byte-guard.net.

If you build anything for the web -- APIs, SPAs, server-rendered apps, microservices -- the OWASP Top 10 is the baseline you need to know. It is the industry-standard list of the most critical web application security risks, maintained by the Open Worldwide Application Security Project and updated every few years based on real-world data.

This guide is part of our Security Tools Series — hands-on guides for the tools every security-minded developer needs.

The 2021 edition reshuffled the list significantly. Broken Access Control jumped to the number one spot. Three new categories appeared. And some old favorites got merged or renamed.

I have seen too many developers treat the OWASP Top 10 as an abstract checklist they skim once during a compliance audit. That misses the point. Every item on this list represents thousands of actual breaches. In this post, I will walk through each of the OWASP Top 10 explained with real code showing the vulnerability and the fix -- in Python and JavaScript, because those are what most web developers work with daily.

Prerequisites

Basic understanding of HTTP requests and responses
Familiarity with Python (Flask/FastAPI) or JavaScript (Node.js/Express)
A general understanding of how web applications work (client-server model)

If you are running your own servers, my SSH hardening guide and VPS hardening guide cover the infrastructure side of security.

A01: Broken Access Control

What it is: Users can act outside their intended permissions. This includes accessing other users' data, modifying records they should not touch, or escalating privileges.

Broken Access Control moved from #5 to #1 in 2021. It is the most common vulnerability found in real applications.

Vulnerable code (Python/FastAPI):

@app.get("/api/users/{user_id}/profile")
async def get_profile(user_id: int):
    # No check: any authenticated user can view any profile
    user = await db.get_user(user_id)
    return user.to_dict()

The problem: the endpoint accepts any user_id and returns the data. There is no check that the requesting user is authorized to see that profile. This is an Insecure Direct Object Reference (IDOR).

Fixed code:

@app.get("/api/users/{user_id}/profile")
async def get_profile(user_id: int, current_user: User = Depends(get_current_user)):
    if current_user.id != user_id and not current_user.is_admin:
        raise HTTPException(status_code=403, detail="Forbidden")
    user = await db.get_user(user_id)
    return user.to_dict()

Key defenses: Deny by default. Enforce ownership checks on every data access. Disable directory listing. Log access control failures and alert on repeated attempts.

A02: Cryptographic Failures

What it is: Sensitive data exposed due to weak or missing encryption. This covers data in transit (no TLS), data at rest (plaintext passwords in the database), and weak algorithms (MD5, SHA1 for passwords).

Vulnerable code (JavaScript/Node.js):

const crypto = require('crypto');

// Storing password with MD5 -- no salt, fast hash, trivially crackable
function hashPassword(password) {
  return crypto.createHash('md5').update(password).digest('hex');
}

// Connecting to database without TLS
const connection = mysql.createConnection({
  host: 'db.example.com',
  user: 'app',
  password: 'secret123',  // Hardcoded credential
  database: 'production'
});

Fixed code:

const bcrypt = require('bcrypt');

// bcrypt: slow by design, includes salt automatically
async function hashPassword(password) {
  const saltRounds = 12;
  return await bcrypt.hash(password, saltRounds);
}

async function verifyPassword(password, hash) {
  return await bcrypt.compare(password, hash);
}

// TLS-enabled connection, credentials from environment
const connection = mysql.createConnection({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  ssl: { rejectUnauthorized: true }
});

Key defenses: Use bcrypt, scrypt, or Argon2 for passwords. Enforce TLS everywhere. Never hardcode secrets -- use environment variables. Classify data and apply encryption based on sensitivity.

A03: Injection

What it is: Untrusted data sent to an interpreter as part of a command or query. SQL injection is the classic example, but this also covers NoSQL injection, OS command injection, and LDAP injection.

Vulnerable code (Python):

@app.get("/api/search")
async def search_users(username: str):
    # String concatenation -- classic SQL injection
    query = f"SELECT * FROM users WHERE username = '{username}'"
    results = await db.execute(query)
    return results

An attacker sends username=' OR '1'='1 and gets every user in the database. Or worse: '; DROP TABLE users; --.

Fixed code:

@app.get("/api/search")
async def search_users(username: str):
    # Parameterized query -- the database handles escaping
    query = "SELECT * FROM users WHERE username = :username"
    results = await db.execute(query, {"username": username})
    return results

Key defenses: Use parameterized queries or an ORM for all database access. Validate and sanitize all input. Use allowlists for expected input patterns. If you must run OS commands, never pass user input to them directly.

A04: Insecure Design

What it is: Flaws in the architecture and design of the application, not in the implementation. This category (new in 2021) covers missing security controls that should have been planned from the start.

Example scenario: An e-commerce site lets users reset their password by answering "What is your mother's maiden name?" This is an insecure design -- the security question can be researched on social media. No amount of secure coding fixes a broken design.

Another example -- no rate limiting on a sensitive endpoint:

# Insecure design: no rate limit on login attempts
@app.post("/api/login")
async def login(credentials: LoginRequest):
    user = await db.get_user_by_email(credentials.email)
    if user and verify_password(credentials.password, user.password_hash):
        return {"token": create_jwt(user)}
    raise HTTPException(status_code=401, detail="Invalid credentials")

Improved design:

from slowapi import Limiter

limiter = Limiter(key_func=get_remote_address)

@app.post("/api/login")
@limiter.limit("5/minute")  # Max 5 attempts per minute per IP
async def login(request: Request, credentials: LoginRequest):
    user = await db.get_user_by_email(credentials.email)
    if user and verify_password(credentials.password, user.password_hash):
        await db.reset_failed_attempts(user.id)
        return {"token": create_jwt(user)}
    if user:
        await db.increment_failed_attempts(user.id)
        if await db.get_failed_attempts(user.id) > 10:
            await db.lock_account(user.id)
    raise HTTPException(status_code=401, detail="Invalid credentials")

Key defenses: Threat model your application before writing code. Use abuse-case stories alongside user stories. Implement rate limiting, account lockout, and monitoring from the start.

A05: Security Misconfiguration

What it is: Insecure default configurations, incomplete configurations, open cloud storage, misconfigured HTTP headers, verbose error messages that leak sensitive information.

This is extremely common in self-hosted setups. I wrote about this in the context of containers in my Docker security guide -- default Docker configurations are not production-ready.

Vulnerable example (Express.js):

const express = require('express');
const app = express();

// Stack traces exposed to users
app.use((err, req, res, next) => {
  res.status(500).json({
    error: err.message,
    stack: err.stack,       // Leaks internal paths and code structure
    query: req.query        // Echoes back user input
  });
});

// Default headers not removed
// X-Powered-By: Express  -- tells attackers your framework

Fixed example:

const express = require('express');
const helmet = require('helmet');
const app = express();

// helmet sets security headers and removes X-Powered-By
app.use(helmet());

// Generic error handler for production
app.use((err, req, res, next) => {
  console.error(`[${new Date().toISOString()}] ${err.stack}`);  // Log internally
  res.status(500).json({
    error: 'Internal server error'  // Generic message to client
  });
});

Key defenses: Remove or change all default credentials. Disable directory listing, debug modes, and stack traces in production. Automate configuration hardening. Review cloud storage permissions.

A06: Vulnerable and Outdated Components

What it is: Using libraries, frameworks, or other software components with known vulnerabilities. This includes operating system packages, application dependencies, and container base images.

Detecting vulnerable dependencies (Python):

# Install safety (Python vulnerability scanner)
pip install safety

# Scan your requirements
safety check -r requirements.txt

# Or scan the current environment
safety check

For JavaScript projects:

# Built-in npm audit
npm audit

# For a detailed report
npm audit --json | jq '.vulnerabilities | keys'

# Fix automatically where possible
npm audit fix

For Docker images:

# Scan a Docker image with Trivy
trivy image your-app:latest

# Scan with severity filter
trivy image --severity HIGH,CRITICAL your-app:latest

Key defenses: Run dependency scanners in your CI/CD pipeline. Subscribe to security advisories for your stack. Remove unused dependencies. Use specific version pins, not ranges, for critical libraries.

A07: Identification and Authentication Failures

What it is: Weaknesses in authentication mechanisms -- permitting weak passwords, credential stuffing, missing multi-factor authentication, or improper session management.

Vulnerable session handling (Python/Flask):

from flask import Flask, session
import os

app = Flask(__name__)
app.secret_key = "super-secret-key"  # Hardcoded, predictable

@app.route("/login", methods=["POST"])
def login():
    user = authenticate(request.form["email"], request.form["password"])
    if user:
        session["user_id"] = user.id
        # Session never expires
        # Session ID not rotated after login
        # No check for brute force
        return redirect("/dashboard")

Fixed implementation:

from flask import Flask, session
from datetime import timedelta
import os
import secrets

app = Flask(__name__)
app.secret_key = os.environ["FLASK_SECRET_KEY"]  # From environment
app.config.update(
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,       # HTTPS only
    SESSION_COOKIE_SAMESITE="Lax",
    PERMANENT_SESSION_LIFETIME=timedelta(hours=1),
)

@app.route("/login", methods=["POST"])
def login():
    user = authenticate(request.form["email"], request.form["password"])
    if user:
        session.clear()                  # Invalidate old session
        session.regenerate()             # New session ID (prevents fixation)
        session["user_id"] = user.id
        session.permanent = True         # Enables expiry
        return redirect("/dashboard")

Key defenses: Implement multi-factor authentication. Enforce password complexity and check against breached password lists (haveibeenpwned API). Rotate session IDs after login. Set session timeouts.

A08: Software and Data Integrity Failures

What it is: Code and infrastructure that does not verify integrity. This includes insecure CI/CD pipelines, auto-update mechanisms without signature verification, and deserialization of untrusted data.

Vulnerable deserialization (Python):

import pickle
import base64

@app.post("/api/import")
async def import_data(data: str):
    # NEVER unpickle untrusted data -- arbitrary code execution
    obj = pickle.loads(base64.b64decode(data))
    return {"imported": len(obj)}

Pickle deserialization executes arbitrary Python code. An attacker can craft a payload that runs system commands on your server.

Fixed approach:

import json

@app.post("/api/import")
async def import_data(data: str):
    try:
        obj = json.loads(base64.b64decode(data))
        # Validate structure with Pydantic or similar
        validated = ImportSchema(**obj)
        return {"imported": len(validated.items)}
    except (json.JSONDecodeError, ValidationError) as e:
        raise HTTPException(status_code=400, detail="Invalid data format")

Key defenses: Use JSON instead of binary serialization formats. Verify digital signatures on software updates. Secure your CI/CD pipeline -- it is a high-value target. Use Subresource Integrity (SRI) for external scripts.

A09: Security Logging and Monitoring Failures

What it is: Insufficient logging, detection, monitoring, and active response. Without proper logging, breaches go undetected for months. The median time to detect a breach is still over 200 days.

Minimal (bad) logging:

@app.post("/api/login")
async def login(credentials: LoginRequest):
    user = await authenticate(credentials.email, credentials.password)
    if user:
        return {"token": create_jwt(user)}
    # No log of the failed attempt
    return {"error": "Invalid credentials"}

Proper security logging:

import logging
from datetime import datetime

security_logger = logging.getLogger("security")
security_logger.setLevel(logging.INFO)
handler = logging.FileHandler("/var/log/app/security.log")
handler.setFormatter(logging.Formatter(
    '%(asctime)s %(levelname)s %(message)s'
))
security_logger.addHandler(handler)

@app.post("/api/login")
async def login(request: Request, credentials: LoginRequest):
    client_ip = request.client.host
    user = await authenticate(credentials.email, credentials.password)

    if user:
        security_logger.info(
            f"LOGIN_SUCCESS email={credentials.email} ip={client_ip}"
        )
        return {"token": create_jwt(user)}

    security_logger.warning(
        f"LOGIN_FAILURE email={credentials.email} ip={client_ip}"
    )
    # Alert on repeated failures from same IP
    await check_brute_force(client_ip)
    raise HTTPException(status_code=401, detail="Invalid credentials")

What to log: All authentication events (success and failure), authorization failures, input validation failures, and any server-side errors. What not to log: Passwords, credit card numbers, session tokens, or personal data.

Key defenses: Log security events in a structured format. Ship logs to a central location. Set up alerts for anomalous patterns. Test that your monitoring actually catches attacks. I run Uptime Kuma for availability monitoring, but application-level logging requires dedicated tools like the ELK stack, Loki, or Graylog.

A10: Server-Side Request Forgery (SSRF)

What it is: The application fetches a remote resource based on user-supplied input without validating the destination. Attackers can make the server send requests to internal services, cloud metadata endpoints, or other systems behind the firewall.

Vulnerable code (JavaScript/Node.js):

const axios = require('axios');

app.post('/api/fetch-url', async (req, res) => {
  const { url } = req.body;
  // No validation -- attacker can target internal services
  const response = await axios.get(url);
  res.json({ data: response.data });
});

// Attacker sends: {"url": "http://169.254.169.254/latest/meta-data/"}
// This fetches AWS instance metadata including IAM credentials

Fixed code:

const axios = require('axios');
const { URL } = require('url');
const dns = require('dns').promises;
const ipaddr = require('ipaddr.js');

const ALLOWED_PROTOCOLS = ['http:', 'https:'];
const BLOCKED_HOSTS = ['metadata.google.internal', '169.254.169.254'];

async function isPrivateIP(hostname) {
  const addresses = await dns.resolve4(hostname);
  return addresses.some(addr => {
    const parsed = ipaddr.parse(addr);
    return parsed.range() !== 'unicast';  // Blocks private, loopback, link-local
  });
}

app.post('/api/fetch-url', async (req, res) => {
  const { url } = req.body;

  try {
    const parsed = new URL(url);

    if (!ALLOWED_PROTOCOLS.includes(parsed.protocol)) {
      return res.status(400).json({ error: 'Protocol not allowed' });
    }
    if (BLOCKED_HOSTS.includes(parsed.hostname)) {
      return res.status(400).json({ error: 'Host not allowed' });
    }
    if (await isPrivateIP(parsed.hostname)) {
      return res.status(400).json({ error: 'Internal addresses not allowed' });
    }

    const response = await axios.get(url, { timeout: 5000, maxRedirects: 0 });
    res.json({ data: response.data });
  } catch (err) {
    res.status(400).json({ error: 'Invalid URL or fetch failed' });
  }
});

Key defenses: Validate and sanitize all user-supplied URLs. Block requests to private IP ranges and cloud metadata endpoints. Use allowlists when the set of target URLs is known. Disable HTTP redirects or validate each redirect destination.

Security Considerations

Understanding the OWASP Top 10 is a starting point, not a finish line. These are the most common risks, not the only risks. Application security is layered:

Infrastructure layer: Harden your server (VPS hardening guide), lock down SSH (SSH hardening guide), containerize applications (Docker security guide)
Application layer: Follow the OWASP Top 10, implement defense in depth, validate all input
Process layer: Code reviews, dependency scanning, automated security testing in CI/CD

No single control stops every attack. The goal is to make exploitation expensive, detection fast, and recovery possible.

Troubleshooting

Problem: Your parameterized query still seems vulnerable to injection. Cause: You are using string formatting to build the query and then passing it to the parameterized query function. The parameterization only works if the query string itself uses placeholders. Fix: Verify that you are using :param (SQLAlchemy), ? (sqlite3), or $1 (PostgreSQL) in the query string itself, not f-strings or .format().

Problem: bcrypt is extremely slow in your application. Cause: The salt rounds are set too high for your server's CPU. Fix: 10-12 rounds is the standard recommendation. Each increment doubles the computation time. Benchmark on your hardware: time python -c "import bcrypt; bcrypt.hashpw(b'test', bcrypt.gensalt(rounds=12))".

Problem: CSP violations flooding your logs after deploying Content-Security-Policy-Report-Only. Cause: Browser extensions inject scripts that violate your CSP. These are not real attacks. Fix: Filter out known extension patterns (e.g., chrome-extension://) from your CSP reports. Focus on violations from your application's actual resources.

Problem: Rate limiting blocks legitimate users behind a shared IP (corporate NAT, VPN). Cause: IP-based rate limiting cannot distinguish between users sharing an IP. Fix: Combine IP-based limits with account-based limits. Use X-Forwarded-For carefully (it can be spoofed). Consider CAPTCHA challenges instead of hard blocks for borderline cases.

Problem: npm audit reports hundreds of vulnerabilities, mostly in dev dependencies. Cause: Many audit findings are in transitive dependencies used only during development, not in production code. Fix: Use npm audit --production to filter to production dependencies only. Prioritize direct dependencies with HIGH or CRITICAL severity.

Conclusion

The OWASP Top 10 is not a compliance checkbox -- it is a map of how real applications get breached. Every item on the list corresponds to thousands of real incidents, and the code examples above represent patterns I have seen in production codebases.

The most impactful changes you can make right now: use parameterized queries everywhere, enforce access control checks at every endpoint, hash passwords with bcrypt or Argon2, and log all authentication events.

For infrastructure-level hardening to complement your application security, check out my VPS hardening guide and Docker security best practices.

Building a secure application from scratch? You will need a solid server foundation. I run all my projects on Hetzner -- reliable, affordable, and great performance. Check out their cloud plans.

How to Monitor Your Server with Uptime Kuma

byteguard — Tue, 23 Jun 2026 18:17:21 +0000

Originally published on byte-guard.net.

TL;DR

Deploy Uptime Kuma with Docker Compose and monitor your websites, APIs, and Docker containers in minutes. Get instant alerts via Telegram, email, or Slack when anything goes down — and publish a public status page for your users.

You deploy your blog, your password manager, your VPN — and then what? You assume it's all running fine until someone tells you it's down. Maybe that someone is a reader. Maybe it's you, three hours later, wondering why your site feels slow.

Uptime Kuma fixes this. It's a self-hosted monitoring tool that checks your services on a schedule and alerts you the moment something goes down. I run it at status.byte-guard.net to monitor every service in my stack. This Uptime Kuma setup guide walks you through installation, configuring monitors, setting up notifications, and creating a public status page.

If you run anything on a server, you need monitoring. Here's how to set it up in under 10 minutes.

What Do You Need to Run Uptime Kuma with Docker?

A Linux VPS with Docker and Docker Compose (here's how I set mine up)
A reverse proxy for SSL (Nginx Proxy Manager, Caddy, or Traefik)
At least one service to monitor (your blog, an API, anything)

How Do You Deploy Uptime Kuma with Docker Compose?

Create a directory:

sudo mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

Create the compose file:

# docker-compose.yml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - kuma_data:/app/data
    ports:
      - "127.0.0.1:3001:3001"
    restart: unless-stopped

volumes:
  kuma_data:

Start it:

docker compose up -d

The container binds to 127.0.0.1:3001 — accessible only from localhost. Your reverse proxy handles the public-facing SSL.

Set Up the Reverse Proxy

In Nginx Proxy Manager, add a proxy host: - Domain: status.yourdomain.com - Forward hostname: uptime-kuma (or 127.0.0.1) - Forward port: 3001 - SSL: enable, request Let's Encrypt certificate - WebSocket support: enable (required for real-time updates)

In Caddy, add to your Caddyfile:

status.yourdomain.com {
    reverse_proxy uptime-kuma:3001
}

Open https://status.yourdomain.com and create your admin account. Do this immediately — the first person to visit creates the admin account.

How Do You Add Your First Uptime Monitors?

Click "Add New Monitor" in the dashboard. Uptime Kuma supports many monitor types:

HTTP(s) Monitor

The most common type. It checks a URL and verifies the response code.

Monitor Type: HTTP(s)
URL: https://blog.byte-guard.net
Heartbeat Interval: 60 seconds
Retries: 3 (avoids false positives from temporary network blips)
Accepted Status Codes: 200-299

This checks your blog every 60 seconds. If it returns a non-2xx status code 3 times in a row, it's marked as down.

TCP Port Monitor

Checks if a specific port is open. Useful for databases, mail servers, or any service that doesn't serve HTTP.

Monitor Type: TCP Port
Hostname: 127.0.0.1
Port: 3306 (MySQL) or 5432 (PostgreSQL)
Heartbeat Interval: 120 seconds

Ping Monitor

Simple ICMP ping. Checks if a host is reachable.

Monitor Type: Ping
Hostname: 10.0.0.1
Heartbeat Interval: 60 seconds

Docker Container Monitor

Checks if a Docker container is running. Requires mounting the Docker socket.

Update your compose file to mount the socket:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - kuma_data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:3001:3001"
    restart: unless-stopped

Security note: Mounting the Docker socket gives Uptime Kuma read access to all your containers. Mount it read-only (:ro) and be aware of the Docker security implications. If this concerns you, use HTTP monitors instead — they verify the service is actually responding, not just that the container is running.

Restart and add a Docker container monitor: - Monitor Type: Docker Container - Container Name: ghost

What Does a Real-World Uptime Kuma Monitor Setup Look Like?

Here's what I actually monitor:

Service	Monitor Type	Interval	URL/Target
Blog	HTTP(s)	60s	`https://blog.byte-guard.net`
Status page	HTTP(s)	60s	`https://status.byte-guard.net`
Ghost Admin	HTTP(s)	120s	`https://blog.byte-guard.net/ghost/`
NPM Dashboard	HTTP(s)	120s	Internal IP:81
SSH	TCP Port	120s	Server IP, port 22
VPS Ping	Ping	60s	Server IP

Six monitors, all running on the same VPS they're monitoring. Yes, if the VPS goes down, Uptime Kuma goes down too — it can't alert you. For critical infrastructure, you'd run Uptime Kuma on a separate server. For a blog, this is fine. I'd know from the DNS monitoring on my other setup.

How Do You Configure Uptime Kuma Notifications?

Monitoring without alerts is a dashboard you never check. Set up notifications so you know the moment something breaks.

Go to Settings → Notifications and click "Setup Notification."

Discord Webhook

In your Discord server, go to channel settings → Integrations → Webhooks
Create a webhook, copy the URL
In Uptime Kuma: Notification Type → Discord, paste the webhook URL
Test and save

Telegram Bot

Message @BotFather on Telegram, create a bot, get the token
Get your Chat ID by messaging @userinfobot
In Uptime Kuma: Notification Type → Telegram, enter bot token and chat ID
Test and save

Email (SMTP)

SMTP Host: your mail server (e.g., smtp.gmail.com)
SMTP Port: 587
From/To: your email addresses
Username/Password: your SMTP credentials

Apply Notifications to Monitors

After creating a notification channel, edit each monitor and check the notification methods you want. You can assign different notifications to different monitors — critical services get Telegram + Discord, less important ones get email only.

How Do You Create an Uptime Kuma Public Status Page?

This is one of Uptime Kuma's best features. A public page showing your service status — like status.byte-guard.net.

Go to Status Pages in the sidebar
Click "New Status Page"
Set the title and slug (e.g., "ByteGuard Status" at /status)
Add monitor groups — drag your monitors into sections
Customize: description, footer text, and theme
Save and publish

The status page shows: - Current status of each service (up/down/maintenance) - Uptime percentage over the last 90 days - Incident history - A heartbeat graph for each monitor

Maintenance Windows

When you're doing planned maintenance, create a maintenance window so your monitors don't fire false alerts:

Go to Maintenance in the sidebar
Create a new maintenance window with start/end times
Select which monitors are affected

During the window, affected monitors show "Maintenance" instead of "Down" on the status page.

What Are Uptime Kuma’s Advanced Configuration Options?

Monitor Groups and Tags

Organize monitors with tags (e.g., "production", "staging", "internal") and group them on your status page. This keeps things manageable as your monitor count grows.

Upside-Down Mode

Inverts the monitor logic — alerts when a service comes up instead of going down. Useful for monitoring ports that should be closed or services that should be off.

Certificate Expiry Monitoring

HTTP(s) monitors automatically track SSL certificate expiry. You'll see the expiry date in the monitor details and get notified when it's approaching expiry (configurable threshold, default 30 days).

API and Integrations

Uptime Kuma has a push monitor type where your service sends heartbeats to Uptime Kuma instead of Kuma polling the service. Useful for cron jobs and batch processes:

# Add to the end of your cron script
curl -s "https://status.yourdomain.com/api/push/<PUSH_TOKEN>?status=up&msg=OK" > /dev/null

If the push doesn't arrive within the expected interval, the monitor marks as down.

How Do You Secure Your Uptime Kuma Instance?

Authentication. Uptime Kuma requires login, but make sure you set a strong password. There's no 2FA built in — protect it with your reverse proxy (IP whitelist or HTTP basic auth on top).
Docker socket. If mounted, it's read-only but still exposes container metadata. Consider whether HTTP monitors are sufficient for your needs.
Status page visibility. Public status pages are just that — public. Don't include internal service names, IP addresses, or ports that you don't want exposed.
Data retention. Monitor data grows over time. Uptime Kuma stores heartbeats in SQLite. For long-running instances, check the database size periodically: docker exec uptime-kuma ls -lh /app/data/kuma.db.

How Do You Troubleshoot Uptime Kuma Issues?

Problem: Dashboard shows "WebSocket connection failed." Cause: Your reverse proxy isn't forwarding WebSocket connections. Fix: In NPM, enable "WebSocket Support" for the proxy host. In Nginx manually, add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";.

Problem: Monitor shows "Down" but the service works fine in browser. Cause: The monitor is checking the wrong URL or port, or the service responds differently to non-browser requests. Fix: Verify the URL is exactly right (including https://). Check if the service requires specific headers — some apps return 403 without a proper User-Agent.

Problem: Notifications not sending. Cause: SMTP credentials wrong, Discord webhook expired, or Telegram bot token invalid. Fix: Use the "Test" button on each notification channel. Check Uptime Kuma logs: docker compose logs uptime-kuma.

Problem: Status page shows blank. Cause: No monitors assigned to the status page groups. Fix: Edit the status page, add groups, and drag monitors into them. Save and refresh.

Problem: High CPU usage. Cause: Too many monitors with very short intervals. Fix: Increase heartbeat intervals for non-critical monitors. 60 seconds is aggressive — 120-300 seconds is fine for most services.

Why Should You Self-Host Uptime Kuma Instead of Using a SaaS Service?

Uptime Kuma takes 10 minutes to set up and saves you from the embarrassment of finding out your site is down from a reader's complaint — or worse, not finding out at all.

I've been running it for the entire ByteGuard stack and it's caught two outages before anyone noticed. The public status page builds trust with readers, and the notification system is reliable across Discord, Telegram, and email.

For next steps:

Follow Docker security best practices to lock down the container
Set up Fail2Ban on your server for broader monitoring
Check my original VPS setup guide if you're starting from scratch

If you need a VPS, I use Hetzner — their CPX22 handles all my services including Uptime Kuma with plenty of headroom.