Backend Setup

This guide starts only the backend application on the host while PostgreSQL, Redis, and Caddy run in Docker. The recommended day-to-day workflow is the full Docker Stack.

Complete the repository prerequisites, dependency installation, and HTTPS setup in that guide before continuing. Database ports, credentials, and service troubleshooting also live in the host-mode infrastructure guide.

Configure The Server

From the repository root, create the server environment file:

cp apps/server/.env.example apps/server/.env

apps/server/start/env.ts is the source of truth for required variables. In the copied local example, fill these blank values before starting the server:

• APP_KEY, BETTER_AUTH_SECRET, and HEALTH_SECRET: generate a separate value for each by running node ace generate:key from apps/server.
• RESEND_API_KEY and BREVO_API_KEY: retrieve the development credentials from the team's secret manager.

Keep the host-mode database and Redis settings from .env.example. APP_ENV controls Jubiloop behavior and is separate from NODE_ENV. Don't put secret values in documentation or commit apps/server/.env.

Start Infrastructure

Start the infra-only services from the repository root:

pnpm run dev:infra:up
pnpm run dev:infra:status

The status command should report PostgreSQL, Redis, and Caddy as running. For service details and diagnostics, use Host-Mode Development and Troubleshooting.

Prepare The Database

Apply pending migrations from the repository root:

pnpm run migration:run

Seeding is optional:

pnpm run db:seed

See Database Development before changing schema or migration history.

Start The Server

From the repository root:

pnpm run dev -- --filter=server

Or run Ace directly:

cd apps/server
node ace serve --hmr

The host endpoint is http://localhost:3333. Caddy also exposes it at https://api.jubiloop.localhost while the infra-only stack is running.

Verify The Server

Check the public health response:

curl http://localhost:3333/health

A healthy response reports isHealthy: true. The full health report requires the monitoring secret and shouldn't be pasted into logs or documentation.

Next, use Backend Ace Commands for project commands and Controllers And Routing for API implementation.