First-time Setup¶

Purpose¶

Go from a fresh git clone to a working local stack - either Docker Compose (app development) or the full k3d/K3s + Helm stack (infrastructure work).

Prerequisites¶

Everything in Prerequisites installed and verified.

Path A: Docker Compose (most common)¶

git clone https://github.com/Thirunk/AkshayaBazaar.git
cd AkshayaBazaar
copy .env.example .env
# edit .env if you want real notification/payment provider credentials - safe to leave
# every value at its default (Simulated providers, no real secrets required to run)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Frontend (hot reload): http://localhost:3000
Backend API directly: http://localhost:5000
MySQL: localhost:3309 (matches docker-compose.yml's MYSQL_HOST_PORT default)

Full detail: Docker.

Path B: local k3d/K3s + Helm¶

1. Create the cluster (if it doesn't already exist)¶

k3d cluster create akshaya-staging `
  --api-port 6550 `
  -p "80:80@loadbalancer" `
  -p "443:443@loadbalancer" `
  --agents 1

Full detail on why both port 80 and an alternate port matter here: Kubernetes → k3d.

2. hosts file¶

127.0.0.1 staging.akshaya.local

Requires an elevated Administrator PowerShell - this portal never edits the hosts file for you:

# Run PowerShell "as Administrator" first, then:
Add-Content -Path "$env:SystemRoot\System32\drivers\etc\hosts" -Value "127.0.0.1 staging.akshaya.local"

Verify:

Get-Content "$env:SystemRoot\System32\drivers\etc\hosts" | Select-String "staging.akshaya.local"

3. Namespace-local MySQL/Redis¶

The local cluster's MySQL/Redis run as ordinary pods in the staging namespace (not part of the Helm chart - the chart assumes an externally-provisioned database, which the real staging/ production clusters have via Terraform, but local doesn't). Apply your own manifests for these (not committed to this repository - see helm/akshayabazaar/examples/secret.example.yaml for the shape of the connection details the backend Secret needs to match).

4. Backend/frontend Secret¶

kubectl create namespace staging
kubectl apply -n staging -f path\to\your\akshayabazaar-local-secrets.yaml

This repository never creates this Secret for you on purpose - see Kubernetes → Helm.

5. Build and deploy¶

.\scripts\build.ps1 -Local
.\scripts\deploy-local.ps1

6. Verify¶

.\scripts\verify-staging.ps1 `
  -Context k3d-akshaya-staging `
  -Namespace staging `
  -ReleaseName akshaya-local `
  -IngressHost staging.akshaya.local `
  -IngressPort 80

Expected result: Summary: 14 PASS, 0 WARNING, 0 FAIL.

MkDocs environment (this portal)¶

cd D:\Projects\AkshayaBazaar
python -m venv .venv-docs
.\.venv-docs\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements-docs.txt
mkdocs serve

Then open http://127.0.0.1:8000. Full detail: this repository's root mkdocs.yml and requirements-docs.txt.

Validation¶

Path	Command	Expected
Docker Compose	`docker compose ps`	`api`, `frontend`, `mysql`, `redis` all `healthy`
k3d/Helm	`.\scripts\verify-staging.ps1 ...` (above)	`14 PASS, 0 WARNING, 0 FAIL`
MkDocs	`mkdocs build --strict`	exits 0, no warnings

If something goes wrong¶

See Troubleshooting.