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 (stage)	IAM user in account 258618559895 (eu-central-1)
AWS (prod)	IAM user in account 759286286879 (read-only to start)
VPN	Client certificate — 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

Configure named profiles for each account:

aws configure --profile stage
# AWS Access Key ID: (from your IAM user)
# AWS Secret Access Key: (from your IAM user)
# Default region: eu-central-1
# Default output: json

aws configure --profile prod
# Same pattern for production

Set your default profile:

export AWS_PROFILE=stage

Add this to your ~/.zshrc to persist it.

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)
vault-api	Analytics API	npm install && npm run dev
widget	Consent banner (client-side JS)	npm install && npm run dev
infra	Terraform infrastructure	cd live/stage/eu-central-1 && terraform init
docs-internal	This docs site	npm install && npm run dev

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