HTTPS and the Caddy edge

Part 3 shipped KitePDF on a single EC2 host behind nginx on port 80, with browsers talking to a raw public IP. That shape proved the product on real AWS. This part covers what we changed next: a real domain, HTTPS, and Caddy as the production edge—plus the URL, CORS, and auth alignment work that a domain forces into the open.

Read it as a learning note, not marketing: what we tried, why Caddy won for ACME, how Terraform still owns AWS shape (we do not click through the console to stand up buckets or security groups), and the exact order of operations when DNS, GitHub secrets, terraform apply, and workflow_dispatch all have to line up.

The application plane did not grow. We still run one Amazon Linux 2023 instance, Docker Compose, Neon for both Postgres databases, S3 for bytes, SQS for jobs, and SSM for secrets. The changes sit at the edge and in every place that embeds a public origin.

HTTPS and Caddy sit on top of the same Terraform stack Part 3 documents under infra/aws. Your IAM user runs terraform init, plan, and apply locally (or in CI later)—that creates the S3 bucket with CORS wired to the EC2 public IP, SQS queues, SSM parameters under ssm_base_path, CloudWatch log group, security group (SSH + HTTP/HTTPS), and the EC2 instance with an instance profile. We do not recreate those resources in the AWS console; the console is for reading state when debugging, not for provisioning.

We evaluated keeping nginx and adding TLS the conventional way: obtain certificates, drop fullchain.pem and privkey.pem under nginx/certs/, switch the mount from localstack.conf to aws.conf, open 443 on the security group, and schedule renewals. That path works—nginx/aws.conf already names kitepdf.pro—but it optimizes for operators who want explicit control of every PEM file.

Caddy optimizes for the opposite: automatic HTTPS as a default. Point DNS at the instance, set SITE_HOST and ACME_EMAIL, publish 80 and 443, and Caddy obtains and renews certificates. For a single-host product where the edge's job is reverse proxy plus TLS—not complex Lua or multi-tenant vhosts—that is the right trade.

Routing did not change philosophy. The browser still hits one public entrypoint. Caddy terminates TLS, then splits traffic the same way nginx/localstack.conf and caddy/Caddyfile.local did: product UI on /, PDF API on /core/v1/*, probes and docs on explicit /core/* paths. Workers never see browser cookies; they stay on the internal Compose network and authenticate to the gateway with INTERNAL_SECRET from SSM.

Caddyfile.prod mirrors caddy/Caddyfile.local on purpose: parity between IP bootstrap and HTTPS production. SITE_HOST and ACME_EMAIL come from Compose environment substitution. The apex block owns HSTS, explicit handles for health and docs, the API reverse_proxy with hour-long read/write timeouts and flush_interval -1 for streaming responses, and a default handle to frontend:3000.

A domain is not a DNS A record alone. Auth cookies, JWT issuer and audience, NEXT_PUBLIC_* bake-time values, Better Auth base URL, and S3 CORS must all agree on the same origin. Treat promotion as one change set—not a sequence of half-updated environments.

The repo keeps a small matrix so you can bootstrap by IP and promote to TLS without inventing a new stack. Application services are identical across Caddy compose files; only the edge service and published ports differ.

The blessed path for the domain stack is the Deploy AWS (Caddy) GitHub Actions workflow. It is the last step in a chain—not a standalone button. Terraform must have created the host and SSM path; EC2_HOST and SSH secrets must match terraform output ec2_public_ip; NEXT_PUBLIC_* and auth URLs must already reflect the origin you want baked into the frontend image. The workflow builds four :prod-amd64 images, pushes to Docker Hub, rsyncs compose + Caddyfiles + generated .env.prod.aws to the instance, stops any competing edge stack, and runs compose pull && up -d.

Promotion is sequential. Skipping a step or running them out of order produces the confusing failures in the lessons table—login on HTTPS with JWT issuer still on http://IP, ACME failures with DNS still on the old host, or CORS allowing the domain while the frontend image still bakes the EC2 IP. Follow the order below even if you already ran Part 3 once; refresh Terraform outputs before you trust old secrets.

HTTPS and a domain closed the largest gap called out in Part 3. We still have not added an Elastic IP, remote Terraform state, autoscaled workers, or a second AWS environment for staging. The host remains a single blast radius; queues are still the intended scale-out point for PDF work.

Revisit Part 3 for the full Terraform module, SSM layout, and Neon migration workflow. Revisit Part 2 when JWT validation fails across environments—issuer, audience, and JWKS URL mistakes look the same on HTTPS as they did on HTTP. Future parts can cover local fidelity (prod-localstack with Caddy) and horizontal scaling once the public edge is no longer the unstable variable.