Onboarding¶
Everything a new engineer needs to get up and running with CookieHub infrastructure and development.
Accounts & Access¶
You'll need access to the following. Ask the team lead to set these up:
| Service | What you need |
|---|---|
| GitHub | Added to cookiehub-com org with write access to relevant repos |
| AWS (both accounts) | Membership of the sec-infra Entra group. AWS access is IAM Identity Center federated to Entra ID — there are no personal IAM users or access keys |
| VPN | Membership of sec-infra, sec-devop-{env} or sec-data-{env}; sign in with your Microsoft account — see VPN Access runbook |
| Cloudflare | Added to CookieHub org account |
| Vercel | Added to CookieHub team |
Tooling¶
Install these on your machine:
| Tool | Purpose | Install |
|---|---|---|
| Node.js 24+ | Core API, Atrax | brew install node or nvm |
| Docker | Local databases, containers | Docker Desktop |
| AWS CLI v2 | AWS access | brew install awscli |
| Session Manager plugin | SSM tunneling | AWS docs |
| Terraform | Infrastructure changes | brew install terraform |
| MariaDB client | Database access | brew install mariadb |
| Python 3 | Docs site (MkDocs) | Pre-installed on macOS |
| MkDocs Material | Build docs locally | pip install mkdocs-material |
AWS CLI Setup¶
Access uses SSO, not access keys. Add the two SSO profiles from the
infra README to ~/.aws/config (cookiehub-stage and
cookiehub-prod, account IDs 258618559895 and 759286286879), then sign in:
aws sso login --profile cookiehub-stage # opens the Entra login in a browser; sessions last 8 hours
export AWS_PROFILE=cookiehub-stage # or cookiehub-prod
aws sts get-caller-identity # verify
Never put anything in ~/.aws/credentials for these accounts. The infra repo also ships .envrc files
(direnv) that select the profile per environment and refuse to run against the wrong account.
Repositories¶
You'll get access to the repos relevant to your work. Key repos include:
| Repo | Purpose | Local setup |
|---|---|---|
core-api |
Client API (TypeScript rewrite) | See below |
core |
Laravel monolith — production dashboard and API | PHP/Laravel setup (ask team for instructions) |
admin |
Staff admin portal (Next.js port of core's /cha) |
See the repo README — needs a DATABASE_URL for a core database |
vault-api |
Analytics API | npm install && npm run dev |
widget |
Consent banner (client-side JS) | npm install && npm run dev |
infra |
Terraform infrastructure | cd environments/stage/eu-central-1 && terraform init |
docs-internal |
This docs site | pip install -r requirements.txt && mkdocs serve |
Core API Local Setup¶
git clone git@github.com:cookiehub-com/core-api.git
cd core-api
cp .env.example .env
docker compose up -d mysql
./scripts/seed-dev.sh
npm install
npm run dev
Database dump required
The seed script loads a database dump from .cookiehub/core_dev_build.sql which is not
checked into git (~115MB). Ask a teammate for a copy and place it in the .cookiehub/
directory before running seed-dev.sh.
- API: http://localhost:3000/client/v3
- Docs: http://localhost:3000/client/v3/docs
- Health: http://localhost:3000/client/health
Connecting to Stage Services¶
Most stage services are behind the public ALB and accessible without VPN:
| Service | URL |
|---|---|
| Core API | https://core-api.stage.cookiehub.net |
| Core API docs | https://core-api.stage.cookiehub.net/client/v3/docs |
| Atrax API | https://atrax-api.stage.cookiehub.net |
For internal services (databases, internal ALB), connect to the VPN first — see VPN Access.
For production ClickHouse and Grafana, use SSM port forwarding — see Port Forwarding.
Key Documentation¶
Start with these pages to understand the system:
- Architecture Overview — system diagram and service summary
- Service Topology — how services connect
- Terraform — how infrastructure is managed
- Secrets — where secrets live and how to manage them
- Deployments — how to deploy and roll back
Common First Tasks¶
- Run core-api locally and hit a few endpoints via the Scalar docs UI
- Connect to the VPN and verify you can reach internal services
- Read a CloudWatch log —
aws logs tail /ecs/stage-euc1-core-core-api --follow --region eu-central-1 - Run
terraform planon the stage environment to see the current state