locals {
  # Render container_env into `-e KEY=VALUE` docker flags. Empty map is a no-op.
  container_env_flags = join(
    " ",
    [for k, v in var.container_env : "-e ${k}=${v}"],
  )

  # With a domain, Caddy serves HTTPS with an automatic certificate. Without
  # one, it serves plain HTTP on the public host port. Both reverse-proxy to the
  # Next.js container bound to localhost.
  caddy_site = var.domain != "" ? var.domain : ":${var.host_port}"
}

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" "app" {
  name        = "${var.app_name}-sg"
  description = "Allow SSH and HTTP/HTTPS traffic for the Next.js 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.app.id
}

resource "openstack_networking_secgroup_rule_v2" "http" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = var.host_port
  port_range_max    = var.host_port
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.app.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.app.id
}

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

  fixed_ip {
    subnet_id = openstack_networking_subnet_v2.private.id
  }

  depends_on = [openstack_networking_router_interface_v2.private]
}

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

  user_data = templatefile("${path.module}/cloud-init/app.yaml", {
    container_image = var.container_image
    app_port        = var.app_port
    host_port       = var.host_port
    env_flags       = local.container_env_flags
    caddy_site      = local.caddy_site
  })

  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.app.id
  }
}

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

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

variable "flavor_name" {
  description = "Instance size (maps from quake.yaml environments.*.resources flavor alias)"
  type        = string
  default     = "s1a.small"
}

variable "image_name" {
  description = "Operating system image"
  type        = string
  default     = "Ubuntu-24.04"
}

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

variable "app_name" {
  description = "Display name prefix for compute and network resources"
  type        = string
  default     = "nextjs-app"
}

variable "container_image" {
  description = "Prebuilt Next.js container image to pull and run on first boot. Build it from the standalone Dockerfile in docker/ and push it to a registry the instance can reach."
  type        = string
  default     = "registry.example.com/nextjs-app:latest"
}

variable "container_env" {
  description = "Environment variables injected into the container at boot, by name (maps from quake.yaml secrets and resolved service outputs, for example DATABASE_URL). Document names here, not secret values."
  type        = map(string)
  default     = {}
}

variable "app_port" {
  description = "Port the Next.js server listens on inside the container (PORT). Next.js standalone defaults to 3000."
  type        = number
  default     = 3000
}

variable "host_port" {
  description = "Public HTTP port the reverse proxy listens on. With a domain set, the proxy also serves HTTPS on 443."
  type        = number
  default     = 80
}

variable "domain" {
  description = "Optional fully qualified domain name. When set, the reverse proxy obtains a certificate and serves HTTPS automatically. Point the domain's DNS A record at the floating IP before apply. Leave empty to serve HTTP only."
  type        = string
  default     = ""
}

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 instance lives in"
  type        = string
  default     = "10.10.10.0/24"
}

output "instance_id" {
  description = "ID of the compute instance running the Next.js container"
  value       = openstack_compute_instance_v2.app.id
}

output "floating_ip" {
  description = "Public floating IP address for the Next.js app"
  value       = openstack_networking_floatingip_v2.app.address
}

output "private_ip" {
  description = "Private IP address of the instance"
  value       = openstack_compute_instance_v2.app.access_ip_v4
}

output "app_url" {
  description = "URL for the running app. HTTPS on the domain when set, otherwise HTTP on the floating IP and host port."
  value = var.domain != "" ? "https://${var.domain}" : (
    var.host_port == 80
    ? "http://${openstack_networking_floatingip_v2.app.address}"
    : "http://${openstack_networking_floatingip_v2.app.address}:${var.host_port}"
  )
}

# Next.js App

Single compute instance running a containerized Next.js app behind a Caddy reverse proxy, with a floating IP and automatic HTTPS when you supply a domain. Specialization of `containerized-app` with Next.js-shaped defaults (`app_port` 3000, a reverse proxy for TLS, and a documented standalone Dockerfile).


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

## quake.yaml mapping

A Next.js deploy is `runtime: container` with a Node Dockerfile. When a launch manifest declares a Next.js app, the handoff resolves it to a container runtime template; this template is the Next.js-shaped option alongside the generic `containerized-app`.

| `quake.yaml` field | Maps to |
| --- | --- |
| `runtime: container` | Container runtime template (`nextjs-app` or `containerized-app`) |
| `source.build: dockerfile` | Build the standalone image in CI (see `docker/Dockerfile`), push to a registry, then set `container_image` before apply |
| `environments.production.resources: cpu-standard` | `flavor_name = "m2a.large"` |
| `environments.preview.resources: cpu-small` | `flavor_name = "s1a.small"` |
| `secrets` and resolved `services` outputs | `container_env` map injected into the running container |

## 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 prebuilt Next.js container image reachable from the instance on first boot (public registry or project-accessible registry)

## Build the image

The app must be built with `output: "standalone"` in `next.config.js`. The included `docker/Dockerfile` is a multi-stage build that produces a minimal runtime image:

```bash
docker build -t registry.example.com/nextjs-app:latest -f docker/Dockerfile .
docker push registry.example.com/nextjs-app:latest
```

Set `container_image` to that reference before apply.

## Usage

1. Clone or copy this template directory
2. Copy `terraform.tfvars.example` to `terraform.tfvars` and fill in your values
3. Source your OpenStack credentials: `source openrc.sh`
4. Initialize: `tofu init`
5. Preview: `tofu plan`
6. Apply: `tofu apply`

After apply, open `app_url` from the outputs. For HTTPS, set `domain` and point its DNS A record at `floating_ip` before apply so Caddy can obtain a certificate.

## How the instance runs the app

cloud-init installs Docker, then runs two containers on a private Docker network:

- `app` runs your `container_image` with `PORT` set to `app_port` (default 3000), plus any `container_env` variables.
- `caddy` (Caddy) is the reverse proxy. With `domain` set it serves HTTPS with an automatic certificate; with `domain` empty it serves HTTP on `host_port`. It forwards traffic to the app container.

## Variables

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key_name` | string | yes | n/a | SSH keypair name (must already exist in your project) |
| `container_image` | string | no | `registry.example.com/nextjs-app:latest` | Prebuilt Next.js image to pull and run (replace with your own) |
| `flavor_name` | string | no | `s1a.small` | Instance size |
| `image_name` | string | no | `Ubuntu-24.04` | Operating system image |
| `app_name` | string | no | `nextjs-app` | Display name prefix for resources |
| `container_env` | map(string) | no | `{}` | Environment variables injected into the container at boot (names, not secret values) |
| `app_port` | number | no | `3000` | Port the Next.js server listens on inside the container |
| `host_port` | number | no | `80` | Public HTTP port the reverse proxy listens on |
| `domain` | string | no | `""` | Domain for automatic HTTPS; leave empty for HTTP only |
| `external_network` | string | no | `PublicStatic` | Persisted FIP / production default; override with `PublicEphemeral` for demos |
| `private_cidr` | string | no | `10.10.10.0/24` | CIDR for the private subnet |

## Outputs

| Name | Description |
| --- | --- |
| `floating_ip` | Public floating IP assigned to the instance |
| `private_ip` | Private IP address of the instance |
| `app_url` | HTTPS on the domain when set, otherwise HTTP on the floating IP and host port |
| `instance_id` | Compute instance ID |

## Environment variables and composition

`container_env` injects values into the container at boot. The launch handoff plan populates it from two sources: `quake.yaml` secret names (you supply the values) and the outputs of service templates applied earlier in the plan (for example a Postgres `DATABASE_URL`). Apply service templates first, read their outputs, then set `container_env` before applying this template.

For the POC, `container_env` values are passed as `docker run -e` flags and are visible in the instance process list and cloud-init logs. For production, source secrets from a secret store rather than the manifest.

## Scope

This is a single-VM origin, not a global edge deploy. There is no native CDN; bring a third-party CDN in front of the floating IP for static and ISR assets if you need edge caching.

## Documentation

See also: [Containerized app template](/resources/iac-templates/containerized-app)