Skip to main content

Build & Deployment

Complete guide for building and deploying ZÈYA Admin Panel.

Prerequisites​

  • Node.js: 18.x or higher
  • npm: 9.x or higher
  • Docker: (Optional, for containerized deployment)

Building the Application​

Development Build​

# Start development server
npm run dev

Production Build​

# Build for production
npm run build

# Start production server
npm start

Static Export (if needed)​

# Export static site
npm run export

Environment Configuration​

Development (.env.local)​

NEXT_PUBLIC_API_URL=http://localhost:8000/api/admin/v1
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_APP_ENV=development
NEXT_PUBLIC_AUTH_TOKEN_KEY=auth_token

Staging (.env.staging)​

NEXT_PUBLIC_API_URL=https://staging-api.zeya.app/api/admin/v1
NEXT_PUBLIC_API_BASE_URL=https://staging-api.zeya.app
NEXT_PUBLIC_APP_ENV=staging
NEXT_PUBLIC_AUTH_TOKEN_KEY=auth_token

Production (.env.production)​

NEXT_PUBLIC_API_URL=https://api.zeya.app/api/admin/v1
NEXT_PUBLIC_API_BASE_URL=https://api.zeya.app
NEXT_PUBLIC_APP_ENV=production
NEXT_PUBLIC_AUTH_TOKEN_KEY=auth_token

Deployment Options​

Vercel Deployment​

Recommended for Next.js applications:

  1. Connect Repository

    • Import project from GitHub/GitLab
    • Connect to repository

  2. Configure Environment Variables

    • Add environment variables in Vercel dashboard
    • Set build and start commands

  3. Deploy

    • Push to main branch triggers deployment
    • Or deploy manually from dashboard

Build Settings:

  • Build Command: npm run build
  • Output Directory: .next
  • Install Command: npm install

Docker Deployment​

The project includes Docker configuration files:

Production Dockerfile:

# Build image
docker build -f docker/Dockerfile.production -t zeya-admin:latest .

# Run container
docker run -d \
  --name zeya-admin \
  -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=https://api.zeya.app/api/admin/v1 \
  zeya-admin:latest

Staging Dockerfile:

docker build -f docker/Dockerfile.stage -t zeya-admin:stage .

Traditional Server Deployment​

Requirements:

  • Node.js installed
  • PM2 or similar process manager
  • Nginx or Apache for reverse proxy

Steps:

  1. Build Application
npm run build
  1. Start with PM2
pm2 start npm --name "zeya-admin" -- start
  1. Configure Nginx
server {
    listen 80;
    server_name admin.zeya.app;
    
    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;
    }
}

Build Optimization​

Production Build Features​

  • Code minification
  • Tree shaking
  • Image optimization
  • CSS optimization
  • Automatic code splitting

Build Output​

After npm run build, you'll find:

  • .next/ - Build output directory
  • Optimized JavaScript bundles
  • Optimized CSS files
  • Static assets

Environment-Specific Builds​

Development​

NEXT_PUBLIC_APP_ENV=development npm run dev

Staging​

NEXT_PUBLIC_APP_ENV=staging npm run build
NEXT_PUBLIC_APP_ENV=staging npm start

Production​

NEXT_PUBLIC_APP_ENV=production npm run build
NEXT_PUBLIC_APP_ENV=production npm start

Deployment Checklist​

  • Environment variables configured
  • API URLs set correctly
  • Build succeeds without errors
  • Production build tested locally
  • SSL certificates configured
  • Domain configured
  • CDN configured (if using)
  • Monitoring set up
  • Error tracking configured

Troubleshooting​

Build Failures​

Common Issues:

  • Missing environment variables
  • API URL not accessible
  • Build memory issues
  • Dependency conflicts

Solutions:

# Clear cache and rebuild
rm -rf .next node_modules
npm install
npm run build

# Check environment variables
cat .env.local

# Increase Node memory (if needed)
NODE_OPTIONS=--max-old-space-size=4096 npm run build

Runtime Errors​

  • Check server logs
  • Verify environment variables
  • Check API connectivity
  • Verify authentication

Performance Issues​

  • Enable Next.js caching
  • Use CDN for static assets
  • Optimize images
  • Enable compression

CI/CD Integration​

GitHub Actions Example​

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npm run build
      - run: npm run lint

Monitoring​

Health Check Endpoint​

The app includes a health check endpoint:

  • /api/health - Health check endpoint

Error Tracking​

  • Configure error tracking service
  • Monitor production errors
  • Set up alerts