Skip to main content

​
Quickstart

Get the Los Inmaduros Backend API up and running in just a few minutes using Docker. This is the fastest way to start developing with the API.

​
Prerequisites

Before you begin, make sure you have:

​
Quick Start Steps

1

Clone the repository

First, clone the repository and navigate into the project directory:
git clone https://github.com/Adriasu09/los-inmaduros-backend.git
cd los-inmaduros-backend
2

Configure environment variables

Copy the example environment file and add your credentials:
cp .env.example .env
Edit the .env file 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
The other environment variables have sensible defaults for Docker development. See the Environment Variables page for details.
3

Start with Docker Compose

Launch the entire stack with a single command:
npm run docker:dev
Or use Docker Compose directly:
docker-compose up --build
Docker will automatically:
  • ✅ Set up a PostgreSQL database
  • ✅ Run Prisma migrations
  • ✅ Install all dependencies
  • ✅ Start the server with hot reload
4

Access the API

That’s it! Your API is now running:
The Swagger documentation at /api-docs provides an interactive interface to explore and test all API endpoints.

​
Test the API

Verify everything is working by making a test request:

​
Health Check

Check if the server and database are 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 ✅"
}

​
Get All Routes

Fetch the list of skating routes: 
curl http://localhost:4000/api/routes
Expected Response: 
{
  "success": true,
  "data": [
    {
      "id": "uuid-here",
      "name": "Madrid Río Loop",
      "slug": "madrid-rio-loop",
      "difficulty": "intermediate",
      "distance": 8.5,
      "description": "A scenic route along Madrid's river park..."
    }
    // ... more routes
  ]
}

​
Browse Interactive Documentation

The easiest way to explore the API is through the Swagger UI:
  1. Open http://localhost:4000/api-docs in your browser
  2. Browse all available endpoints
  3. Try requests directly from the interface
  4. See request/response schemas

​
Useful Docker Commands

Manage your development environment with these 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

​
Next Steps

Now that you have the API running, you can:

Explore API Endpoints

Learn about all available endpoints and their parameters

Authentication Setup

Configure Clerk authentication for protected endpoints

Environment Variables

Understand all configuration options

Manual Installation

Set up the API without Docker

​
Troubleshooting

If you see database connection errors:
  1. Make sure Docker containers are running: docker ps
  2. Check PostgreSQL container logs: docker-compose logs db
  3. Verify the DATABASE_URL in your .env file
  4. Try rebuilding: docker-compose down -v && docker-compose up --build
If port 4000 is already occupied:
  1. Change the PORT variable in your .env file
  2. Update docker-compose.yml port mapping accordingly
  3. Restart the containers
If you see Clerk-related errors:
  1. Verify your CLERK_SECRET_KEY and CLERK_PUBLISHABLE_KEY are correct
  2. Make sure they’re from the same Clerk application
  3. Check that your Clerk application is properly configured
For more detailed installation options, including manual setup without Docker, see the Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us