Getting started

Services and local ports

The Music web app runs at http://localhost:4174; this API service runs at http://localhost:4175; the Ngamia API defaults to http://localhost:8080. Camel Accounts must accept the web app’s callback URL.

Component	Local URL	Purpose
Music web	`http://localhost:4174`	UI, PKCE creation, API calls
Music API	`http://localhost:4175`	OAuth exchange, session cookies, API proxy
Ngamia API	`http://localhost:8080`	Account, billing, music, and activity resources
Camel Accounts	`https://accounts.camelcreatives.com`	User sign-in and OAuth code issuance

1. Configure both applications

In api/.env.local, copy the API’s .env.example and set the local web origin:


PORT=4175
NGAMIA_API_BASE_URL=http://localhost:8080
CAMEL_ACCOUNTS_URL=https://accounts.camelcreatives.com
CAMEL_ACCOUNTS_CLIENT_ID=ngamia_web
CAMEL_ACCOUNTS_REDIRECT_URI=http://localhost:4174/auth/callback
ALLOWED_ORIGINS=http://localhost:4174

In web/.env.local, use matching public OAuth settings and API URL:


NEXT_PUBLIC_API_URL=http://localhost:4175
NEXT_PUBLIC_CAMEL_ACCOUNTS_URL=https://accounts.camelcreatives.com
NEXT_PUBLIC_CAMEL_ACCOUNTS_CLIENT_ID=ngamia_web
NEXT_PUBLIC_CAMEL_ACCOUNTS_REDIRECT_URI=http://localhost:4174/auth/callback

Register http://localhost:4174/auth/callback with Camel Accounts. The redirect URI must match exactly in the Camel client registration and both app configurations. The callback belongs to the web app, while the code exchange occurs server-side in the API.

2. Start each service

In separate terminals, run npm install && npm run dev from api/ and from web/. The NestJS API uses nest start --watch and binds port 4175 by default. Start the Ngamia API using its own setup instructions; this repository does not contain that service.

3. Check API health

Health does not require cookies or an allowed browser origin:


curl -i http://localhost:4175/api/health


{"service":"ngamia-music-api","status":"ok"}

Open http://localhost:4174/login. The web app creates a random PKCE verifier and OAuth state, stores both in sessionStorage, sends the SHA-256 challenge to Camel Accounts, and returns from /auth/callback with a code. The callback posts {code, code_verifier} to the API. On success, the API sets ngamia_music_access and ngamia_music_refresh cookies. The JSON response deliberately contains only { "ok": true }.

5. Check the signed-in session

The browser must send credentials and an allowed Origin:


curl -i http://localhost:4175/api/auth/session \
  -H 'Origin: http://localhost:4174' \
  --cookie 'ngamia_music_access=REDACTED; ngamia_music_refresh=REDACTED'

In real browser code, use fetch(url, { credentials: 'include' }). Do not copy production cookie values into terminal history, issue trackers, or logs.

6. Load models, then generate

First fetch GET /api/music/models and use a model identifier returned by the live catalog. Then send the validated generation body to POST /api/music/generate. See the generation workflow for a browser example, complete curl shape, binary response handling, and retry guidance.

Continue with authentication, API routes, or architecture.