Configuration/Env Variables
Environment Variables
Comprehensive reference for configuring Hatch microservices. Each service requires specific keys to communicate with AWS, RabbitMQ, and Redis.
GLOBAL SCHEMA SECRETS REQUIRED MONOREPO SCOPED
API Gateway
Handles authentication, project management, and job publishing.
| Variable | Description |
|---|---|
| PORT | Internal port the Gin server listens on (default: 8080). |
| GITHUB_CLIENT_ID | OAuth application client ID from GitHub Developer settings. |
| GITHUB_CLIENT_SECRET | OAuth application secret for exchanging codes for tokens. |
| JWT_SECRET | High-entropy string used to sign session tokens. |
| DATABASE_URL | PostgreSQL connection string (e.g., postgres://user:pass@host:5432/db). |
| RABBITMQ_URL | Connection string for the message broker. |
| REDIS_URL | Connection string for log persistence and real-time streams. |
Builder Worker
Orchestrates git cloning, Docker builds, and ECR pushing.
| Variable | Description |
|---|---|
| AWS_REGION | The AWS region where ECR repositories are located. |
| ECR_REGISTRY | Full URI of your private ECR registry (e.g., <id>.dkr.ecr.<region>.amazonaws.com). |
| ECR_REPOSITORY | Base name for storing build artifacts (default: hatch-builds). |
| REDIS_URL | Shared with API for streaming build logs back to the dashboard. |
| RABBITMQ_URL | Shared with API to consume BuildJob events. |
Deployer Worker
Provisions and updates ECS Fargate tasks and ALB routing rules.
| Variable | Description |
|---|---|
| ECS_CLUSTER_NAME | The name of the cluster provisioned via Terraform. |
| ALB_LISTENER_ARN | ARN of the ALB listener where rules will be injected. |
| VPC_ID | The ID of the target VPC for task networking. |
| SUBNET_A / SUBNET_B | Private subnets where Fargate tasks will be launched. |
| TASK_EXECUTION_ROLE_ARN | IAM Role providing task permissions to ECR and CloudWatch. |
Web Frontend
Next.js application providing the control plane UI.
| Variable | Description |
|---|---|
| NEXT_PUBLIC_API_URL | Public URL of the API Gateway (used for client-side fetches). |
| NEXT_PUBLIC_WS_URL | WebSocket endpoint for real-time log streaming (optional if using relative paths). |
Security Best Practices
- Never commit
.envfiles to source control. They are ignored by default via the root.gitignore. - In production, prefer using AWS Secrets Manager or Parameter Store instead of raw environment variables where possible.
- Rotate your
JWT_SECRETandGITHUB_CLIENT_SECRETregularly to minimize exposure.