Skip to main content

​
Prerequisites

Before installing Alternativa Verde, ensure you have the following installed on your system:
  • Node.js (v18 or higher recommended)
  • pnpm package manager
  • PostgreSQL database (v12 or higher)
If you don’t have pnpm installed, you can install it globally with: npm install -g pnpm

​
Installation Steps

1

Install Dependencies

Clone or download the Alternativa Verde application, navigate to the project directory, and install all required dependencies:
pnpm install
This will install all necessary packages including:
  • React for the user interface
  • Express for the API server
  • PostgreSQL client for database connectivity
  • Additional utilities for charting and data export
2

Create PostgreSQL Database

Connect to your PostgreSQL instance and create the database:
createdb tickets
Or using psql:
CREATE DATABASE tickets;
3

Configure Environment Variables

Create a .env file in the project root by copying the example file:
cp .env.example .env
Edit the .env file with your database connection details:
PGHOST=127.0.0.1
PGPORT=5432
PGUSER=postgres
PGPASSWORD=your_password_here
PGDATABASE=tickets
Make sure to replace your_password_here with your actual PostgreSQL password. Never commit the .env file to version control.
4

Load Database Schema

Load the consolidated database schema which includes all tables, indexes, and extensions:
psql -U postgres -d tickets -f db/schema.sql
This creates the following tables:
  • collection_centers - Collection center locations
  • collection_center_members - Team members and roles
  • generators - Material generators (clients)
  • vehicles - Collection center vehicles
  • tickets - Material entry records
  • dispatches - Material exit records
  • app_configuration - Application settings
The schema automatically installs the pg_trgm extension for efficient text searching.
5

Load Initial Data (Optional)

If you want to start with sample data for testing, load the seed data:
pnpm db:seed
Skip this step if you’re setting up a production environment and want to start with a clean database.
6

Start the Application

Start both the frontend application and the API server:
pnpm dev:all
This command runs:
  • Frontend: React application (typically on port 5173)
  • API Server: Express backend (typically on port 3000)
Alternatively, you can run them separately:
pnpm dev
7

Verify Installation

Open your browser and navigate to the application URL (typically http://localhost:5173). You should see the Alternativa Verde interface.
The exact port may vary depending on your configuration. Check the terminal output for the correct URL.

​
Database Structure Overview

The Alternativa Verde database uses PostgreSQL with the following key tables:
TablePurpose
collection_centersStores collection center information (name, location, active status)
collection_center_membersTeam members with roles (collectors, administrators)
generatorsMaterial generators (clients) with collection modes
vehiclesCollection center vehicles for material transport
ticketsEntry tickets for incoming materials
dispatchesExit records for dispatched materials
app_configurationActive collection center setting

​
Next Steps

Now that you have Alternativa Verde installed, proceed to the Quick Start guide to configure your first collection center and create your first ticket:

Quick Start Guide

Get operational in minutes by setting up your collection center and creating your first ticket

​
Troubleshooting

Make sure PostgreSQL is running and the connection details in your .env file are correct. Test the connection with:
psql -U postgres -d tickets
If the default ports are already in use, you can modify the port configuration in the Vite and Express configuration files.
Install pnpm globally:
npm install -g pnpm

Build docs developers (and LLMs) love

Get started for freeTalk to us