Installation Guide

This guide provides detailed instructions for installing and configuring SIGEAC (Sistema de Gestión Aeronáutica Civil) in various environments.

System Requirements

Minimum Requirements

Node.js: 20.x or higher
RAM: 4GB minimum, 8GB recommended
Disk Space: 2GB for dependencies and build artifacts
OS: Linux, macOS, or Windows

Supported Package Managers

npm (comes with Node.js)
yarn 1.x or higher
pnpm 8.x or higher
bun 1.x or higher

Prerequisites

Install Node.js

Download and install Node.js 20 or higher from nodejs.orgVerify your installation:

node --version  # Should output v20.x.x or higher
npm --version   # Should output 10.x.x or higher

Install Git

Install Git from git-scm.com if not already installed:

git --version  # Verify installation

Backend API Setup

Ensure your SIGEAC backend API is running and accessible. The frontend requires:

A running Laravel backend API
CORS configured to allow requests from your frontend domain
JWT authentication endpoints (/api/login, /api/logout, etc.)
WebSocket support (optional, for real-time features)

Installation Steps

1. Clone the Repository

git clone <repository-url>
cd sigec_frontend

2. Install Dependencies

Choose your preferred package manager and install dependencies:

npm install

The installation process will download and install 80+ packages including:

Next.js 14.2.14 - React framework
React 18 - UI library
TanStack Query 5 - Data fetching and caching
Radix UI - Accessible component primitives
Tailwind CSS 3 - Utility-first CSS framework
TypeScript 5 - Type safety
Axios - HTTP client
Zustand - State management
Zod - Schema validation

Configuration

Environment Variables

Create a .env.local file in the root directory with the following variables:

.env.local

# ====================================
# API Configuration (Required)
# ====================================
NEXT_PUBLIC_API_BASE_URL=https://api.sigeac.com/api

# ====================================
# Storage Configuration (Required)
# ====================================
NEXT_PUBLIC_STORAGE_BASE_URL=https://storage.sigeac.com/

# ====================================
# WebSocket Configuration (Optional)
# ====================================
# Required for real-time notifications and updates
NEXT_PUBLIC_REVERB_APP_KEY=your-reverb-app-key
NEXT_PUBLIC_REVERB_HOST=reverb.sigeac.com
NEXT_PUBLIC_REVERB_SCHEME=https

Important: All environment variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Never store sensitive secrets in these variables.

Environment Variable Details

Variable	Required	Description
`NEXT_PUBLIC_API_BASE_URL`	Yes	Base URL for the SIGEAC backend API. Must include `/api` path
`NEXT_PUBLIC_STORAGE_BASE_URL`	Yes	Base URL for file storage (images, documents, PDFs)
`NEXT_PUBLIC_REVERB_APP_KEY`	No	Reverb application key for WebSocket connections
`NEXT_PUBLIC_REVERB_HOST`	No	Reverb server hostname
`NEXT_PUBLIC_REVERB_SCHEME`	No	Protocol for Reverb (`https` or `http`)

Next.js Configuration

The application comes pre-configured with next.config.mjs. Key configurations include:

next.config.mjs

const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "http",
        hostname: "172.190.0.162",
      },
      {
        protocol: "https",
        hostname: "apisigeactmd74.share.zrok.io",
      },
    ],
  },
};

Image Optimization: Update the remotePatterns array to include your backend domain for Next.js image optimization.

Tailwind CSS Configuration

SIGEAC uses a custom Tailwind configuration with:

Custom color scheme - HSL-based design tokens
Dark mode support - Class-based theme switching
Custom animations - Accordion, background movement effects
Custom background images - Aviation-themed backgrounds
shadcn/ui integration - Pre-styled component library

No additional Tailwind configuration is needed for basic usage.

Running the Application

Development Mode

Start the development server with hot module replacement:

npm run dev

The application will be available at http://localhost:3000

Production Build

Build the application for production:

npm run build
npm run start

Production builds are optimized with minification, code splitting, and image optimization. Build time typically takes 1-3 minutes depending on your hardware.

Application Structure

Understanding SIGEAC’s directory structure:

sigec_frontend/
├── app/                    # Next.js App Router pages
│   ├── [company]/         # Multi-tenant company routes
│   ├── acceso_publico/    # Public access pages (SMS reports)
│   ├── ajustes/           # Settings pages
│   ├── login/             # Authentication pages
│   ├── inicio/            # Dashboard
│   └── sistema/           # System management
├── components/            # Reusable React components
│   ├── cards/            # Card components
│   ├── dialogs/          # Modal dialogs
│   ├── forms/            # Form components
│   ├── layout/           # Layout components
│   └── ui/               # shadcn/ui components
├── actions/              # Server actions and API calls
│   ├── aerolinea/        # Airline operations
│   ├── general/          # General operations
│   ├── mantenimiento/    # Maintenance actions
│   └── sms/              # Safety management
├── hooks/                # Custom React hooks
├── lib/                  # Utility functions and configs
│   ├── axios.ts          # Axios instance configuration
│   ├── session.ts        # Session management
│   └── utils.ts          # Helper functions
├── contexts/             # React contexts (Auth, etc.)
├── stores/               # Zustand state stores
├── types/                # TypeScript type definitions
├── public/               # Static assets
└── middleware.ts         # Next.js middleware (auth)

Authentication Flow

SIGEAC implements cookie-based JWT authentication:

Login: User submits credentials to /api/login
Token Storage: JWT token stored in auth_token cookie
Axios Interceptor: Automatically attaches Authorization: Bearer <token> to all API requests
Middleware Protection: middleware.ts protects routes like /inicio, /ajustes, /administracion
Session Expiry: 401 responses trigger automatic logout and redirect to /login

Protected routes require valid authentication. Accessing protected routes without a valid token will redirect to /login.

Code Linting

Run ESLint to check for code quality issues:

npm run lint

Fix auto-fixable issues:

npm run lint -- --fix

Troubleshooting

Installation Issues

npm install fails with dependency conflicts

Try using the --legacy-peer-deps flag:

npm install --legacy-peer-deps

Or use a different package manager like pnpm which handles peer dependencies better:

npm install -g pnpm
pnpm install

Sharp installation fails

Sharp (image optimization library) may fail on some systems. Try:

npm rebuild sharp

Or install platform-specific binaries:

npm install --platform=linux --arch=x64 sharp

Node version mismatch

Ensure you’re using Node.js 20 or higher:

node --version

Use nvm to switch versions:

nvm install 20
nvm use 20

Runtime Issues

Port 3000 already in use

Specify a different port:

PORT=3001 npm run dev

Or kill the process using port 3000:

# On Linux/Mac
lsof -ti:3000 | xargs kill -9

# On Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

API connection errors (CORS)

CORS errors indicate backend configuration issues. Ensure your backend allows:

Origin: http://localhost:3000 (development) or your production domain
Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
Headers: Authorization, Content-Type, skip_zrok_interstitial
Credentials: true (for cookies)

Example Laravel CORS configuration:

'paths' => ['api/*'],
'allowed_origins' => ['http://localhost:3000'],
'allowed_methods' => ['*'],
'allowed_headers' => ['*'],
'supports_credentials' => true,

Images not loading

If images from the backend aren’t loading:

Verify NEXT_PUBLIC_STORAGE_BASE_URL is correct
Add your storage domain to next.config.mjs:

images: {
  remotePatterns: [
    {
      protocol: "https",
      hostname: "your-storage-domain.com",
    },
  ],
}

Restart the development server after config changes

Authentication loops or infinite redirects

Clear cookies and local storage:

// In browser console
document.cookie.split(";").forEach(c => {
  document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/");
});
localStorage.clear();

Then refresh the page and log in again.

WebSocket connection fails

WebSocket errors are non-critical. The app functions without WebSockets, but you’ll miss real-time updates.To fix:

Verify Reverb server is running
Check NEXT_PUBLIC_REVERB_* environment variables
Ensure WebSocket port is open in your firewall
Verify the backend Reverb configuration matches frontend settings

Build Issues

Build fails with TypeScript errors

Check for type errors:

npx tsc --noEmit

Fix errors before building. Common issues:

Missing type definitions
Incorrect prop types
Unused variables (can be suppressed with // @ts-ignore)

Out of memory during build

Increase Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Build succeeds but start fails

Ensure all environment variables are set in production:

# Create .env.production
cp .env.local .env.production

# Rebuild
npm run build
npm run start

Production Deployment

For production deployment options, see:

Vercel Deployment - Recommended for Next.js apps
Docker Deployment - Containerized deployment options
Self-Hosted - Deploy on your own infrastructure

Next Steps

After installation:

Quickstart

Quick guide to get started with SIGEAC

Configuration

Detailed configuration options

Architecture

Learn about SIGEAC’s technical architecture

API Integration

Connect to the backend API

Getting Help

If you encounter issues not covered in this guide:

Review the troubleshooting section above
Contact your system administrator
Report bugs via GitHub Issues

Getting Started

Core Concepts

Modules

User Guides

Installation

Installation Guide

System Requirements

Minimum Requirements

Supported Package Managers

Prerequisites

Installation Steps

1. Clone the Repository

2. Install Dependencies

Configuration

Environment Variables

Environment Variable Details

Next.js Configuration

Tailwind CSS Configuration

Running the Application

Development Mode

Production Build

Application Structure

Authentication Flow

Code Linting

Troubleshooting

Installation Issues

Runtime Issues

Build Issues

Production Deployment

Next Steps

Quickstart

Configuration

Architecture

API Integration

Getting Help

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

User Guides

​Installation Guide

​System Requirements

​Minimum Requirements

​Supported Package Managers

​Prerequisites

​Installation Steps

​1. Clone the Repository

​2. Install Dependencies

​Configuration

​Environment Variables

​Environment Variable Details

​Next.js Configuration

​Tailwind CSS Configuration

​Running the Application

​Development Mode

​Production Build

​Application Structure

​Authentication Flow

​Code Linting

​Troubleshooting

​Installation Issues

​Runtime Issues

​Build Issues

​Production Deployment

​Next Steps

Quickstart

Configuration

Architecture

API Integration

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Minimum Requirements

Supported Package Managers

Prerequisites

Installation Steps

1. Clone the Repository

2. Install Dependencies

Configuration

Environment Variables

Environment Variable Details

Next.js Configuration

Tailwind CSS Configuration

Running the Application

Development Mode

Production Build

Application Structure

Authentication Flow

Code Linting

Troubleshooting

Installation Issues

Runtime Issues

Build Issues

Production Deployment

Next Steps

Getting Help