Skip to content

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:

  1. Architecture Overview — system diagram and service summary
  2. Service Topology — how services connect
  3. Terraform — how infrastructure is managed
  4. Secrets — where secrets live and how to manage them
  5. 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 plan on the stage environment to see the current state