Installation

Detailed installation and configuration guide for PROVESA Web

Complete guide to installing and configuring PROVESA Web, the institutional web platform and administrative panel for PROVESA SCC (Sociedad Cooperativa de Consumo).

System Requirements

Required Software

• Node.js: Version 20 or higher
• Package Manager: pnpm v9+ (recommended) or npm
• Database: PostgreSQL 15 or higher (local or remote)

Optional Tools

• Git: For cloning the repository
• Database GUI: pgAdmin, TablePlus, or Drizzle Studio for database management

Installation Steps

1. Clone the repository

   Clone the PROVESA Web repository from GitHub:

   git clone https://github.com/ashcroft08/provesa-web.git
   cd provesa-web
   
2. Install dependencies

   Install all required dependencies using your preferred package manager:

   npm

   npm install
   

   This will install all dependencies listed in package.json, including:

   • SvelteKit 5 - Application framework
   • Drizzle ORM - Database toolkit
   • Better Auth - Authentication system
   • TailwindCSS 4 - Styling framework
   • Nodemailer - Email sending
   • Vitest & Playwright - Testing frameworks
3. Set up environment variables

   Create your environment configuration file:

   cp .env.example .env
   

   Edit the .env file with your specific configuration:

   .env

   # Database Configuration
   DATABASE_URL="postgres://user:password@host:5432/provesa"
   
   # Application Origin
   ORIGIN="http://localhost:5173"
   
   # Authentication Secret (32 characters, high entropy)
   BETTER_AUTH_SECRET=""
   
   # Gmail Credentials for Password Recovery
   GMAIL_USER="[e-mail]"
   GMAIL_APP_PASSWORD="your-app-password"
   
   # Admin User Seed Configuration
   ADMIN_NAME="Administrador"
   ADMIN_EMAIL="[e-mail]"
   ADMIN_PASSWORD="your-secure-password"
   

   Never commit your .env file to version control. The .env.example file is provided as a template only.

4. Configure the database

   Apply the database schema to your PostgreSQL database:

   npm

   npm run db:push
   

   This command uses Drizzle Kit to synchronize your database schema with the definitions in src/lib/server/db/schema.js.

5. Seed the database

   Run the seed scripts to create initial data:

   npm

   npm run db:seed
   

   This will:

   • Create an admin user with the credentials from your .env file
   • Set up the default theme configuration
6. Start the development server

   Launch the development server:

   npm

   npm run dev
   

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

Environment Variables Reference

Database Configuration

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgres://user:password@localhost:5432/provesa

The database URL format is: postgres://username:password@host:port/database_name

Application Settings

Variable	Description	Example
ORIGIN	Base URL of your application	http://localhost:5173 (development) https://provesa.com (production)

Authentication

Variable	Description	Required
BETTER_AUTH_SECRET	32-character secret for session encryption	Yes

Generate a cryptographically secure secret for production. You can use openssl rand -base64 32 or visit Better Auth documentation for recommendations.

Email Configuration

Variable	Description	Required
GMAIL_USER	Gmail address for sending emails	Yes
GMAIL_APP_PASSWORD	Gmail app-specific password	Yes

To generate a Gmail App Password:

1. Go to your Google Account settings
2. Navigate to Security → 2-Step Verification
3. Scroll to “App passwords”
4. Generate a new app password for “Mail”

See Google’s guide for detailed instructions.

Admin User Seed

Variable	Description	Default
ADMIN_NAME	Display name for admin user	Administrador
ADMIN_EMAIL	Admin login email	[e-mail]
ADMIN_PASSWORD	Admin login password	(required)

Available Scripts

PROVESA Web includes several npm scripts for different tasks:

Development

npm

# Start development server
npm run dev

# Type-check the codebase
npm run check

# Type-check in watch mode
npm run check:watch

Database Management

npm

# Push schema changes to database
npm run db:push

# Generate migrations
npm run db:generate

# Run migrations
npm run db:migrate

# Open Drizzle Studio (database GUI)
npm run db:studio

# Run seed scripts
npm run db:seed

Production Build

npm

# Create production build
npm run build

# Preview production build locally
npm run preview

Testing & Quality

npm

# Run all tests (unit + E2E)
npm test

# Run unit tests only
npm run test:unit

# Run E2E tests only
npm run test:e2e

# Lint code
npm run lint

# Format code with Prettier
npm run format

Project Structure

provesa-web/
├── drizzle/                      # Database migrations
├── src/
│   ├── lib/
│   │   ├── assets/               # Static resources (favicon, etc.)
│   │   ├── components/           # Reusable components (Navbar, Admin)
│   │   ├── server/
│   │   │   ├── auth.js           # Better Auth configuration
│   │   │   └── db/               # Drizzle schemas, seeds, connection
│   │   └── utils/                # Shared utilities
│   └── routes/
│       ├── admin/                # Admin panel (protected routes)
│       ├── login/                # Login page
│       ├── recuperar/            # Password recovery request
│       └── restablecer-password/ # Password reset
├── static/                       # Public static files
├── .env.example                  # Environment variables template
├── drizzle.config.js             # Drizzle Kit configuration
├── svelte.config.js              # SvelteKit configuration
└── vite.config.js                # Vite configuration

Technology Stack

PROVESA Web is built with modern web technologies:

Technology	Purpose	Version
SvelteKit	Application framework	5
Svelte	UI framework with runes	5
TailwindCSS	Utility-first CSS framework	4
PostgreSQL	Relational database	15+
Drizzle ORM	TypeScript ORM	Latest
Better Auth	Authentication library	Latest
Nodemailer	Email sending (Gmail)	Latest
Vitest	Unit testing framework	Latest
Playwright	E2E testing framework	Latest

Troubleshooting

Database Connection Issues

If you encounter database connection errors:

1. Verify PostgreSQL is running: pg_isready
2. Check your DATABASE_URL format is correct
3. Ensure the database exists: createdb provesa
4. Verify user permissions in PostgreSQL

Port Already in Use

If port 5173 is already in use:

# Kill the process using port 5173
lsof -ti:5173 | xargs kill -9

# Or specify a different port
npm run dev -- --port 3000

Missing Environment Variables

If you see errors about missing environment variables:

1. Ensure .env file exists in the project root
2. Verify all required variables are set
3. Restart the development server after changing .env

Gmail Authentication Errors

If password recovery emails fail to send:

1. Verify GMAIL_USER and GMAIL_APP_PASSWORD are correct
2. Ensure you’re using an App Password, not your regular Gmail password
3. Check that 2-Step Verification is enabled on your Google account

Next Steps

After installation, you can:

• Access the admin panel at /admin
• Customize theme colors in the admin settings
• Manage candidates and suggestions
• Configure the public-facing website
• Set up production deployment

For production deployment, ensure you’ve configured proper environment variables, enabled HTTPS, and followed security best practices for your database and authentication secrets.