Skip to main content

​
Overview

The Los Inmaduros Backend includes full Docker support for easy deployment. Docker automatically handles database setup, dependency installation, and migrations.

​
Prerequisites

​
Development Setup

​
Quick Start

The easiest way to run the project in development mode: 
# Clone the repository
git clone https://github.com/Adriasu09/los-inmaduros-backend.git
cd los-inmaduros-backend

# Copy environment variables
cp .env.example .env
# Edit .env and add your Clerk and Supabase credentials

# Start with Docker Compose
npm run docker:dev
That’s it! The application will be available at:

​
Development Configuration

The docker-compose.yml file sets up two services:

​
PostgreSQL Database

postgres:
  image: postgres:14-alpine
  container_name: los-inmaduros-db
  restart: unless-stopped
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: postgres
    POSTGRES_DB: los_inmaduros
  ports:
    - "5432:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data

​
Backend API

backend:
  build:
    context: .
    dockerfile: Dockerfile
  container_name: los-inmaduros-backend
  restart: unless-stopped
  ports:
    - "4000:4000"
  environment:
    NODE_ENV: development
    DATABASE_URL: postgresql://postgres:postgres@postgres:5432/los_inmaduros
  depends_on:
    postgres:
      condition: service_healthy
  volumes:
    - ./src:/app/src
    - ./prisma:/app/prisma
  command: sh -c "npx prisma migrate deploy && npx tsx src/app.ts"

​
What Docker Does Automatically

When you run docker-compose up, Docker automatically:
  • Sets up a PostgreSQL 14 database with health checks
  • Installs all Node.js dependencies
  • Generates the Prisma Client
  • Runs database migrations with prisma migrate deploy
  • Starts the development server with hot reload
  • Mounts source code volumes for live code changes

​
Production Setup

For production deployments, use the docker-compose.prod.yml file: 
# Start production environment
npm run docker:prod

# Or directly
docker-compose -f docker-compose.prod.yml up --build

​
Production Differences

  • Uses multi-stage build for smaller image size
  • Installs only production dependencies (npm ci --only=production)
  • No source code volumes (compiled code only)
  • Optimized restart policies (restart: always)
  • Environment variables from .env file
  • Runs compiled JavaScript with npm start

​
Production Configuration

backend:
  build:
    context: .
    dockerfile: Dockerfile
    target: production
  container_name: los-inmaduros-backend-prod
  restart: always
  environment:
    NODE_ENV: production
    DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
  command: sh -c "npx prisma migrate deploy && npm start"

​
Dockerfile Stages

The Dockerfile uses a multi-stage build:

​
Stage 1: Build

FROM node:22-alpine AS builder

# Install OpenSSL for Prisma
RUN apk add --no-cache openssl libc6-compat

WORKDIR /app

# Install dependencies
COPY package*.json ./
COPY prisma ./prisma/
RUN npm ci

# Build application
COPY . .
RUN npx prisma generate
RUN npm run build

​
Stage 2: Production

FROM node:22-alpine AS production

RUN apk add --no-cache openssl libc6-compat

WORKDIR /app

# Install only production dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy Prisma and build artifacts
COPY --from=builder /app/prisma ./prisma
RUN npx prisma generate
COPY --from=builder /app/dist ./dist

EXPOSE 4000
ENV NODE_ENV=production

CMD ["npm", "start"]

​
Useful Docker Commands

​
Starting and Stopping

# Start development environment
npm run docker:dev
docker-compose up --build

# Start in background (detached)
docker-compose up -d

# Stop containers
npm run docker:dev:down
docker-compose down

# Stop and remove volumes (deletes database data)
docker-compose down -v

​
Viewing Logs

# View all logs
npm run docker:logs
docker-compose logs

# Follow logs in real-time
docker-compose logs -f

# View specific service logs
docker-compose logs backend
docker-compose logs postgres

​
Database Management

# Run Prisma Studio
docker-compose exec backend npx prisma studio

# Run migrations manually
docker-compose exec backend npx prisma migrate deploy

# Access PostgreSQL shell
docker-compose exec postgres psql -U postgres -d los_inmaduros

# Reset database
docker-compose down -v
docker-compose up --build

​
Rebuilding

# Rebuild containers
docker-compose up --build

# Force rebuild from scratch
docker-compose build --no-cache

# Remove everything and start fresh
docker-compose down -v && docker-compose up --build

​
Container Management

# List running containers
docker-compose ps

# Execute command in container
docker-compose exec backend sh

# Restart specific service
docker-compose restart backend

# View container resource usage
docker stats

​
Troubleshooting

​
Database Connection Issues

If the backend cannot connect to the database: 
# Check if database is healthy
docker-compose ps

# View database logs
docker-compose logs postgres

# Restart database
docker-compose restart postgres

​
Port Already in Use

If port 4000 or 5432 is already in use: 
# Find process using port
lsof -i :4000
lsof -i :5432

# Or change port in docker-compose.yml
ports:
  - "4001:4000"  # Use port 4001 instead

​
Volume Permissions

On Linux, if you encounter permission issues: 
# Change ownership
sudo chown -R $USER:$USER .

# Or run with sudo
sudo docker-compose up

​
Clean Slate

To completely reset everything: 
# Remove all containers, volumes, and images
docker-compose down -v --rmi all

# Start fresh
docker-compose up --build

​
Deploying to Cloud Platforms

The Docker configuration works with most container platforms:
  • Render: Automatically detects Dockerfile
  • Railway: Supports Docker deployments
  • Fly.io: Use fly launch with Dockerfile
  • Google Cloud Run: Deploy with gcloud run deploy
  • AWS ECS: Use ECR and ECS task definitions
See Production Deployment for platform-specific guides.

​
Next Steps

Environment Variables

Configure required environment variables

Production Deployment

Deploy to production platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us