Deployment - BeeHex

Overview

BeeHex is a Next.js 14 application optimized for deployment on modern hosting platforms. This guide covers deployment options, configuration, and best practices.

Prerequisites

Before deploying, ensure:

Your code is committed to a Git repository
All tests pass locally
Production environment variables are configured
Game server backend is deployed and accessible

Deployment Options

Vercel (Recommended)

Vercel is the recommended platform for deploying BeeHex, created by the makers of Next.js.

Connect Repository

Go to vercel.com
Click “New Project”
Import your BeeHex repository

Configure Project

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

Framework Preset: Next.js
Build Command: npm run build
Output Directory: .next
Install Command: npm install

Set Environment Variables

Add production environment variables:

Variable	Value	Description
`NODE_ENV`	`production`	Environment mode

Since BeeHex uses src/env/env.ts for configuration, you’ll need to modify this file or use a build-time script to inject production values.

Deploy

Click “Deploy”. Vercel will:

Install dependencies
Build your Next.js application
Deploy to a global CDN
Provide a production URL

Deployment typically takes 2-3 minutes.

Vercel Features

Automatic Deployments

Every push to your main branch triggers a new deployment

Preview Deployments

Pull requests get unique preview URLs for testing

Edge Network

Global CDN for fast loading worldwide

Zero Configuration

Automatic optimization for Next.js apps

Netlify

Deploy BeeHex on Netlify with automatic builds:

Create New Site

Log in to netlify.com
Click “Add new site” → “Import an existing project”
Connect your Git repository

Configure Build Settings

Build command: npm run build
Publish directory: .next

Add Environment Variables

In Site settings → Environment variables, configure your production settings.

Deploy

Click “Deploy site” to trigger your first deployment.

Netlify provides automatic HTTPS, continuous deployment, and branch previews.

Docker Container

Deploy BeeHex as a Docker container for self-hosted environments:

Create Dockerfile

Create a Dockerfile in your project root:

Dockerfile

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source code
COPY . .

# Build application
RUN npm run build

# Production stage
FROM node:20-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

# Copy built application
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/node_modules ./node_modules

# Expose port
EXPOSE 3000

# Start application
CMD ["npm", "start"]

Build Docker Image

docker build -t beehex:latest .

Run Container

docker run -p 3000:3000 \
  -e NODE_ENV=production \
  beehex:latest

(Optional) Use Docker Compose

Create docker-compose.yml:

docker-compose.yml

version: '3.8'

services:
  beehex:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Run with:

docker-compose up -d

Traditional Hosting (VPS)

Deploy on a VPS (DigitalOcean, AWS EC2, etc.):

Prepare Server

Install Node.js 20+ on your server:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Clone Repository

git clone <your-repo-url> /var/www/beehex
cd /var/www/beehex

Install Dependencies

npm ci --only=production

Configure Environment

Create production environment configuration:

# Edit src/env/env.ts with production values
nano src/env/env.ts

src/env/env.ts

export default function getEnv() {
  return {
    'IP_HOST': 'your-game-server.com',
  };
}

Build Application

npm run build

Start with PM2

Use PM2 for process management:

# Install PM2 globally
npm install -g pm2

# Start application
pm2 start npm --name "beehex" -- start

# Save PM2 configuration
pm2 save

# Setup auto-restart on server reboot
pm2 startup

Configure Nginx Reverse Proxy

Create Nginx configuration:

/etc/nginx/sites-available/beehex

server {
    listen 80;
    server_name your-domain.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 site:

sudo ln -s /etc/nginx/sites-available/beehex /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Setup SSL with Let's Encrypt

sudo apt-get install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Build Optimization

Production Build

Create an optimized production build:

npm run build

This command:

Compiles TypeScript to JavaScript
Minifies JavaScript and CSS
Optimizes images and fonts
Generates static pages where possible
Creates production bundles in .next/

Build Output

.next/
├── static/              # Static assets with cache hashing
├── server/              # Server-side code
│   ├── app/            # App Router pages
│   └── chunks/         # Code-split chunks
└── cache/              # Build cache for faster rebuilds

Environment Configuration

Production Environment

For production, modify src/env/env.ts:

export default function getEnv() {
  return {
    'IP_HOST': '127.0.0.1', // Local development
  };
}

Important: The current environment system uses a gitignored file. Consider implementing a build-time environment variable system for easier deployment:

export default function getEnv() {
  return {
    'IP_HOST': process.env.NEXT_PUBLIC_GAME_SERVER || '127.0.0.1',
  };
}

Environment Variable Best Practices

Never commit secrets to version control
Use different values for development, staging, and production
Prefix client-side variables with NEXT_PUBLIC_ in Next.js
Document all required variables in your README

Performance Optimization

Next.js Optimizations

BeeHex leverages Next.js built-in optimizations:

Automatic Code Splitting

Each route only loads necessary code

Image Optimization

Automatic image resizing and WebP conversion

Font Optimization

Self-hosted fonts with zero layout shift

Script Optimization

Optimized third-party script loading

Additional Optimizations

Enable Compression

Next.js automatically gzip/brotli compresses responses in production.

Configure Caching

Set appropriate cache headers for static assets:

next.config.mjs

const nextConfig = {
  reactStrictMode: false,
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, max-age=31536000, immutable',
          },
        ],
      },
    ];
  },
};

Analyze Bundle Size

npm install -D @next/bundle-analyzer

Update next.config.mjs:

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer(nextConfig);

Run analysis:

ANALYZE=true npm run build

Monitoring & Logging

Application Monitoring

Monitor your production deployment:

Vercel Analytics: Built-in analytics for Vercel deployments
Google Analytics: Track user behavior
Sentry: Error tracking and performance monitoring
LogRocket: Session replay and debugging

Health Checks

Implement health check endpoints:

src/app/api/health/route.ts

export async function GET() {
  return Response.json({ 
    status: 'ok', 
    timestamp: new Date().toISOString() 
  });
}

Rollback Strategy

Vercel Rollback

Go to your project dashboard
Click “Deployments”
Find the previous working deployment
Click ”⋯” → “Promote to Production”

Manual Rollback

# Revert to previous commit
git revert HEAD
git push origin main

# Or checkout specific commit
git checkout <previous-commit-hash>
git push origin main --force

Continuous Deployment

GitHub Actions

Automate deployments with GitHub Actions:

.github/workflows/deploy.yml

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run linter
        run: npm run lint
        
      - name: Build application
        run: npm run build
        
      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

Security Considerations

Production Checklist:

✅ Use HTTPS for all connections
✅ Configure secure WebSocket connections (WSS)
✅ Set secure headers (CSP, HSTS, X-Frame-Options)
✅ Enable rate limiting on API routes
✅ Sanitize user inputs
✅ Keep dependencies up to date
✅ Monitor for security vulnerabilities

Security Headers

Add security headers in next.config.mjs:

const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'Referrer-Policy',
            value: 'strict-origin-when-cross-origin',
          },
        ],
      },
    ];
  },
};

Troubleshooting

Build Fails

Issue: Build fails with TypeScript errors

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

WebSocket Connection Issues

Issue: Can’t connect to game server in production

Verify IP_HOST in src/env/env.ts points to production server
Ensure game server allows connections from your domain
Check CORS configuration on game server
Use WSS (secure WebSocket) for HTTPS sites

Memory Issues

Issue: Build runs out of memory

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run build

Next Steps

Architecture Overview

Understand the system architecture

Game Engine

Learn about the game engine implementation

WebSocket Protocol

Explore the real-time communication protocol

Contributing

Contribute to the project

Architecture

Development

Documentation Index

​Overview

​Prerequisites

​Deployment Options

​Vercel (Recommended)

​Vercel Features

Automatic Deployments

Preview Deployments

Edge Network

Zero Configuration

​Netlify

​Docker Container

​Traditional Hosting (VPS)

​Build Optimization

​Production Build

​Build Output

​Environment Configuration

​Production Environment

​Environment Variable Best Practices

​Performance Optimization

​Next.js Optimizations

Automatic Code Splitting

Image Optimization

Font Optimization

Script Optimization

​Additional Optimizations

​Monitoring & Logging

​Application Monitoring

​Health Checks

​Rollback Strategy

​Vercel Rollback

​Manual Rollback

​Continuous Deployment

​GitHub Actions

​Security Considerations

​Security Headers

​Troubleshooting

​Build Fails

​WebSocket Connection Issues

​Memory Issues

​Next Steps

Architecture Overview

Game Engine

WebSocket Protocol

Contributing

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Options

Vercel (Recommended)

Vercel Features

Netlify

Docker Container

Traditional Hosting (VPS)

Build Optimization

Production Build

Build Output

Environment Configuration

Production Environment

Environment Variable Best Practices

Performance Optimization

Next.js Optimizations

Additional Optimizations

Monitoring & Logging

Application Monitoring

Health Checks

Rollback Strategy

Vercel Rollback

Manual Rollback

Continuous Deployment

GitHub Actions

Security Considerations

Security Headers

Troubleshooting

Build Fails

WebSocket Connection Issues

Memory Issues

Next Steps