Deployment and troubleshooting
Run commands
From the API project root (api/ in the Ngamia Music repository):
npm install
npm run build
npm run startThe Nest CLI compiles src/ to dist/; npm start runs node dist/main.js. The server binds to 0.0.0.0 and uses PORT or defaults to 4175. Configure a platform health probe to GET /api/health. Camel OAuth token exchange allows 20 seconds per upstream request, session/model reads 15 seconds, logout 10 seconds, and generation/authenticated proxy calls up to 280 seconds. Confirm your hosting platform allows long-running Node.js requests of that duration; if its hard timeout is shorter, generation may terminate before the handler can return its timeout JSON.
The docs site itself runs independently from the API. It is a Next.js/Nextra app, does not call the API, and needs no credentials.
Common symptoms
| Symptom | Check |
|---|---|
403 “origin not allowed” | Browser Origin must exactly match an ALLOWED_ORIGINS entry, including scheme and port. |
401 from session/models/generate | Sign in again; inspect whether cookies are sent; check Ngamia token exchange and refresh availability. |
| OAuth code exchange fails | Compare client ID and redirect URI in the web app, API, and Camel registration; check PKCE verifier/state flow. |
| Session route says unauthenticated | Browser request needs credentials: 'include'; verify cookie domain/same-site deployment. |
| Model list is empty/fails | Check upstream /v1/models response and that the signed-in account has eligible models. |
Generation returns 502 timeout | Check Ngamia activity and creations before retrying to avoid duplicates. |
| Generation route hangs then platform disconnects | Compare the platform’s request timeout with the API’s 280-second upstream timeout. |
| Share link cannot load audio | Check is_public, creation ID, and upstream public metadata/content response. |
| Browser cannot read a response header | Only selected headers are exposed by CORS; generation IDs are exposed. |
| Nest build succeeds but startup fails | Confirm deployment ran npm run build and contains dist/main.js. |
Logging and secrets
The source does not emit structured request logs or define a request ID. Do not log authorization codes, PKCE verifiers, access/refresh tokens, or cookie headers. Add correlation at your hosting boundary if needed, while redacting credentials and prompt text according to your privacy policy.