locals {
  # With a domain, Caddy serves HTTPS with an automatic Let's Encrypt certificate.
  # Without one, it serves plain HTTP on port 80 at the floating IP.
  caddy_site = var.domain != "" ? var.domain : ":80"
}

data "openstack_images_image_v2" "os" {
  name        = var.image_name
  most_recent = true
}

data "openstack_networking_network_v2" "external" {
  name = var.external_network
}

resource "openstack_networking_network_v2" "private" {
  name           = "${var.app_name}-net"
  admin_state_up = true
}

resource "openstack_networking_subnet_v2" "private" {
  name            = "${var.app_name}-subnet"
  network_id      = openstack_networking_network_v2.private.id
  cidr            = var.private_cidr
  ip_version      = 4
  dns_nameservers = ["1.1.1.1", "8.8.8.8"]
}

resource "openstack_networking_router_v2" "main" {
  name                = "${var.app_name}-router"
  external_network_id = data.openstack_networking_network_v2.external.id
}

resource "openstack_networking_router_interface_v2" "private" {
  router_id = openstack_networking_router_v2.main.id
  subnet_id = openstack_networking_subnet_v2.private.id
}

resource "openstack_networking_secgroup_v2" "proxy" {
  name        = "${var.app_name}-sg"
  description = "SSH and HTTP/HTTPS for the edge reverse proxy"
}

resource "openstack_networking_secgroup_rule_v2" "ssh" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 22
  port_range_max    = 22
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.proxy.id
}

resource "openstack_networking_secgroup_rule_v2" "http" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 80
  port_range_max    = 80
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.proxy.id
}

resource "openstack_networking_secgroup_rule_v2" "https" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 443
  port_range_max    = 443
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.proxy.id
}

resource "openstack_networking_port_v2" "proxy" {
  name               = "${var.app_name}-port"
  network_id         = openstack_networking_network_v2.private.id
  security_group_ids = [openstack_networking_secgroup_v2.proxy.id]

  fixed_ip {
    subnet_id = openstack_networking_subnet_v2.private.id
  }

  depends_on = [openstack_networking_router_interface_v2.private]
}

resource "openstack_blockstorage_volume_v3" "data" {
  name = "${var.app_name}-data"
  size = var.volume_size
}

resource "openstack_compute_instance_v2" "proxy" {
  name        = var.app_name
  flavor_name = var.flavor_name
  key_pair    = var.key_name

  user_data = templatefile("${path.module}/cloud-init/proxy.yaml.tftpl", {
    caddy_site    = local.caddy_site
    caddy_version = var.caddy_version
    upstream_host = var.upstream_host
    upstream_port = var.upstream_port
  })

  block_device {
    uuid                  = data.openstack_images_image_v2.os.id
    source_type           = "image"
    destination_type      = "volume"
    volume_size           = 20
    boot_index            = 0
    delete_on_termination = true
  }

  network {
    port = openstack_networking_port_v2.proxy.id
  }
}

resource "openstack_compute_volume_attach_v2" "data" {
  instance_id = openstack_compute_instance_v2.proxy.id
  volume_id   = openstack_blockstorage_volume_v3.data.id
}

resource "openstack_networking_floatingip_v2" "proxy" {
  pool = var.external_network
}

resource "openstack_networking_floatingip_associate_v2" "proxy" {
  floating_ip = openstack_networking_floatingip_v2.proxy.address
  port_id     = openstack_networking_port_v2.proxy.id
}

variable "key_name" {
  description = "SSH keypair name (must already exist in your project)"
  type        = string
}

variable "flavor_name" {
  description = "Instance size. Caddy is a lightweight reverse proxy: 2 vCPU and 2 GiB RAM handle steady TLS termination and routing for a typical app backend. Raise the flavor only for very high connection counts or large upload bodies."
  type        = string
  default     = "s1a.small"
}

variable "image_name" {
  description = "Operating system image. cloud-init targets a Debian-family distribution; Ubuntu 24.04 is the recommended base."
  type        = string
  default     = "Ubuntu-24.04"
}

variable "app_name" {
  description = "Display name prefix for compute and network resources"
  type        = string
  default     = "edge-reverse-proxy"
}

variable "caddy_version" {
  description = "Caddy container image tag. The default 2-alpine tracks the current Caddy 2 release on a minimal base; pin a specific tag (for example 2.9.1-alpine) for reproducible rebuilds."
  type        = string
  default     = "2-alpine"
}

variable "domain" {
  description = "Public domain for the proxy front door. When set, Caddy obtains a Let's Encrypt certificate and serves HTTPS automatically. Point the domain's DNS A record at the floating IP before traffic arrives. Leave empty to serve plain HTTP on port 80 at the floating IP."
  type        = string
  default     = ""
}

variable "upstream_host" {
  description = "Private IP address of the backend instance Caddy proxies to. The backend stays on the private subnet with no floating IP of its own; lock its security group to accept traffic only from this proxy's private IP."
  type        = string
  default     = "10.42.0.10"
}

variable "upstream_port" {
  description = "TCP port the backend listens on within the private network"
  type        = number
  default     = 8080
}

variable "volume_size" {
  description = "Block volume size in GiB for Caddy certificates and config state. The volume mounts at /data so TLS material and the Caddy data directory live on a resizable volume rather than the boot disk."
  type        = number
  default     = 10
}

variable "external_network" {
  description = "Shared external network for router gateway and floating IPs; defaults to PublicStatic (persisted FIP / production pattern). Override with PublicEphemeral for ephemeral demos."
  type        = string
  default     = "PublicStatic"
}

variable "private_cidr" {
  description = "CIDR for the private tenant network the proxy lives in"
  type        = string
  default     = "10.42.0.0/24"
}

#cloud-config
package_update: true
packages:
  - ca-certificates
  - curl
write_files:
  - path: /opt/edge-proxy/Caddyfile
    permissions: "0644"
    content: |
      ${caddy_site} {
          reverse_proxy ${upstream_host}:${upstream_port}
      }
  - path: /opt/edge-proxy/docker-compose.yml
    permissions: "0644"
    content: |
      services:
        caddy:
          image: caddy:${caddy_version}
          restart: unless-stopped
          ports:
            - "80:80"
            - "443:443"
          volumes:
            - /opt/edge-proxy/Caddyfile:/etc/caddy/Caddyfile:ro
            - /data/caddy:/data
            - /data/caddy-config:/config
runcmd:
  - |
    set -e
    # The data volume attaches as /dev/sdb on this platform. Mount it at /data
    # before Docker starts so Caddy certificate state lives on the resizable
    # volume rather than the boot disk.
    DEV=/dev/sdb
    for i in $(seq 1 30); do [ -b "$DEV" ] && break; sleep 5; done
    if ! blkid "$DEV" >/dev/null 2>&1; then mkfs.ext4 -F -L proxydata "$DEV"; fi
    mkdir -p /data/caddy /data/caddy-config
    mount "$DEV" /data
    grep -q "$DEV" /etc/fstab || echo "$DEV /data ext4 defaults,nofail 0 2" >> /etc/fstab
    curl -fsSL https://get.docker.com | sh
    cd /opt/edge-proxy
    docker compose up -d

# Edge reverse proxy

Single compute instance running [Caddy](https://caddyserver.com), an open-source reverse proxy with automatic HTTPS, on infrastructure you control. The proxy terminates TLS on a floating IP and forwards traffic to a private backend that has no public address of its own.


**Network class:** production — `external_network` defaults to `PublicStatic` for persisted floating IPs and multi-tier stacks; override with `PublicEphemeral` for ephemeral demos.

The instance provisions a private network, a floating IP, and a block volume mounted at `/data` so Caddy certificate state lives on a resizable volume rather than the boot disk. cloud-init installs Docker, writes a Caddyfile that reverse-proxies to your backend, and starts Caddy on first boot.

## Where this fits

This template provides the reverse proxy and TLS foundation for the edge and gateway template family. It implements the self-managed front door shape from the [front with a WAF](/docs/network/how-to/front-with-waf) how-to without the WAF engine. Pair it with a [containerized app](/resources/iac-templates/containerized-app) or [three-tier app](/resources/iac-templates/three-tier-app) backend on the same private network.

This proxy runs in one region on a VM you operate. It is not a global edge network. For geographic distribution, [front the origin with a third-party CDN](/docs/network/how-to/front-with-cdn).

## Prerequisites

- OpenTofu >= 1.6.0 or Terraform >= 1.6.0
- Quake AI account with OpenStack credentials
- An existing SSH keypair in your project (the value of `key_name` must match that keypair)
- A backend instance on the private network (or plan to deploy one after the proxy)

## Resource baseline

Caddy is a single lightweight process. The default `s1a.small` flavor (2 shared vCPU, 2 GiB RAM) handles steady TLS termination for a typical app backend. The boot disk is 20 GiB; certificate and config state live on the separate data volume (`volume_size`, default 10 GiB).

## Usage

1. Clone or copy this template directory
2. Copy `terraform.tfvars.example` to `terraform.tfvars` and set `key_name`, `upstream_host`, and `upstream_port` (and `domain` if you have one)
3. Source your OpenStack credentials: `source openrc.sh`
4. Initialize: `tofu init`
5. Preview: `tofu plan`
6. Apply: `tofu apply`

cloud-init takes a few minutes on first boot to install Docker, mount the data volume, and start Caddy. The proxy then answers on `proxy_url` from the outputs.

## Domain and TLS

With `domain` set and its DNS A record pointed at `floating_ip`, Caddy obtains a Let's Encrypt certificate automatically and serves HTTPS on 443. With `domain` empty, Caddy serves plain HTTP on port 80 at the floating IP.

For the DNS steps, see [point a domain to Quake AI](/docs/network/how-to/point-domain-to-quake-ai) and [Let's Encrypt certificates](/docs/network/how-to/lets-encrypt-certificate).

## Backend security

Set `upstream_host` to the private IP of your backend. The backend should have no floating IP. After apply, lock the backend security group so it accepts traffic on `upstream_port` only from the proxy's `private_ip` output.

## Alternate engines

This template leads with Caddy for automatic HTTPS and minimal config. [Traefik 3](https://traefik.io) fits stacks that need dynamic service discovery across many containers. [Nginx Proxy Manager](https://nginxproxymanager.com) fits operators who want a web UI instead of editing config files. Both are MIT-licensed and run on the same single-VM shape; swap the container image and config in cloud-init if you prefer one of them.

## Outputs

| Output | Description |
| --- | --- |
| `floating_ip` | Public floating IP of the proxy |
| `private_ip` | Private IP of the proxy on the tenant network |
| `proxy_url` | HTTPS on the domain when set, otherwise HTTP on the floating IP |
| `instance_id` | Compute instance ID |

## Validation

This template passes `tofu validate` in CI. That check confirms the OpenTofu configuration is well-formed against the provider schema; it does not run `tofu apply` against a live account.