Backend Setup

This guide covers the essential setup steps for the Jubiloop backend.

Prerequisites

• Node.js 22+ 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

The backend uses environment variables for configuration. These are automatically generated from env.deploy.yml:

# For local development, .env files are created automatically
# when you run npm run dev

Key environment variables:

• PORT - Server port (default: 3333)
• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• APP_KEY - Application secret key
• SESSION_DRIVER - Session storage (redis)

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 project root
npm run db:seed

# Or from server directory
cd apps/server
node ace db:seed

4. Start the Server

# From project root (starts all services)
npm run dev

# Or just the backend
npm run dev:server

The API will be 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

Accessing the Database

# Via Docker
docker exec -it jubiloop_local_dev_postgres psql -U postgres -d jubiloop_dev_db

# Connection details for GUI tools
# Host: localhost
# Port: 5433
# Username: 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

1. Ensure Docker is running: docker ps
2. Check PostgreSQL container: docker logs jubiloop_local_dev_postgres
3. Verify DATABASE_URL in .env file
4. Try restarting Docker containers:

   cd infra/local_dev
   docker compose restart

Redis Connection Failed

1. Check Redis container: docker logs jubiloop_local_dev_redis
2. Verify REDIS_URL in .env file
3. Ensure Redis is running: docker exec -it jubiloop_local_dev_redis redis-cli ping

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