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.

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.

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	Fallback listener ARN for app routing rules. Keep this as the HTTP listener only if you are not using TLS yet.
ALB_HTTPS_LISTENER_ARN	Preferred listener ARN for app routing rules when ACM/TLS is enabled. Hatch will inject host rules here and keep deployment URLs on HTTPS.
DEPLOYMENT_URL_SCHEME	Public scheme used in deployment URLs and live logs (typically https in production).
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.

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_DEPLOYMENT_URL_SCHEME	Fallback scheme for older deployment records that only stored the hostname. Use https in production.
NEXT_PUBLIC_WS_URL	WebSocket endpoint for real-time log streaming (optional if using relative paths).

Never commit .env files 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_SECRET and GITHUB_CLIENT_SECRET regularly to minimize exposure.