DEV Community: Yaroslav

Setting up nginx as a reverse proxy

Yaroslav — Tue, 01 Sep 2026 07:39:54 +0000

If you run more than one service on a server, you need a single entry point in front of them. Instead of setting up a web server and SSL inside every service, it gets handled once, in one place.

We will use jwilder/nginx-proxy. It watches the Docker socket and builds nginx config automatically, based on labels and env vars on your containers. No manual nginx.conf editing every time you add a service.

Prerequisites:

A server with Docker and the Docker Compose plugin installed.
A domain name pointed at the server (needed later for SSL).
Basic comfort with docker compose files.

Base setup: nginx-proxy

The core piece is the nginx-proxy container itself. It exposes ports 80 and 443, and reads the Docker socket to see which containers are running. When a container starts or stops, it updates the routing on its own.

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx_proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - html:/usr/share/nginx/html
      - certs_volume:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - /srv/nginx-vhosts:/etc/nginx/vhost.d:ro
    networks:
      - webproxy

The docker socket mount lets nginx-proxy see new containers as they appear. The vhost.d mount is a folder for custom nginx snippets per domain, we will use this later to lock down some endpoints from public access.

Adding HTTPS with acme-companion

Plain HTTP is not enough for anything public, so we add acme-companion, which pairs with nginx-proxy and handles Let's Encrypt certificates.

  acme-companion:
    image: nginxproxy/acme-companion
    container_name: acme_companion
    environment:
      - DEFAULT_EMAIL=${EMAIL}
    volumes:
      - certs_volume:/etc/nginx/certs:rw
      - acme:/etc/acme.sh
      - /var/run/docker.sock:/var/run/docker.sock:ro
    volumes_from:
      - nginx-proxy
    networks:
      - webproxy
    restart: unless-stopped

It shares the certs volume with nginx-proxy through volumes_from, so both containers see the same certificate files.

Full docker-compose.yml

Let's put both containers, volumes, and networks together:

version: '3.8'

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx_proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - html:/usr/share/nginx/html
      - certs_volume:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - /srv/nginx-vhosts:/etc/nginx/vhost.d:ro
    networks:
      - webproxy

  acme-companion:
    image: nginxproxy/acme-companion
    container_name: acme_companion
    environment:
      - DEFAULT_EMAIL=${EMAIL}
    volumes:
      - certs_volume:/etc/nginx/certs:rw
      - acme:/etc/acme.sh
      - /var/run/docker.sock:/var/run/docker.sock:ro
    volumes_from:
      - nginx-proxy
    networks:
      - webproxy
    restart: unless-stopped

volumes:
  certs_volume:
  acme:
  html:

networks:
  webproxy:
    external: true

The webproxy network is marked external, meaning it is not created by this compose file. We create it once by hand, and every service that wants to sit behind the proxy joins this same network.

Environment variables

.env:

EMAIL=admin@example.com

EMAIL is used by acme-companion as the default contact address for Let's Encrypt. Fill it in with a real address, because Let's Encrypt sends expiry warnings there.

Creating the network

Since the network is external, create it before the first deploy:

docker network create webproxy

Run this once per server. Every stack that needs to be reachable through the proxy connects to this network.

Creating the vhost directory

nginx-proxy mounts /srv/nginx-vhosts as a read only folder for per-domain nginx snippets. Services publish their own config fragments here, e.g. to restrict access to internal routes. Create the folder and give your user ownership:

sudo mkdir -p /srv/nginx-vhosts
sudo chown $USER:$USER /srv/nginx-vhosts

Connecting a service to the proxy

Any container can join the proxy without touching nginx directly. Add a few env vars and put the container on the webproxy network.

version: '3.8'

services:
  myapp:
    build: .
    container_name: myapp
    restart: unless-stopped
    environment:
      - VIRTUAL_HOST=${DOMAIN}
      - VIRTUAL_PORT=8000
      - LETSENCRYPT_HOST=${DOMAIN}
      - LETSENCRYPT_EMAIL=${EMAIL}
    networks:
      - webproxy

networks:
  webproxy:
    external: true

VIRTUAL_HOST tells nginx-proxy which domain routes to this container. VIRTUAL_PORT is the port your app listens on inside the container. LETSENCRYPT_HOST and LETSENCRYPT_EMAIL tell acme-companion to request a certificate for that domain.

.env for the service:

DOMAIN=localhost
EMAIL=admin@example.com

Replace localhost with your real domain before deploying.

Custom nginx config for a service

Sometimes the default routing is not enough. A route needs an IP allow list, custom headers, or something else nginx-proxy does not expose through env vars. For this, place a config snippet into /srv/nginx-vhosts/${DOMAIN}, and nginx-proxy loads it automatically for that domain.

A generic template, filled in by a deploy script using envsubst:

location /internal/ {
    allow 10.0.0.0/8;
    deny all;

    proxy_pass         http://${DOMAIN};
    proxy_set_header   Host              $http_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-Port  $server_port;
    proxy_http_version 1.1;
}

Now, only requests from the allowed range reach the route, everything else gets a 403. For a full example of a deploy script that fills in a template like this, see this article.

Conclusion

We now have one nginx-proxy container in front of everything, and it picks up new services on its own, no manual nginx edits needed. Certificates renew automatically through acme-companion, and any route that needs special rules gets its own config. From here, any service just joins the webproxy network and gets a domain and SSL for free.

Setting up Keycloak as a central identity provider

Yaroslav — Tue, 25 Aug 2026 06:22:50 +0000

This is the first article in a series about Keycloak. We will set up Keycloak as an authentication provider and later connect it to internal services. In the end we get a single entry point and a single user provider for all of them.

In this article we set up Keycloak itself, get the admin console running, and lock it down properly.

Installation

We run Keycloak with Docker, behind an existing nginx reverse proxy. This guide assumes such a proxy (e.g. jwilder/nginx-proxy with an ACME companion for SSL) is already running on the host and shared across services, listening on the webproxy docker network.

Make sure Docker and the Docker Compose plugin are installed on the server first:

docker --version
docker compose version

If these commands fail, install Docker using the official instructions for your OS. Once Docker is ready, create a folder on the server for the project, e.g. /opt/docker.keycloak. We will place the files there step by step: docker-compose.yml, .env, nginx/vhost.conf, and deploy.sh.

Configuration

docker-compose.yml:

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.2
    container_name: keycloak
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: ${KC_DB_USERNAME:-keycloak}
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_ADMIN:-admin}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_HOSTNAME: ${DOMAIN}
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_HOSTNAME_STRICT: "false"
      KC_HEALTH_ENABLED: "true"
      JAVA_OPTS_APPEND: ${KC_JAVA_OPTS:--Xms512m -Xmx512m}
      VIRTUAL_HOST: ${DOMAIN}
      VIRTUAL_PORT: 8080
      LETSENCRYPT_HOST: ${DOMAIN}
      LETSENCRYPT_EMAIL: ${EMAIL}
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - keycloak
      - webproxy
    healthcheck:
      test: [ "CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9000 && printf 'GET /health/ready HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'" ]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 90s
    deploy:
      resources:
        limits:
          memory: 1g
    restart: unless-stopped

  postgres:
    image: postgres:17
    container_name: keycloak_postgres
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: ${KC_DB_USERNAME:-keycloak}
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
    volumes:
      - keycloak_data:/var/lib/postgresql/data
    networks:
      - keycloak
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB" ]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 512m
    restart: unless-stopped

networks:
  keycloak:
    driver: bridge
  webproxy:
    external: true

volumes:
  keycloak_data:

The setup has two containers: Keycloak and Postgres. Keycloak stores realm and user data in Postgres, so the database needs to be healthy before Keycloak starts. The webproxy network connects Keycloak to an external nginx reverse proxy.

Environment variables

.env:

DOMAIN=localhost
EMAIL=admin@example.com

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=

KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=

DOMAIN: the domain for Keycloak (e.g. auth.example.com)
EMAIL: email for the Let's Encrypt SSL certificate
KEYCLOAK_ADMIN: Keycloak admin username
KEYCLOAK_ADMIN_PASSWORD: admin password
KC_DB_USERNAME: Postgres username (default keycloak)
KC_DB_PASSWORD: Postgres password

Fill in DOMAIN, EMAIL, and both passwords before the first run.

Restricting admin access

The admin console and the master realm give full control over Keycloak. If this is open to the web, it becomes a direct target for brute force and credential stuffing. The safe option is to close it from the outside and allow access only from 127.0.0.1, then reach it through an SSH tunnel when needed.

nginx/vhost.conf:

# Keycloak admin access restriction.
# Template: ${DOMAIN} is substituted by deploy.sh via envsubst.
#
# Admin interface is accessible only via SSH tunnel from localhost.

location /auth/admin/ {
    allow 127.0.0.1;
    deny all;

    proxy_pass         http://${DOMAIN};
    proxy_set_header   Host              $http_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-Port  $server_port;
    proxy_set_header   Proxy             "";
    proxy_http_version 1.1;
}

location /auth/realms/master/ {
    allow 127.0.0.1;
    deny all;

    proxy_pass         http://${DOMAIN};
    proxy_set_header   Host              $http_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-Port  $server_port;
    proxy_set_header   Proxy             "";
    proxy_http_version 1.1;
}

This config blocks the admin console and the master realm from the public internet. Only requests from 127.0.0.1 get through. This means the admin panel is reachable only through an SSH tunnel, which we set up below.

Deployment

With the config files ready, one script publishes the nginx vhost and starts Keycloak.

deploy.sh:

#!/bin/bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
VHOSTS_DIR="/srv/nginx-vhosts"

# Load .env
set -a
source "${SCRIPT_DIR}/.env"
set +a

if [[ -z "${DOMAIN:-}" ]]; then
    echo "Error: DOMAIN is not set in .env" >&2
    exit 1
fi

# Publish nginx vhost config
echo "Publishing nginx config for ${DOMAIN}..."
mkdir -p "${VHOSTS_DIR}"
envsubst '${DOMAIN}' < "${SCRIPT_DIR}/nginx/vhost.conf" > "${VHOSTS_DIR}/${DOMAIN}"

# Reload nginx
if docker inspect nginx_proxy &>/dev/null; then
    docker exec nginx_proxy nginx -s reload
    echo "nginx reloaded."
else
    echo "Warning: nginx_proxy container not found, skipping reload."
fi

# Start Keycloak
echo "Starting Keycloak..."
docker compose -f "${SCRIPT_DIR}/docker-compose.yml" up -d

Run it with:

./deploy.sh

The script does three things:

Fills DOMAIN from .env into nginx/vhost.conf and writes the result to /srv/nginx-vhosts/${DOMAIN}.
Reloads nginx_proxy.
Starts Keycloak with docker compose up -d.

Admin console access

/auth/admin/ and /auth/realms/master/ are closed to the outside world. Only 127.0.0.1 can reach them.

Open an SSH tunnel from your local machine:

ssh -L 8443:127.0.0.1:443 user@server -N

Add this line to /etc/hosts:

127.0.0.1 auth.example.com

Open in the browser:

https://auth.example.com:8443/auth/admin/

Log in with the credentials from KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD. Close the tunnel with Ctrl+C when done.

Testing

After Keycloak starts, open the admin console through the SSH tunnel. You will see the Keycloak login screen.

After logging in, you start in the master realm. Do not use it for your applications and users: master controls Keycloak itself, including the admin account, and a leaked token from your applications should never reach it.

Create a separate realm for your organization instead. Click Create realm, give it a name (e.g. your company name), and save.

From this point, the realm is ready for clients, users, and roles. Everything you connect to Keycloak goes into this realm, not into master.

Conclusion

We now have a working Keycloak instance with a Postgres database and a locked down admin console. It can create realms, manage users, and issue tokens, which is everything a service needs to delegate its login screen to Keycloak.