Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LizandroCanul/back_sdo/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before installing the Yucatan Public Works API, ensure you have the following installed:

Node.js

Version 18.x or higher recommended

PostgreSQL

Version 15.x with PostGIS 3.3+ extension

npm

Version 8.x or higher (comes with Node.js)

Docker

Optional but recommended for database setup
You can verify your Node.js version with node --version and npm with npm --version

​
Installation Steps

1

Clone the Repository

Clone the source code from your repository:
git clone <repository-url>
cd back_sdo
2

Install Dependencies

Install all required npm packages:
npm install
This installs:
  • NestJS framework and core modules
  • TypeORM for database operations
  • Passport.js for authentication
  • Class-validator for request validation
  • And other dependencies listed in package.json
3

Set Up the Database

Choose one of the following methods to set up PostgreSQL with PostGIS:The easiest way to get started is using the included Docker Compose configuration:
docker-compose up -d
This creates a PostgreSQL database with:
  • Image: postgis/postgis:15-3.3
  • Port: 5432
  • Database: obras_yucatan_db
  • User: admin
  • Password: password123
version: '3.8'

services:
  db:
    image: postgis/postgis:15-3.3
    restart: always
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password123
      POSTGRES_DB: obras_yucatan_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

​
Option B: Manual PostgreSQL Installation

If you prefer to install PostgreSQL manually:
  1. Install PostgreSQL 15 or higher
  2. Install the PostGIS extension
  3. Create the database:
CREATE DATABASE obras_yucatan_db;
CREATE USER admin WITH PASSWORD 'password123';
GRANT ALL PRIVILEGES ON DATABASE obras_yucatan_db TO admin;

-- Connect to the database and enable PostGIS
\c obras_yucatan_db
CREATE EXTENSION postgis;
4

Configure Environment Variables

Create a .env file in the project root directory:
cp .env.example .env
Edit the .env file with your configuration:
.env
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=admin
DATABASE_PASSWORD=password123
DATABASE_NAME=obras_yucatan_db

​
Environment Variables Reference

VariableDescriptionDefault
DATABASE_HOSTPostgreSQL host addresslocalhost
DATABASE_PORTPostgreSQL port5432
DATABASE_USERDatabase usernameadmin
DATABASE_PASSWORDDatabase passwordpassword123
DATABASE_NAMEDatabase nameobras_yucatan_db
Never commit the .env file to version control. It contains sensitive credentials.
5

Run Database Migrations

TypeORM will automatically synchronize the database schema when you start the application.The API uses TypeORM’s synchronize option in development, which automatically creates tables based on your entities.
In production, you should disable synchronize and use proper migrations instead.
6

Start the Application

You’re ready to run the API!
npm run start:dev
If successful, you’ll see:
🚀 Servidor corriendo en http://localhost:3000

​
Verify Installation

Test that the API is running correctly: 
curl http://localhost:3000
You can also check the health of your database connection by attempting to log in (you’ll need to create a user first or use seeded data).

​
Running Modes

The API supports different running modes for various environments:

​
Development Mode

Runs with auto-reload on file changes: 
npm run start:dev
Features:
  • Hot reload on code changes
  • Detailed error messages
  • Database synchronization enabled
  • CORS enabled for all origins

​
Production Mode

Optimized build for production deployment: 
npm run build
npm run start:prod
Features:
  • Compiled JavaScript output
  • Optimized performance
  • Should disable database synchronization
  • Configure CORS for specific origins

​
Debug Mode

Runs with Node.js debugger attached: 
npm run start:debug
Attach your debugger to port 9229.

​
Database Schema

The API automatically creates the following main tables:
  • obras: Public works projects
  • obra_ubicaciones: Geographic locations for obras (PostGIS)
  • users: System users with role-based access
  • user_favorite_obras: User favorites relationship
  • municipios: Municipalities
  • dependencias: Government dependencies
  • tipo_proyecto: Project type catalog
  • estatus_obra: Work status catalog
  • ejercicio_fiscal: Fiscal year catalog
  • localidad: Locality catalog

​
Configuration Details

The API includes several important configurations:

​
Global Validation Pipe

From src/main.ts:9-15: 
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,              // Remove unknown properties
    forbidNonWhitelisted: true,   // Throw error on unknown properties
    transform: true,              // Transform payloads to DTO instances
  }),
);

​
CORS Configuration

From src/main.ts:18-23: 
app.enableCors({
  origin: '*',                    // Allow all origins (development)
  methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
  preflightContinue: false,
  optionsSuccessStatus: 204,
});
In production, restrict CORS origin to your specific frontend domains instead of using '*'.

​
Troubleshooting

​
Database Connection Issues

Problem: Cannot connect to PostgreSQL Solutions:
  • Verify Docker container is running: docker ps
  • Check database credentials in .env match docker-compose.yml
  • Ensure PostgreSQL is listening on port 5432: netstat -an | grep 5432
  • Check firewall settings

​
PostGIS Extension Missing

Problem: Error about PostGIS geometry types Solutions: 
-- Connect to your database
\c obras_yucatan_db

-- Enable PostGIS extension
CREATE EXTENSION IF NOT EXISTS postgis;

-- Verify installation
SELECT PostGIS_Version();

​
Port Already in Use

Problem: Port 3000 is already in use Solutions:
  • Kill the process using port 3000: 
    # Find process
lsof -i :3000

# Kill process
kill -9 <PID>
  • Or change the port in src/main.ts:25

​
Module Not Found Errors

Problem: Cannot find module errors after installation Solutions: 
# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

​
TypeORM Synchronization Issues

Problem: Tables not being created Solutions:
  • Verify database exists and is accessible
  • Check TypeORM configuration in your app module
  • Manually create the database if needed
  • Review entity files for syntax errors

​
Production Deployment

For production deployment, consider:

Environment Variables

Use a secrets manager for sensitive credentials

Database Migrations

Disable synchronize and use proper migrations

CORS Configuration

Restrict origins to your frontend domains

Process Manager

Use PM2 or similar for process management

​
Production Environment Variables

.env.production
NODE_ENV=production
DATABASE_HOST=your-production-host
DATABASE_PORT=5432
DATABASE_USER=your-prod-user
DATABASE_PASSWORD=your-secure-password
DATABASE_NAME=obras_yucatan_db
DATABASE_SSL=true
JWT_SECRET=your-very-secure-secret

​
Using PM2 for Production

# Install PM2 globally
npm install -g pm2

# Build the application
npm run build

# Start with PM2
pm2 start dist/main.js --name yucatan-api

# View logs
pm2 logs yucatan-api

# Restart on file changes
pm2 reload yucatan-api

​
Next Steps

Authentication Setup

Configure JWT tokens and create your first users

Database Schema

Understand the complete data model

API Reference

Explore all available API endpoints

Quick Start Guide

Make your first API requests

Build docs developers (and LLMs) love

Get started for freeTalk to us