Backend Setup

This guide covers the essential setup steps for the Jubiloop backend when running in host-mode (infrastructure in Docker, applications on your machine).

For the recommended Docker Stack workflow where everything runs in Docker, see Local Development Setup.

Prerequisites

• Node.js 24+ installed
• Docker running (for local PostgreSQL and Redis)
• Access to the monorepo

Initial Setup

1. Install Dependencies

From the project root:

npm install

2. Environment Configuration

Copy the example environment file:

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

Then fill in the required values in apps/server/.env:

Variable	How to get it
APP_KEY	cd apps/server && node ace generate:key
BETTER_AUTH_SECRET	cd apps/server && node ace generate:key
HEALTH_SECRET	cd apps/server && node ace generate:key
REDIS_PASSWORD	From 1Password vault
RESEND_API_KEY	From 1Password vault
BREVO_API_KEY	From 1Password vault

Docker Stack overrides

If you use the Docker Stack, DB_HOST and REDIS_HOST are automatically overridden to the container names. You only need to set the secret values above.

3. Database Setup

Run Migrations

# From project root
npm run migration:run

# Or from server directory
cd apps/server
node ace migration:run

Seed Database (Optional)

For development, you can seed the database with sample data:

# From server directory
cd apps/server
node ace db:seed

4. Start the Server

Recommended: use the Docker Stack

npm run dev:stack:up

API available at: https://api.jubiloop.localhost

See Local Development Setup for the full guide.

Alternative: run on host (infra-only mode)

Requires infrastructure services to be running first:

cd infra/local_dev && docker compose -f docker-compose.infra.yml up -d

Then start the server:

# From project root
npm run dev -- --filter=server

# Or from server directory
cd apps/server
node ace serve --hmr

Available at: http://localhost:3333

Common Tasks

Creating a New Migration

cd apps/server
node ace make:migration create_table_name

Rolling Back Migrations

cd apps/server
node ace migration:rollback

Forbidden

migration:rollback --batch=0 drops every table in the database. It is explicitly prohibited. Use migration:fresh to reset locally.

Accessing the Database

Docker Stack:

docker exec -it jubiloop_dev_postgres psql -U postgres -d jubiloop_dev_db

Infra-only mode:

docker exec -it jubiloop_local_dev_postgres psql -U postgres -d jubiloop_dev_db

GUI tools (both modes): localhost:5433, user: postgres, password: postgres, database: jubiloop_dev_db

Checking Server Health

curl http://localhost:3333/health

Troubleshooting

Port Already in Use

If port 3333 is already in use:

1. Check what's using it: lsof -i :3333
2. Change the port in your .env file
3. Restart the server

Database Connection Failed

Docker Stack:

docker logs jubiloop_dev_postgres

Infra-only:

docker logs jubiloop_local_dev_postgres

Verify DB_HOST=localhost and DB_PORT=5433 in your .env file.

Redis Connection Failed

Docker Stack: docker logs jubiloop_dev_redis

Infra-only: docker logs jubiloop_local_dev_redis

Verify REDIS_HOST=localhost and REDIS_PORT=6379 in your .env file.

Next Steps

• Review AdonisJS Commands for CLI reference
• Check Controllers & Routing for API development
• See Data Models for database schema
• Read API Reference for endpoint documentation