Installation - Kontrak Backend

System Requirements

Before installing Kontrak Backend, ensure your system meets the following requirements:

Required Software

Node.js

Version: 18.0.0 or higherRecommended: 20.x LTSDownload from nodejs.org

npm

Version: 8.0.0 or higherIncluded with Node.jsOr use yarn/pnpm as alternatives

System Dependencies

Linux (Ubuntu/Debian)
macOS
Windows

Puppeteer requires additional system libraries for headless Chrome:

sudo apt-get update
sudo apt-get install -y \
  ca-certificates \
  fonts-liberation \
  libappindicator3-1 \
  libasound2 \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libcairo2 \
  libcups2 \
  libdbus-1-3 \
  libexpat1 \
  libfontconfig1 \
  libgbm1 \
  libgcc1 \
  libgdk-pixbuf2.0-0 \
  libglib2.0-0 \
  libgtk-3-0 \
  libnspr4 \
  libnss3 \
  libpango-1.0-0 \
  libpangocairo-1.0-0 \
  libstdc++6 \
  libx11-6 \
  libx11-xcb1 \
  libxcb1 \
  libxcomposite1 \
  libxcursor1 \
  libxdamage1 \
  libxext6 \
  libxfixes3 \
  libxi6 \
  libxrandr2 \
  libxrender1 \
  libxss1 \
  libxtst6 \
  lsb-release \
  wget \
  xdg-utils

No additional dependencies required. Ensure you have:

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

Hardware Recommendations

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	2 GB	4+ GB
Disk Space	500 MB	2+ GB
Network	Any	Stable connection for npm packages

PDF generation is CPU and memory intensive, especially for batch processing. More resources = better performance.

Installation Methods

From Source (Recommended)
Using Docker (Coming Soon)

Clone Repository

# Clone the repository
git clone <your-repository-url>
cd kontrak-backend

Install Dependencies

npm install

This will install all required packages from package.json:

package.json (excerpt)

{
  "dependencies": {
    "express": "^5.1.0",
    "typescript": "^5.9.3",
    "zod": "^4.1.12",
    "puppeteer": "^24.34.0",
    "pdf-lib": "^1.17.1",
    "handlebars": "^4.7.8",
    "archiver": "^7.0.1",
    "dotenv": "^17.2.3",
    "cors": "^2.8.5",
    "pino": "^10.1.0"
  }
}

Build TypeScript

npm run build

This compiles TypeScript files from src/ to JavaScript in dist/ using the configuration in tsconfig.json.

Environment Configuration

Create Environment File

Copy the example environment file:

cp .env.example .env

Or create a new .env file manually in the project root.

Configure Server Settings

Edit .env and configure the server:

.env

# Server Configuration
NODE_ENV=development
PORT=3000
HOST=localhost

NODE_ENV

string

default:"development"

Environment mode: development or production

PORT

number

default:"3000"

Port number where the server will listen

HOST

string

default:"localhost"

Host address for the server

Configure CORS

Set allowed origins for Cross-Origin Resource Sharing:

.env

# CORS - Allowed origins (comma-separated)
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

CORS_ORIGINS

string

default:"http://localhost:5173"

Comma-separated list of allowed origins. Update this for production to include your frontend domain.

Example for Production:

CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

Configure File Limits

Set processing limits for safety:

.env

# File Limits
MAX_FILE_SIZE=10485760  # 10MB in bytes
MAX_EMPLOYEES=1000

MAX_FILE_SIZE

number

default:"10485760"

Maximum file size in bytes for uploads (default: 10MB)

MAX_EMPLOYEES

number

default:"1000"

Maximum number of employee records that can be processed

Configure Directories

Set the temporary directory for file processing:

.env

# Temporary directory for file processing
TEMP_DIR=./temp

TEMP_DIR

string

default:"./temp"

Directory path for temporary file storage during processing. The application will create this directory if it doesn’t exist.

Complete Environment Template

.env

# =====================================
# Kontrak Backend Configuration
# =====================================

# Server Configuration
NODE_ENV=development
PORT=3000
HOST=localhost

# CORS - Allowed origins (comma-separated)
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# File Limits
MAX_FILE_SIZE=10485760  # 10MB
MAX_EMPLOYEES=1000

# Timeouts and cleanup
FILE_CLEANUP_TIMEOUT=3600000  # 1 hour

# Temporary directory for file processing
TEMP_DIR=./temp

Verify Installation

Run Type Check

Verify TypeScript compilation without emitting files:

npm run type-check

Should complete with no errors.

Run Linter

Check code quality and style:

npm run lint

Fix any issues automatically:

npm run lint:fix

Build Project

Compile TypeScript to JavaScript:

npm run build

Verify dist/ directory is created with compiled files.

Start Development Server

Launch the server in development mode:

npm run dev

Expected output:

[INFO] Creando aplicacion Express...
[INFO] Registrando ruta GET /
[INFO] ✅ Ruta GET / registrada
[INFO] Registrando rutas en /api
[INFO] 📝 Registrando rutas de contratos...
[INFO] ✅ Rutas de contratos registradas
[INFO] Rutas registradas correctamente en /api
[INFO] Inicializando servidor...
[INFO] =========== Server running on port 3000 ==========
[INFO] =========== Environment: development ==========

Test API Endpoints

Test the health check endpoint:

curl http://localhost:3000/api/health

Expected response:

{
  "success": true,
  "message": "Server is running",
  "timestamp": "2026-03-05T10:30:00.000Z",
  "path": "/api/health"
}

Test the root endpoint:

curl http://localhost:3000/

Expected response:

{
  "success": true,
  "message": "Kontrak API - Sistema de Generación de Contratos",
  "version": "1.0.0",
  "status": "running",
  "timestamp": "2026-03-05T10:30:00.000Z",
  "endpoints": {
    "uploadExcel": "POST /api/contracts/upload",
    "health": "GET /api/health"
  }
}

Running in Production

Build for Production

# Set production environment
export NODE_ENV=production

# Build the project
npm run build

# Start the production server
npm start

The production start command runs:

node ./dist/index.js

Production Checklist

Update Environment Variables

.env

NODE_ENV=production
PORT=3000
HOST=0.0.0.0  # Listen on all interfaces
CORS_ORIGINS=https://yourdomain.com

Use Process Manager

Use PM2 or similar to manage the Node.js process:

# Install PM2
npm install -g pm2

# Start with PM2
pm2 start dist/index.js --name kontrak-backend

# Enable startup script
pm2 startup
pm2 save

Configure Reverse Proxy

Use Nginx or Apache as a reverse proxy:

nginx.conf

server {
    listen 80;
    server_name api.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Enable SSL/TLS

Use Let’s Encrypt for free SSL certificates:

# Install Certbot
sudo apt-get install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d api.yourdomain.com

Configure Logging

The application uses Pino for structured logging. Logs are written to stdout/stderr.View logs with PM2:

pm2 logs kontrak-backend

Common Installation Issues

npm install fails with EACCES error

Permission error when installing global packages.Solution:

# Option 1: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Puppeteer fails to download Chrome

Network issues or firewall blocking Chromium download.Solution:

# Skip Chromium download if you have Chrome installed
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install

# Or set custom executable path
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

TypeScript compilation errors

Version mismatch or missing type definitions.Solution:

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

# Ensure TypeScript version
npm install typescript@^5.9.3 --save-dev

Port already in use

Another process is using port 3000.Solution:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port in .env
PORT=3001

Permission denied creating temp directory

Application cannot create temporary directory.Solution:

# Create directory manually
mkdir -p ./temp
chmod 755 ./temp

# Or use system temp directory
TEMP_DIR=/tmp/kontrak

Development Scripts

Available npm scripts from package.json:

Script	Command	Description
`dev`	`npm run dev`	Start development server with hot reload
`build`	`npm run build`	Compile TypeScript to JavaScript
`start`	`npm start`	Run production server
`lint`	`npm run lint`	Check code with ESLint
`lint:fix`	`npm run lint:fix`	Fix ESLint errors automatically
`format`	`npm run format`	Format code with Prettier
`format:check`	`npm run format:check`	Check code formatting
`type-check`	`npm run type-check`	Type check without emitting files

Next Steps

Quick Start

Generate your first contract

Configuration

Advanced configuration options

API Reference

Explore all API endpoints

Troubleshooting

If you encounter issues during installation:

Check Node.js version: node --version (must be 18+)
Clear npm cache: npm cache clean --force
Review logs: Check console output for specific error messages
Verify dependencies: Ensure all system dependencies are installed (especially on Linux)
Check permissions: Ensure you have write access to the project directory

For persistent issues, check the application logs in development mode which provide detailed error information using the Pino logger.

​System Requirements

​Required Software

Node.js

npm

​System Dependencies

​Hardware Recommendations

​Installation Methods

​Clone Repository

​Install Dependencies

​Build TypeScript

​Environment Configuration

​Complete Environment Template

​Verify Installation

​Running in Production

​Build for Production

​Production Checklist

​Common Installation Issues

​Development Scripts

​Next Steps

Quick Start

Configuration

API Reference

​Troubleshooting

System Requirements

Required Software

System Dependencies

Hardware Recommendations

Installation Methods

Clone Repository

Install Dependencies

Build TypeScript

Environment Configuration

Complete Environment Template

Verify Installation

Running in Production

Build for Production

Production Checklist

Common Installation Issues

Development Scripts

Next Steps

Troubleshooting