Skip to content

Developer Onboarding

This guide describes the standard MazeVault Core developer workflow.

It covers:

  • branch rules
  • local Docker-first development
  • optional frontend-only debug mode
  • pre-push checks
  • CLA signing
  • GitHub Actions flow

Branching Rules

MazeVault Core development is anchored on dev.

Use these rules:

  • Start feature work from dev
  • Create a feature/* branch from dev
  • Open your pull request back to dev
  • Do not do normal feature work on main
  • Do not do normal feature work on staging
  • Do not do normal feature work on production

Recommended flow:

git clone git@github.com:MazeVault/maze-core.git
cd maze-core
git checkout dev
git pull origin dev
git checkout -b feature/<short-description>

Prerequisites

Install these tools before starting:

  • Docker with Docker Compose
  • Git
  • Go 1.26.x
  • Node.js with npm

Standard Local Development

The standard local workflow is Docker-first.

Start the full stack with:

docker compose -f docker-compose.yml up --build

This brings up the local application stack including:

  • client-postgres
  • client-redis
  • client-backend
  • client-frontend
  • client-ocsp-responder

Local Endpoints

  • Frontend: http://localhost:5173
  • Backend HTTP: http://localhost:8080
  • Backend HTTPS: https://localhost:8443
  • OCSP responder: http://localhost:8081/health

Basic Health Checks

curl -k https://localhost:8443/api/v1/health
curl http://localhost:8081/health

Runtime Debugging

Use Docker logs as the primary runtime inspection tool:

docker compose logs -f client-backend client-frontend client-ocsp-responder

Restart only the service you changed when possible:

docker compose restart client-backend
docker compose restart client-frontend
docker compose restart client-ocsp-responder

Optional Frontend-Only Debug Mode

Use this only when you explicitly want Vite hot reload outside Docker.

This is not the default team workflow.

First stop the frontend container:

docker compose stop client-frontend

Then run the frontend locally:

cd frontend
npm install
npm run dev

When you are done, you can return to the standard workflow by stopping the local Vite process and starting the container again:

docker compose start client-frontend

Local Checks Before Push

Run the minimum validation before pushing your branch:

cd backend && go test ./...
cd ../frontend && npm install && npm run build && npm test -- --run

If you changed containerized behavior, also recheck the running stack:

docker compose -f docker-compose.yml up --build
curl -k https://localhost:8443/api/v1/health

CLA Step By Step

First-time contributors must complete the Contributor License Agreement flow.

1. Open a pull request to dev

The CLA check is tied to the pull request workflow.

2. Wait for the CLA Assistant status check

The check appears automatically after PR open or PR update.

3. If CLA is missing, read the CLA document

https://github.com/MazeVault/.github/blob/main/CLA.md

4. Add this exact comment to the PR

I have read the CLA Document and I hereby sign the CLA

5. Wait for CLA Assistant to pass

If it does not rerun automatically, comment:

recheck

6. Continue only after the CLA check is green

Do not request merge while CLA Assistant is failing.

GitHub Actions Flow

Pull Request Flow

When you open a PR to dev, the repository runs pull request checks, including:

  • CLA validation
  • PR validation

Push To dev

When changes land on dev, the ci-dev.yml pipeline runs:

  1. backend build and tests
  2. frontend build and tests
  3. Trivy scanning
  4. Azure Container Registry push
  5. AKS gateway deployment
  6. promotion toward staging

staging

staging is for higher-level deployment verification and production promotion.

It is not a normal developer working branch.

production

production is the release branch.

It is not a normal developer working branch.

Release tags vX.Y.Z are created from production only.

main

main is a sync target from production.

It is not a normal developer working branch.

Practical Summary

  • Work from dev
  • Create feature/* branches from dev
  • Use docker compose -f docker-compose.yml up --build as the normal local workflow
  • Use local npm run dev only as an explicit frontend-only debug mode
  • Open PRs back to dev
  • Complete CLA before merge