Installation

This guide covers both Docker-based installation (recommended) and manual setup for the Los Inmaduros Backend API.

Prerequisites

Choose your installation method and ensure you have the required prerequisites:

Docker (Recommended)
Manual Setup

Docker Desktop - Install Docker Desktop
Git - For cloning the repository
Clerk Account - Sign up at clerk.com
Supabase Account - Sign up at supabase.com

Docker is the recommended approach as it handles all dependencies and database setup automatically.

Installation Methods

Docker Installation
Manual Installation

Quick Start with Docker

Docker is the easiest way to run the project. Everything is configured automatically.

Clone the repository

git clone https://github.com/Adriasu09/los-inmaduros-backend.git
cd los-inmaduros-backend

Create .env file

Copy the example environment file:

cp .env.example .env

Edit .env and add your Clerk and Supabase credentials:

# Clerk Authentication
CLERK_SECRET_KEY=your_clerk_secret_key
CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key

# Supabase Storage
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key

Other variables like DATABASE_URL and PORT are pre-configured for Docker.

Start with Docker Compose

Launch the entire stack:

npm run docker:dev

Or use Docker Compose directly:

docker-compose up --build

Docker will automatically:

✅ Set up PostgreSQL database
✅ Run Prisma migrations
✅ Install dependencies
✅ Start the server with hot reload

Verify installation

Your API is now running at:

Backend: http://localhost:4000
API Docs: http://localhost:4000/api-docs
PostgreSQL: localhost:5432

Test the health endpoint:

curl http://localhost:4000/health

Docker Management Commands

# Stop containers
npm run docker:dev:down

# View logs
npm run docker:logs

# Rebuild from scratch
docker-compose down -v && docker-compose up --build

# Stop and remove everything (including volumes)
docker-compose down -v

# Production mode
npm run docker:prod

Manual Setup Without Docker

If you prefer to run without Docker, follow these steps:

Clone the repository

git clone https://github.com/Adriasu09/los-inmaduros-backend.git
cd los-inmaduros-backend

Install dependencies

npm install

This will install all required packages including Express, Prisma, TypeScript, and more.

Configure environment variables

Create a .env file in the root directory:

# Server
PORT=4000
NODE_ENV=development

# Frontend URL (CORS)
FRONTEND_URL=http://localhost:3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/los_inmaduros

# Supabase Storage
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_anon_key_here

# Clerk Authentication
CLERK_SECRET_KEY=sk_test_your_secret_key
CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key

Make sure to replace all placeholder values with your actual credentials.

See the Environment Variables page for detailed descriptions of each variable.

Set up PostgreSQL database

Create a PostgreSQL database:

# Using psql
createdb los_inmaduros

# Or using PostgreSQL client
psql -U postgres
CREATE DATABASE los_inmaduros;

Make sure your DATABASE_URL in .env matches your database credentials.

Run Prisma migrations

Set up the database schema:

npx prisma migrate dev

This will:

Create all required tables
Set up relationships
Generate the Prisma Client

Start development server

npm run dev

The server will start at http://localhost:4000 🚀

Verify installation

Test the API:

curl http://localhost:4000/health

Visit the interactive documentation: http://localhost:4000/api-docs

Development Scripts

# Development with hot reload
npm run dev

# Compile TypeScript
npm run build

# Run in production
npm start

# Run tests with coverage
npm test

# Run tests in watch mode
npm run test:watch

# Open Prisma Studio (database GUI)
npx prisma studio

# Generate Prisma client
npx prisma generate

Environment Variables Setup

The API requires several environment variables to function properly. Here’s a comprehensive overview:

Required Variables

Variable	Description	Example
`CLERK_SECRET_KEY`	Clerk secret key for authentication	`sk_test_...`
`CLERK_PUBLISHABLE_KEY`	Clerk publishable key	`pk_test_...`
`SUPABASE_URL`	Supabase project URL	`https://xxx.supabase.co`
`SUPABASE_ANON_KEY`	Supabase anonymous key	`eyJhbG...`
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@localhost:5432/db`

Optional Variables

Variable	Description	Default
`PORT`	Server port	`4000`
`NODE_ENV`	Environment mode	`development`
`FRONTEND_URL`	Frontend URL for CORS	`http://localhost:3000`

For detailed information about each environment variable, see the Environment Variables page.

Database Setup

The API uses Prisma as an ORM with PostgreSQL.

With Docker

Docker automatically sets up PostgreSQL with these credentials:

Host: db (internal) / localhost (external)
Port: 5432
User: postgres
Password: postgres
Database: los_inmaduros

Manual Setup

You’ll need to:

Install PostgreSQL 14 or higher
Create a database named los_inmaduros (or your preferred name)
Update DATABASE_URL in your .env file
Run migrations: npx prisma migrate dev

Useful Prisma Commands

# Run migrations
npx prisma migrate dev

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

# Open Prisma Studio (database GUI)
npx prisma studio

# Generate Prisma client
npx prisma generate

# Create a new migration
npx prisma migrate dev --name migration_name

Verification

Health Check

Verify the server is running:

curl http://localhost:4000/health

Expected response:

{
  "status": "OK",
  "message": "Los Inmaduros Backend is running! 🛼",
  "timestamp": "2026-03-04T10:30:00.000Z",
  "database": "Connected ✅"
}

Test API Endpoints

Get all routes:

curl http://localhost:4000/api/routes

Access Swagger Documentation

Open your browser and visit: http://localhost:4000/api-docs This provides an interactive interface to test all endpoints.

Troubleshooting

Database connection errors

Symptoms: “Database connection failed” or Prisma errorsSolutions:

Verify PostgreSQL is running
Check DATABASE_URL is correct in .env
Ensure the database exists: psql -l
Run migrations: npx prisma migrate dev
For Docker: docker-compose logs db

Port already in use

Symptoms: “Port 4000 is already in use”Solutions:

Change PORT in .env to a different value (e.g., 4001)
Kill the process using port 4000: lsof -ti:4000 | xargs kill -9
For Docker: Update port mapping in docker-compose.yml

Clerk authentication errors

Symptoms: 401 errors or “Invalid Clerk token”Solutions:

Verify CLERK_SECRET_KEY and CLERK_PUBLISHABLE_KEY are correct
Ensure both keys are from the same Clerk application
Check your Clerk dashboard for the correct keys
Make sure keys are properly formatted (no extra spaces)

Supabase storage errors

Symptoms: Photo upload fails or storage errorsSolutions:

Verify SUPABASE_URL and SUPABASE_ANON_KEY are correct
Check your Supabase project is active
Ensure storage bucket is created in Supabase dashboard
Verify bucket permissions allow public uploads

TypeScript compilation errors

Symptoms: Build fails with type errorsSolutions:

Run npm install to ensure all dependencies are installed
Delete node_modules and package-lock.json, then npm install again
Run npx prisma generate to regenerate Prisma client
Check TypeScript version matches package.json (5.6)

Next Steps

Quickstart Guide

Quick overview of getting started

Environment Variables

Detailed configuration reference

API Reference

Explore all available endpoints

Authentication

Learn about Clerk authentication

Get Started

Core Concepts

Deployment

Installation

Installation

Prerequisites

Installation Methods

Quick Start with Docker

Docker Management Commands

Manual Setup Without Docker

Development Scripts

Environment Variables Setup

Required Variables

Optional Variables

Database Setup

With Docker

Manual Setup

Useful Prisma Commands

Verification

Health Check

Test API Endpoints

Access Swagger Documentation

Troubleshooting

Next Steps

Quickstart Guide

Environment Variables

API Reference

Authentication

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

​Installation

​Prerequisites

​Installation Methods

​Quick Start with Docker

​Docker Management Commands

​Manual Setup Without Docker

​Development Scripts

​Environment Variables Setup

​Required Variables

​Optional Variables

​Database Setup

​With Docker

​Manual Setup

​Useful Prisma Commands

​Verification

​Health Check

​Test API Endpoints

​Access Swagger Documentation

​Troubleshooting

​Next Steps

Quickstart Guide

Environment Variables

API Reference

Authentication

Build docs developers (and LLMs) love

Installation

Prerequisites

Installation Methods

Quick Start with Docker

Docker Management Commands

Manual Setup Without Docker

Development Scripts

Environment Variables Setup

Required Variables

Optional Variables

Database Setup

With Docker

Manual Setup

Useful Prisma Commands

Verification

Health Check

Test API Endpoints

Access Swagger Documentation

Troubleshooting

Next Steps