OpenEco Documentation

Self-hosted climate transparency for enterprises

View the Project on GitHub Open-Eco/oe-core

Vercel Deployment Guide

Deploy OpenEco to Vercel for demos, previews, or small-scale production deployments.

Quick Deploy

Deploy with Vercel

Time: ~10 minutes

Prerequisites

Step-by-Step Deployment

1. Import Repository

  1. Visit vercel.com/new
  2. Import your GitHub repository: Open-Eco/oe-core
  3. Configure:
    • Root Directory: web
    • Framework: Next.js (auto-detected)

2. Configure Environment Variables

Add these in Vercel project settings:

Variable Value How to Get
DATABASE_URL PostgreSQL connection string See Database Options
NEXTAUTH_SECRET Random 32+ char string openssl rand -base64 32
NEXTAUTH_URL Your Vercel URL https://your-project.vercel.app
NEXT_PUBLIC_APP_URL Same as NEXTAUTH_URL https://your-project.vercel.app

3. Deploy

Click Deploy and wait ~2-5 minutes.

4. Initialize Database

After first deploy:

# Clone repo locally
git clone https://github.com/Open-Eco/oe-core.git
cd oe-core/web

# Pull Vercel environment variables
vercel env pull .env.local

# Run migrations
npx prisma generate
npx prisma db push

Database Options

Best for Vercel deployments

  1. Sign up: neon.tech
  2. Create project and database
  3. Copy connection string
  4. Add to Vercel as DATABASE_URL

Free tier: 0.5 GB storage, perfect for demos

Alternative: Supabase

  1. Sign up: supabase.com
  2. Create project
  3. Get connection string: Settings > Database
  4. Add to Vercel as DATABASE_URL

Free tier: 500 MB database

Alternative: Railway

  1. Sign up: railway.app
  2. Create PostgreSQL service
  3. Copy connection string
  4. Add to Vercel as DATABASE_URL

Custom Domain

Add Domain in Vercel

  1. Project Settings > Domains
  2. Add your domain: demo.open-eco.org
  3. Configure DNS:
Type: CNAME
Name: demo
Value: cname.vercel-dns.com

Update Environment Variables

After adding domain:

NEXTAUTH_URL=https://demo.open-eco.org
NEXT_PUBLIC_APP_URL=https://demo.open-eco.org

Then redeploy.

Troubleshooting

404 Not Found Error

A 404 Not Found response after deployment is one of the most common issues with OpenEco on Vercel.

Common Causes

  1. Root Directory not set to web — OpenEco’s Next.js app lives in web/. If Vercel builds from the repository root it cannot locate the application, causing all routes to return 404.
  2. Incorrect or missing vercel.json — Invalid rewrites, redirects, or routes entries can send requests to paths that do not exist.
  3. Build output directory mismatch — Setting outputDirectory to anything other than .next (the Next.js default) prevents Vercel from serving the compiled app.
  4. Build did not complete successfully — A failed build leaves no deployable output, so all routes return 404.
  5. Next.js page not found — The requested path simply does not exist in the Next.js app (mistyped URL, removed route, etc.).

Step-by-Step Debugging

Step 1: Check the Root Directory setting

  1. Go to Project Settings > General in your Vercel project
  2. Under Build & Development Settings, confirm Root Directory is web
  3. If blank or set to ., change it to web and redeploy

Step 2: Verify vercel.json

The repository-level vercel.json should look like this (no outputDirectory or framework overrides needed):

{
  "buildCommand": "npm run build",
  "installCommand": "npm install",
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

Step 3: Review build logs

  1. Open the Vercel project dashboard and select the affected deployment
  2. Click View Build Logs and scroll to the end
  3. A successful build ends with ✓ Compiled successfully and a route listing
  4. Any errors or a missing .next output indicate a build failure

Step 4: Confirm the build output locally

cd web
npm install
npm run build
ls -la .next/   # Should list: cache/, server/, static/, BUILD_ID, etc.

Step 5: Test a known route

Visit https://your-project.vercel.app/ and https://your-project.vercel.app/api/health. If only specific routes return 404, the issue is in Next.js routing rather than Vercel configuration.

Repository-Specific Example

Setting Correct Value
Root Directory web
Framework Preset Next.js (auto-detected)
Build Command npm run build
Output Directory .next (auto-detected)
Install Command npm install

An empty Root Directory causes Vercel to look for next.config.js in the repository root (where it does not exist), producing a build error or 404 on all routes.

Further Reading

Build Fails: “Prisma Client not generated”

Solution: Ensure web/package.json has:

"scripts": {
  "postinstall": "prisma generate"
}

Database Connection Failed

Check:

Authentication Not Working

Check:

Configuration Files

vercel.json

Located in repository root. Key settings:

{
  "buildCommand": "npm run build",
  "installCommand": "npm install",
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

Important: Do not add "framework", "outputDirectory", or "routes" keys unless you have a specific reason — Next.js auto-detection handles these correctly when Root Directory is set to web. Incorrect values for these keys are a common cause of 404 errors after deployment. See Troubleshooting: 404 Not Found Error for details.

Security Headers

Automatically applied:

Vercel vs Self-Hosted

Feature Vercel Self-Hosted
Setup Time 10 min 2-4 hours
SSL/HTTPS Automatic Manual
Scaling Automatic Manual
Database External Included
Best For Demos, small teams Enterprise, production

When to self-host:

See INSTALLATION.md for self-hosted deployment.

Deployment Guides

Configuration

Resources

Full Documentation

For complete Vercel deployment documentation with advanced configuration, see:

VERCEL_DEPLOYMENT.md in the repository root

Estimated Time: 10-15 minutes
Difficulty: Easy
Best For: Demos, previews, small teams

Part of the OpenEco Documentation