Local Development — Cloud Backend

Prerequisites

Go 1.26+
SQL Server running locally (Docker recommended) or Azure SQL access
Flyway CLI (for migrations)

Setup

cd Backend
cp .env.example .env
# Edit .env with your values
go mod download

Environment variables

All variables are documented in Backend/.env.example. Key ones for local development:

Variable	Example value	Notes
`DATABASE_URL`	`sqlserver://sa:Pass@localhost:1433?database=monozu&encrypt=disable`	Local SQL Server
`SECRET_KEY`	`change-me-to-a-long-random-string`	Must be ≥32 chars in prod
`APP_ENV`	`development`	Enables ANSI log colors
`IS_DEV`	`true`	Forces SQL auth over Managed Identity
`PORT`	`8000`	API listen port
`APP_BASE_URL`	`http://localhost:3000`	Frontend SPA URL (for OAuth redirects)
`ALLOW_ORIGINS`	`http://localhost:3000,http://127.0.0.1:3000`	CORS allowed origins

Management integration (optional locally)

If testing the Management ↔ Cloud integration locally, also set:

Variable	Value
`CLOUD_INTERNAL_API_TOKEN`	Any string — must match Management’s value
`CLOUD_WEBHOOK_HMAC_SECRET`	Any 32+ char string — must match Management’s value
`MANAGEMENT_API_URL`	`http://localhost:8080`

Microsoft Entra ID (optional locally)

Only needed if testing SSO locally:

Variable	Value
`MS_CLIENT_ID`	App registration client ID
`MS_CLIENT_SECRET`	Client secret
`API_PUBLIC_URL`	`http://localhost:8000` (must match Entra redirect URI)

Run SQL Server locally (Docker)

docker run --name monozu-sql \
  -e ACCEPT_EULA=Y \
  -e SA_PASSWORD=YourStr0ngP@ss \
  -p 1433:1433 \
  -d mcr.microsoft.com/mssql/server:2022-latest

Run migrations

flyway \
  -url="jdbc:sqlserver://localhost:1433;databaseName=monozu;encrypt=false" \
  -user=sa \
  -password=YourStr0ngP@ss \
  -locations=filesystem:db/migration \
  migrate

Start the server

go run ./cmd/server
# API available at http://localhost:8000

Or build and run:

go build -o ./bin/server ./cmd/server
./bin/server

Run tests

go test ./...

Docker (full stack)

The Dockerfile is a multi-stage build (Go builder → Alpine runtime):

docker build -t monozu-backend .
docker run -p 8000:8000 --env-file .env monozu-backend

Common issues

Problem	Fix
`HTTP 431` on Entra ID redirect	Increase `HTTP_READ_BUFFER_BYTES=65536`
Refresh cookie not sent	Check `REFRESH_COOKIE_SAMESITE` — use `lax` or `none` for cross-origin, `strict` for same-origin
`tenant pending` on login	Activate the tenant via Management service first
SQL auth fails	Ensure `IS_DEV=true` is set when using `DATABASE_URL`