Installation Guide
This comprehensive guide will walk you through setting up Portal Ciudadano Manta from scratch, including all prerequisites, environment configuration, and Supabase backend setup.Prerequisites
Before you begin, ensure your development environment meets these requirements:Node.js
Package Manager
npm (included with Node.js) or yarnCheck your version:
Git
Supabase Account
Free tier availableSign up at supabase.com
Step 1: Clone the Repository
First, clone the project repository to your local machine:The repository includes all source code, configuration files, and assets needed to run the application.
Step 2: Install Dependencies
Install all required npm packages:Key Dependencies Installed
The installation includes:Frontend Framework
Frontend Framework
package.json
TypeScript & Build Tools
TypeScript & Build Tools
package.json
Styling
Styling
package.json
Backend & Database
Backend & Database
package.json
Maps & Geolocation
Maps & Geolocation
package.json
Internationalization
Internationalization
package.json
PDF Generation
PDF Generation
package.json
Step 3: Supabase Project Setup
Supabase provides the backend infrastructure including database, authentication, and file storage.Create Supabase Project
- Go to supabase.com and sign in
- Click “New Project”
- Fill in project details:
- Name: Portal-Ciudadano-Manta
- Database Password: Strong password (save this!)
- Region: Choose closest to Ecuador (e.g., US East)
- Pricing Plan: Free tier is sufficient for development
- Click “Create new project”
Project creation takes 1-2 minutes. You’ll see a loading screen while Supabase provisions your PostgreSQL database.
Get API Credentials
Once the project is ready:
- Go to Settings → API
- Copy these values:
- Project URL (
VITE_SUPABASE_URL) - anon public key (
VITE_SUPABASE_ANON_KEY)
- Project URL (
Create Database Schema
Navigate to SQL Editor in your Supabase dashboard and execute the following schema:
Database Schema
Click “Run” to execute the schema. This creates all tables, indexes, and triggers.
Configure Row Level Security (RLS)
Enable RLS to secure your data. In the SQL Editor, run:
Row Level Security
Row Level Security ensures users can only access data they’re authorized to see. Admins have full access, while citizens can only access their own data and public content.
Configure Storage Buckets
For image uploads (news images, report photos):
- Go to Storage in Supabase dashboard
- Create a new bucket called
reportes-fotos - Set it to Public
- Create another bucket called
noticias-imagenes - Set it to Public
Storage Policies
Configure Authentication Settings
Go to Authentication → Settings:Email Auth Settings:
- Enable Email confirmation
- Set Site URL: Your production URL (or
http://localhost:5173for dev) - Add Redirect URLs:
http://localhost:5173/login?verified=truehttp://localhost:5173/reset-password- Your production URLs
- Confirmation email
- Password reset email
- Magic link email
The site URL and redirect URLs must match your application URLs exactly for authentication flows to work properly.
Step 4: Environment Configuration
Create your environment file with the Supabase credentials:How Environment Variables Are Used
The app loads these variables in the Supabase client:src/lib/supabase.ts
Step 5: Start Development Server
With everything configured, start the development server:The application should now be running at
http://localhost:5173Step 6: Verify Installation
Test that everything is working:Check Browser Console
Open DevTools (F12) and verify:
- No errors in console
- Supabase client initialized successfully
- No 404s for assets
Test Registration
Navigate to
/register and create a test account to verify:- Form validation works
- Supabase authentication works
- User record created in database
- Confirmation email sent
Building for Production
When ready to deploy:Deploy to Netlify
Portal Ciudadano Manta includes a Option 2: GitHub Integration
netlify.toml configuration for easy deployment:Option 1: Netlify CLI- Push your code to GitHub
- Connect repository in Netlify dashboard
- Configure build settings:
- Build command:
npm run build - Publish directory:
dist - Node version:
20
- Build command:
- Add environment variables in Netlify:
VITE_SUPABASE_URLVITE_SUPABASE_ANON_KEY
The included
netlify.toml configures redirects for SPA routing, security headers, and caching automatically.Troubleshooting
Supabase Connection Errors
Supabase Connection Errors
Symptoms: “Failed to fetch”, timeout errors, or authentication issuesSolutions:
- Verify
.envfile exists and has correct credentials - Check Supabase project status (not paused)
- Verify API keys are copied correctly (no extra spaces)
- Check browser console for specific error messages
- Ensure Supabase project URL uses HTTPS
Build Errors
Build Errors
Symptoms: TypeScript errors, missing modulesSolutions:
- Delete
node_modulesand reinstall: - Clear Vite cache:
- Check Node.js version (must be 16+)
Map Not Loading
Map Not Loading
Symptoms: Blank map, missing tilesSolutions:
- Check browser console for CORS errors
- Verify Leaflet CSS is imported in
main.ts - Check network tab for tile loading issues
- Ensure location permissions are granted
Authentication Issues
Authentication Issues
Symptoms: Can’t log in, session expires immediatelySolutions:
- Verify redirect URLs in Supabase settings
- Check site URL configuration
- Clear browser cookies and local storage
- Verify RLS policies are correct
- Check email confirmation settings
Next Steps
Quickstart Guide
Learn how to use the platform features
API Reference
Explore the Supabase database schema and APIs
Deployment
Deploy to production (Netlify, Vercel, etc.)
Architecture
Learn about the system architecture
Installation complete! Your Portal Ciudadano Manta development environment is ready.
