Deployment Guide - BudgetView

Overview

BudgetView is a Next.js application designed for deployment on modern hosting platforms. This guide covers production deployment, environment configuration, and best practices.

BudgetView is optimized for serverless deployment with automatic scaling and global CDN distribution.

Deployment Options

Vercel

Recommended platform with zero-config Next.js support and automatic CI/CD

Netlify

Alternative platform with similar features and generous free tier

Self-Hosted

Docker or Node.js deployment on your own infrastructure

Prerequisites

Before deploying, ensure you have:

Supabase Project

Active Supabase project with database and authentication configured

Git Repository

Source code pushed to GitHub, GitLab, or Bitbucket

Environment Variables

Supabase URL and API key from project settings

Domain Name

Custom domain for production (optional but recommended)

Vercel Deployment (Recommended)

Initial Setup

Connect Repository

Visit vercel.com and sign in
Click “Add New Project”
Import your Git repository
Select the repository containing BudgetView

Configure Build Settings

Vercel auto-detects Next.js projects. Verify these settings:

Framework Preset: Next.js
Build Command: npm run build
Output Directory: .next (auto-detected)
Install Command: npm install
Node Version: 18.x or higher

Set Environment Variables

Add required variables in Vercel dashboard:

Variable	Value	Source
`NEXT_PUBLIC_SUPABASE_URL`	`https://xxxxx.supabase.co`	Supabase → Settings → API
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	`eyJhbGc...`	Supabase → Settings → API → anon public

Use the anon key, NOT the service_role key for NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY.

Deploy

Click “Deploy” and wait for build completion (typically 2-3 minutes)

Verify Deployment

Visit the generated URL (e.g., your-project.vercel.app)
Test login functionality
Create a test wallet and transaction
Verify data appears in Supabase dashboard

Continuous Deployment

Vercel automatically deploys on Git push:

# Make changes and commit
git add .
git commit -m "Update dashboard UI"
git push origin main

# Vercel builds and deploys automatically
# View deployment at https://vercel.com/your-username/your-project

Branch deployments:

main branch → Production deployment
Feature branches → Preview deployments with unique URLs
Pull requests → Automatic preview comments

Custom Domain

Add a custom domain in Vercel:

Add Domain

Go to project Settings → Domains
Enter your domain (e.g., budgetview.com)
Click “Add”

Configure DNS

Add DNS records at your domain registrar:

Type: A
Name: @
Value: 76.76.21.21

Type: CNAME
Name: www
Value: cname.vercel-dns.com

Verify Domain

Vercel automatically provisions SSL certificate (via Let’s Encrypt)

Netlify Deployment

Setup Instructions

Connect Repository

Visit netlify.com and sign in
Click “Add new site → Import an existing project”
Choose your Git provider and repository

Build Configuration

Configure build settings:

netlify.toml

[build]
  command = "npm run build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

Environment Variables

Add in Site settings → Environment variables:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

Deploy

Click “Deploy site” and monitor build logs

Netlify-Specific Configuration

Create a netlify.toml file in your project root:

[build]
  command = "npm run build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[build.environment]
  NODE_VERSION = "18"

Self-Hosted Deployment

Using Node.js

Deploy directly on a VPS or dedicated server:

Install Dependencies

# On your server
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g pm2  # Process manager

Clone Repository

git clone https://github.com/your-username/budgetview.git
cd budgetview
npm install

Configure Environment

# Create .env.local file
cat > .env.local << EOF
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

Build Application

npm run build

Start with PM2

pm2 start npm --name "budgetview" -- start
pm2 save
pm2 startup  # Enable auto-restart on server reboot

Configure Nginx

server {
  listen 80;
  server_name budgetview.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 Certbot:

sudo certbot --nginx -d budgetview.com

Using Docker

Create a Dockerfile:

FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Production image
FROM node:18-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

COPY --from=builder /app/package*.json ./
RUN npm ci --only=production

COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public

EXPOSE 3000

CMD ["npm", "start"]

Build and run:

# Build image
docker build -t budgetview:latest .

# Run container
docker run -d \
  -p 3000:3000 \
  -e NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co \
  -e NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-anon-key \
  --name budgetview \
  --restart unless-stopped \
  budgetview:latest

Docker Compose:

docker-compose.yml

version: '3.8'

services:
  budgetview:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_SUPABASE_URL=${NEXT_PUBLIC_SUPABASE_URL}
      - NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=${NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY}
    restart: unless-stopped

Start with:

docker-compose up -d

Environment Variables

Required Variables

The application will not function without these variables properly configured.

Variable	Required	Description	Example
`NEXT_PUBLIC_SUPABASE_URL`	Yes	Supabase project URL	`https://abc123.supabase.co`
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	Yes	Supabase anon public key	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`

Optional Variables

Variable	Default	Description
`PORT`	`3000`	Server port
`NODE_ENV`	`production`	Environment mode

Validating Configuration

The application checks for required environment variables on startup:

app/login/page.tsx

if (!process.env.NEXT_PUBLIC_SUPABASE_URL || 
    !process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY) {
  throw new Error("Variables de entorno de Supabase no configuradas")
}

Build Configuration

Next.js Config

The next.config.js file can be customized:

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
  images: {
    domains: ['your-project.supabase.co'],
  },
  // Disable source maps in production for smaller bundles
  productionBrowserSourceMaps: false,
}

module.exports = nextConfig

Package.json Scripts

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint ."
  }
}

Performance Optimization

Build Time
Runtime
Database

Enable SWC minification (default in Next.js 13+)
Use npm ci instead of npm install in CI/CD
Cache node_modules between builds
Disable source maps in production

Next.js automatic code splitting
Image optimization with next/image
Font optimization with next/font
API route caching with revalidate

Monitoring & Logging

Vercel Analytics

Enable in project settings:

Go to Analytics tab
Enable Web Analytics
View real-time metrics: pageviews, unique visitors, top pages

Error Tracking

Integrate Sentry for error monitoring:

npm install @sentry/nextjs

sentry.client.config.js

import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0,
})

Application Logs

For self-hosted deployments, use PM2 logs:

pm2 logs budgetview          # View live logs
pm2 logs budgetview --lines 100  # Last 100 lines
pm2 flush budgetview         # Clear logs

Database Migrations

Manage Supabase schema changes:

# Install Supabase CLI
npm install -g supabase

# Link to project
supabase link --project-ref your-project-ref

# Create migration
supabase migration new add_new_column

# Apply migration
supabase db push

Always test migrations in a development environment before applying to production.

Security Checklist

Environment Variables

✓ Never commit .env.local to Git
✓ Use different Supabase projects for dev/prod
✓ Rotate API keys if exposed

HTTPS

✓ Enable SSL certificate (automatic on Vercel/Netlify)
✓ Force HTTPS redirects
✓ Use HSTS headers

Database Security

✓ Row Level Security enabled on all tables
✓ Service role key never exposed to client
✓ Regular database backups

Authentication

✓ Email verification enabled (optional)
✓ Rate limiting on login attempts
✓ Strong password requirements

Troubleshooting

Rollback Strategy

If a deployment causes issues:

Vercel
Self-Hosted

Go to Deployments tab
Find previous working deployment
Click ⋯ → Promote to Production
Instant rollback (no rebuild required)

# Git rollback
git log --oneline  # Find commit hash
git checkout abc123
npm run build
pm2 restart budgetview

Backup & Disaster Recovery

Always maintain backups of your database and environment configuration.

Database Backups

Supabase Pro plan includes automatic daily backups. For manual backups:

# Export database
supabase db dump -f backup-$(date +%Y%m%d).sql

# Restore from backup
supabase db reset --db-url postgresql://...

Code Backups

Git repository serves as source code backup
Tag production releases: git tag v1.0.0
Push to multiple remotes for redundancy

Production Checklist

Before going live:

For architecture details, see the System Architecture page.

Get Started

Core Features

User Guide

Technical

​Overview

​Deployment Options

Vercel

Netlify

Self-Hosted

​Prerequisites

​Vercel Deployment (Recommended)

​Initial Setup

​Continuous Deployment

​Custom Domain

​Netlify Deployment

​Setup Instructions

​Netlify-Specific Configuration

​Self-Hosted Deployment

​Using Node.js

​Using Docker

​Environment Variables

​Required Variables

​Optional Variables

​Validating Configuration

​Build Configuration

​Next.js Config

​Package.json Scripts

​Performance Optimization

​Monitoring & Logging

​Vercel Analytics

​Error Tracking

​Application Logs

​Database Migrations

​Security Checklist

​Troubleshooting

​Rollback Strategy

​Backup & Disaster Recovery

​Database Backups

​Code Backups

​Production Checklist

Build docs developers (and LLMs) love

Overview

Deployment Options

Prerequisites

Vercel Deployment (Recommended)

Initial Setup

Continuous Deployment

Custom Domain

Netlify Deployment

Setup Instructions

Netlify-Specific Configuration

Self-Hosted Deployment

Using Node.js

Using Docker

Environment Variables

Required Variables

Optional Variables

Validating Configuration

Build Configuration

Next.js Config

Package.json Scripts

Performance Optimization

Monitoring & Logging

Vercel Analytics

Error Tracking

Application Logs

Database Migrations

Security Checklist

Troubleshooting

Rollback Strategy

Backup & Disaster Recovery

Database Backups

Code Backups

Production Checklist