Deployment Overview¶
PackyTrace has an AWS demonstration deployment and a local Kubernetes reference deployment. The AWS application runs on one EC2 instance. The Kubernetes manifests are validated with kind but still require production ingress, secrets, backups, network policy and highly available data services before use on a managed cluster.
| Target | Status | Purpose |
|---|---|---|
| AWS | Deployed demonstration; last documented verification 2026-08-01 | Runs the public application without high availability or automated backups |
| Kubernetes on kind | Local reference, reproducible | Validates manifest rendering and local orchestration |
| Cloudflare Pages | Separate documentation deployment | Hosts this static documentation; verify status in the deployment workflow |
Application Deployment on AWS¶
The application uses a single-server infrastructure:
- Terraform creates the AWS network, compute, storage, security, and IAM resources.
- One Amazon Linux EC2 instance runs the complete container stack with Docker Compose.
- Caddy is the only public entry point. It provides HTTPS, serves the web applications, and forwards API requests to the gateway. We chose it because it automatically manages TLS certificates and combines static hosting and reverse proxying in a small configuration.
- An Elastic IP gives the server a stable public address, while an encrypted EBS volume keeps application data when the instance is replaced.
- AWS Systems Manager provides administrative access without opening SSH. Secrets and configuration are read from SSM Parameter Store.
- GitHub Actions builds versioned container images and publishes them to GHCR. The EC2 host pulls those images during deployment.
Inside the host, Docker Compose runs the eight services together with Postgres, Redpanda (using the Kafka protocol), Keycloak, Prometheus, Grafana, and the brand simulators. Only ports 80 and 443 are open to the internet; services and data stores stay on the private container network.
This single-server design was chosen to keep the demonstration affordable and easy to operate without changing the microservice, database ownership, authentication, or privacy boundaries. Its accepted limitation is that it is not highly available.
See AWS Application Deployment for deployment and operating commands.
Kubernetes reference deployment¶
Kubernetes is not the current AWS runtime. It is a working deployment path for the point at which one server is no longer enough. It is stored in deployment/k8s and uses:
- kind to run a reproducible Kubernetes cluster on a development machine;
- Kustomize with a shared base and a small kind overlay, so a future cloud overlay can change environment-specific settings without copying the whole deployment;
- Deployments and Services for the application services and brand simulators;
- StatefulSets and persistent volume claims for Postgres and Kafka;
- Jobs for one-time database and Kafka initialization;
- Ingress NGINX to route incoming traffic;
- liveness and readiness probes, resource requests and limits, non-root security contexts, and per-service database secrets;
- a Horizontal Pod Autoscaler that scales passport-service from one to five replicas when CPU use rises, plus two gateway replicas.
The manifests reuse the same database initialization, Keycloak realm, Prometheus rules, and Grafana dashboard files as Docker Compose. This avoids maintaining two versions of the same configuration.
Kubernetes can support failed-pod replacement, multiple replicas, rolling updates and workload distribution. CPU-based HPA configuration is a local mechanism, not evidence that scaling meets the scan SLO. Before using these manifests in production, the kind overlay and development secrets must be replaced with cloud-specific ingress, TLS, secret management, backups, and highly available data services.
See Kubernetes Deployment for the implementation and local commands.
Documentation Deployment¶
The documentation is built from Markdown with MkDocs Material. GitHub Actions validates it in strict mode and uploads the static site to Cloudflare Pages. Hosting it separately keeps documentation traffic and deployment concerns away from the AWS application.
See Cloudflare Docs Deployment for the publishing setup.