Deployment

Overview

Sistema Financiero is a Next.js application that can be deployed to any platform supporting Node.js 20+. This guide covers the most popular deployment platforms.

All deployment methods require a configured Supabase project. Complete Supabase Configuration first.

Deployment Platforms Comparison

Platform	Free Tier	Build Time	Edge Network	Best For
Vercel	✅ Hobby (generous)	~2 min	✅ Global CDN	Next.js apps (recommended)
Railway	❌ $5/month	~3 min	✅ Global	Full-stack with DB
Netlify	✅ Starter	~2 min	✅ Global CDN	Static + serverless
Render	✅ Free tier	~5 min	❌ Single region	Simple deployments
Cloudflare Pages	✅ Free (unlimited)	~2 min	✅ 300+ locations	Edge-first apps
Self-Hosted	✅ (your server)	~2 min	❌	Full control

Recommended: Vercel is built by the creators of Next.js and offers the best developer experience with zero configuration.

Deploy to Vercel (Recommended)

Prerequisites

GitHub, GitLab, or Bitbucket account
Code pushed to a repository
Supabase project configured

Deployment Steps

Push Code to GitHub

If you haven’t already:

Terminal

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/sistema-financiero.git
git push -u origin main

Import Project to Vercel

Go to vercel.com and sign in with GitHub
Click Add New → Project
Select your sistema-financiero repository
Click Import

Vercel auto-detects Next.js and configures build settings.

Configure Environment Variables

Before deploying, add environment variables:

In the Configure Project screen, expand Environment Variables
Add each variable:

Key	Value	Environment
`NEXT_PUBLIC_SUPABASE_URL`	Your Supabase URL	Production, Preview, Development
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Your Supabase anon key	Production, Preview, Development
`OPENROUTER_API_KEY`	Your OpenRouter key (optional)	Production, Preview, Development
`NEXT_PUBLIC_APP_URL`	`https://your-app.vercel.app`	Production

For NEXT_PUBLIC_APP_URL, use a placeholder first (like https://sistema-financiero.vercel.app), then update it after deployment with your actual Vercel URL.

Deploy

Click Deploy and wait ~2 minutes.You’ll see build logs streaming. Once complete, you’ll get a deployment URL like:

https://sistema-financiero-abc123.vercel.app

Update App URL

After first deployment:

Go to Settings → Environment Variables
Find NEXT_PUBLIC_APP_URL
Update to your actual Vercel URL

Redeploy:

Terminal

git commit --allow-empty -m "Update app URL"
git push

Custom Domain (Optional)

Add Domain in Vercel

Go to your project Settings → Domains
Enter your domain (e.g., finanzas.tuempresa.com)
Click Add

Configure DNS

Vercel will show DNS records to add:For root domains (example.com):

A Record:
Name: @
Value: 76.76.21.21

For subdomains (app.example.com):

CNAME Record:
Name: app
Value: cname.vercel-dns.com

Add these records in your domain registrar (GoDaddy, Namecheap, Cloudflare, etc.)

Wait for Verification

DNS propagation takes 5-60 minutes. Vercel will automatically issue an SSL certificate once verified.

Continuous Deployment

Vercel automatically deploys on every git push:

Production: Commits to main branch → your-app.vercel.app
Preview: Commits to other branches → your-app-git-branch.vercel.app
Pull Requests: Each PR gets a unique preview URL

Preview deployments let you test changes before merging to production. Share the URL with team members for review.

Deploy to Railway

Deployment Steps

Create Railway Account

Go to railway.app
Sign up with GitHub
Verify your email

Create New Project

Click New Project
Select Deploy from GitHub repo
Choose your sistema-financiero repository
Click Deploy Now

Add Environment Variables

Click on your service
Go to Variables tab

Click New Variable for each:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
OPENROUTER_API_KEY=sk-or-v1-...
NEXT_PUBLIC_APP_URL=https://your-app.up.railway.app

Configure Build Settings

Railway auto-detects Next.js. If needed, manually set:

Build Command: npm run build
Start Command: npm run start
Port: 3000 (auto-detected)

Deploy

Railway automatically deploys. Check the Deployments tab for progress.Once complete, click View Deployment to see your live app.

Custom Domain on Railway

Go to Settings → Networking
Click Custom Domain
Enter your domain and follow DNS instructions
Add the provided CNAME record to your DNS

Railway provides automatic SSL certificates for custom domains.

Deploy to Netlify

Deployment Steps

Create Netlify Account

Go to netlify.com
Sign up with GitHub

Import Project

Click Add new site → Import an existing project
Select GitHub
Authorize Netlify
Choose your repository

Configure Build Settings

Netlify should auto-detect these settings:

Build command: npm run build
Publish directory: .next
Functions directory: .netlify/functions (auto-created)

Netlify requires the Next.js Runtime plugin. It’s usually auto-installed, but if builds fail, add it manually in Site Settings → Build & deploy → Build plugins.

Add Environment Variables

Go to Site settings → Build & deploy → Environment
Click Edit variables

Add each variable:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
OPENROUTER_API_KEY=sk-or-v1-...
NEXT_PUBLIC_APP_URL=https://your-app.netlify.app

Deploy

Click Deploy site. Initial build takes ~3 minutes.Once complete, you’ll get a URL like https://sistema-financiero.netlify.app.

Deploy to Render

Create Render Account

Create Web Service

Click New → Web Service
Connect your GitHub repository
Configure:
- Name: sistema-financiero
- Environment: Node
- Build Command: npm install && npm run build
- Start Command: npm run start

Add Environment Variables

In the Environment section, add:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
OPENROUTER_API_KEY=sk-or-v1-...
NEXT_PUBLIC_APP_URL=https://sistema-financiero.onrender.com

Deploy

Click Create Web Service. First deployment takes ~5 minutes.

Render’s free tier may spin down after inactivity. First request after idle takes 30-60 seconds to wake up.

Deploy to Cloudflare Pages

Install Wrangler CLI

Terminal

npm install -g wrangler
wrangler login

Configure for Cloudflare Pages

Cloudflare Pages requires adapter configuration. Add to package.json:

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "pages:build": "npx @cloudflare/next-on-pages",
    "pages:dev": "npx @cloudflare/next-on-pages --watch"
  }
}

Install adapter:

Terminal

npm install --save-dev @cloudflare/next-on-pages

Deploy

Terminal

npm run pages:build
npx wrangler pages deploy .vercel/output/static

Add Environment Variables

In Cloudflare dashboard:

Go to Workers & Pages → Your project
Settings → Environment Variables
Add each variable for Production and Preview

Cloudflare Pages has limitations with Next.js API routes. Some features (like streaming AI responses) may not work. Vercel or Railway are better choices for full functionality.

Self-Hosted Deployment

Using Docker

Create Dockerfile

Create Dockerfile in project root:

Dockerfile

FROM node:20-alpine AS base

# Install dependencies
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package*.json ./
RUN npm ci

# Build application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Set build-time env vars
ARG NEXT_PUBLIC_SUPABASE_URL
ARG NEXT_PUBLIC_SUPABASE_ANON_KEY
ARG NEXT_PUBLIC_APP_URL
ENV NEXT_PUBLIC_SUPABASE_URL=$NEXT_PUBLIC_SUPABASE_URL
ENV NEXT_PUBLIC_SUPABASE_ANON_KEY=$NEXT_PUBLIC_SUPABASE_ANON_KEY
ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL

RUN npm run build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

Update next.config.ts

Enable standalone output:

next.config.ts

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'standalone',
}

export default nextConfig

Build Image

Terminal

docker build \
  --build-arg NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co \
  --build-arg NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc... \
  --build-arg NEXT_PUBLIC_APP_URL=https://your-domain.com \
  -t sistema-financiero .

Run Container

Terminal

docker run -d \
  -p 3000:3000 \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  --name sistema-financiero \
  sistema-financiero

Access at http://localhost:3000

Using PM2 (Node.js Process Manager)

Install PM2

Terminal

npm install -g pm2

Build Application

Terminal

npm run build

Create PM2 Config

Create ecosystem.config.js:

ecosystem.config.js

module.exports = {
  apps: [{
    name: 'sistema-financiero',
    script: 'node_modules/next/dist/bin/next',
    args: 'start',
    env: {
      NODE_ENV: 'production',
      PORT: 3000,
      NEXT_PUBLIC_SUPABASE_URL: 'https://your-project.supabase.co',
      NEXT_PUBLIC_SUPABASE_ANON_KEY: 'eyJhbGc...',
      OPENROUTER_API_KEY: 'sk-or-v1-...',
      NEXT_PUBLIC_APP_URL: 'https://your-domain.com',
    },
    instances: 'max',
    exec_mode: 'cluster',
    watch: false,
    max_memory_restart: '500M',
  }]
}

Start with PM2

Terminal

pm2 start ecosystem.config.js
pm2 save
pm2 startup

PM2 will auto-restart your app on crashes and reboot.

Nginx Reverse Proxy

If running on a VPS, use Nginx as a reverse proxy:

/etc/nginx/sites-available/sistema-financiero

server {
    listen 80;
    server_name finanzas.tuempresa.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;
    }
}

Enable SSL with Let’s Encrypt:

Terminal

sudo certbot --nginx -d finanzas.tuempresa.com

Post-Deployment Checklist

Verify Application Loads

Visit your deployment URL and check:

✅ Dashboard loads without errors
✅ No console errors in browser DevTools (F12)
✅ Favicon and images load

Test Database Connection

Try adding a transaction via the manual form
Check if it appears in the dashboard
Verify data is saved in Supabase Table Editor

Test AI Features (if enabled)

Go to the AI chat page (/agente-mejorado)
Send a test message: “Gasté $100 en gasolina”
Verify the transaction is registered

Check Performance

Run PageSpeed Insights:

https://pagespeed.web.dev/analysis?url=https://your-app.vercel.app

Target scores:

Performance: 90+
Accessibility: 95+
Best Practices: 95+
SEO: 90+

Set Up Monitoring (Optional)

Add error tracking with Sentry:

Terminal

npm install @sentry/nextjs
npx @sentry/wizard@latest -i nextjs

Or use Vercel Analytics (free for Vercel deployments):

Terminal

npm install @vercel/analytics

app/layout.tsx

import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

Troubleshooting Deployment Issues

Build fails with 'Module not found'

Problem: Missing dependencies or incorrect imports.Solution:

# Clear cache and reinstall
rm -rf node_modules .next package-lock.json
npm install
npm run build

Check import paths are correct:

// ✅ Correct (using tsconfig path alias)
import { supabase } from '@/lib/supabase'

// ❌ Wrong (relative path may break)
import { supabase } from '../../../lib/supabase'

Application crashes on startup

Problem: Missing environment variables or runtime errors.Solution:

Check deployment logs for error messages
Verify all required env vars are set in platform UI
Ensure NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are present

Test locally with production env:

NODE_ENV=production npm run build && npm run start

API routes return 500 errors

Problem: Server-side errors in API routes.Solution:

Check server logs (Vercel: Deployment logs, Railway: Service logs)
Common issues:
- Missing OPENROUTER_API_KEY (if using AI features)
- Supabase connection fails (check URL/key)
- CORS issues (check API route headers)

Add error logging:

export async function POST(request: Request) {
  try {
    // Your code
  } catch (error) {
    console.error('API Error:', error)
    return NextResponse.json(
      { error: String(error) },
      { status: 500 }
    )
  }
}

Slow cold start times

Problem: First request after idle takes 10+ seconds.Solution:

Vercel: Upgrade to Pro plan for always-warm instances
Railway: No cold starts (paid plans keep services running)
Render: Free tier spins down after 15min idle (upgrade to keep alive)
Self-hosted: No cold starts

Database queries are slow

Problem: Dashboard takes 5+ seconds to load.Solution:

Check Supabase region matches deployment region
Verify indexes exist (see Supabase Configuration)

Add query optimization:

// ❌ Slow (fetches all fields)
const { data } = await supabase.from('transacciones').select('*')

// ✅ Fast (only needed fields)
const { data } = await supabase
  .from('transacciones')
  .select('fecha, tipo, monto, categoria')
  .order('fecha', { ascending: false })
  .limit(100)

Rollback Deployment

Vercel

Go to Deployments tab
Find previous working deployment
Click ⋯ → Promote to Production

Railway

Go to Deployments tab
Find previous deployment
Click Redeploy

Git-Based Rollback

For any platform:

Terminal

# Revert last commit
git revert HEAD
git push

# Or rollback to specific commit
git reset --hard <commit-hash>
git push --force

Use --force carefully! It rewrites Git history and can affect team members.

Next Steps

Dashboard Features

Learn how to use the dashboard

API Reference

Integrate with the API

Customization

Customize the UI and features

Troubleshooting

Fix common problems

Congratulations! Your Sistema Financiero instance is now live. 🎉

Introduction

Setup

Overview

Deployment Platforms Comparison

Deploy to Vercel (Recommended)

Prerequisites

Deployment Steps

Custom Domain (Optional)

Continuous Deployment

Deploy to Railway

Deployment Steps

Custom Domain on Railway

Deploy to Netlify

Deployment Steps

Deploy to Render

Deploy to Cloudflare Pages

Self-Hosted Deployment

Using Docker

Using PM2 (Node.js Process Manager)

Nginx Reverse Proxy

Post-Deployment Checklist

Troubleshooting Deployment Issues

Rollback Deployment

Vercel

Railway

Git-Based Rollback

Next Steps

Dashboard Features

API Reference

Customization

Troubleshooting

Build docs developers (and LLMs) love

Introduction

Setup

​Overview

​Deployment Platforms Comparison

​Deploy to Vercel (Recommended)

​Prerequisites

​Deployment Steps

​Custom Domain (Optional)

​Continuous Deployment

​Deploy to Railway

​Deployment Steps

​Custom Domain on Railway

​Deploy to Netlify

​Deployment Steps

​Deploy to Render

​Deploy to Cloudflare Pages

​Self-Hosted Deployment

​Using Docker

​Using PM2 (Node.js Process Manager)

​Nginx Reverse Proxy

​Post-Deployment Checklist

​Troubleshooting Deployment Issues

​Rollback Deployment

​Vercel

​Railway

​Git-Based Rollback

​Next Steps

Dashboard Features

API Reference

Customization

Troubleshooting

Build docs developers (and LLMs) love

Overview

Deployment Platforms Comparison

Deploy to Vercel (Recommended)

Prerequisites

Deployment Steps

Custom Domain (Optional)

Continuous Deployment

Deploy to Railway

Deployment Steps

Custom Domain on Railway

Deploy to Netlify

Deployment Steps

Deploy to Render

Deploy to Cloudflare Pages

Self-Hosted Deployment

Using Docker

Using PM2 (Node.js Process Manager)

Nginx Reverse Proxy

Post-Deployment Checklist

Troubleshooting Deployment Issues

Rollback Deployment

Vercel

Railway

Git-Based Rollback

Next Steps