hasher/DEPLOYMENT.md

Deployment Guide

This guide covers deploying the Hasher application to production.

Prerequisites

• Node.js 18.x or higher
• Redis 6.x or higher
• Domain name (optional, for custom domain)
• SSL certificate (recommended for production)

Deployment Options

Option 1: Vercel (Recommended for Next.js)

Vercel provides seamless deployment for Next.js applications.

Steps:

1. Install Vercel CLI:

   npm install -g vercel
   

2. Login to Vercel:

   vercel login
   

3. Deploy:

   vercel
   

4. Set Environment Variables:

   • Go to your project settings on Vercel
   • Add environment variables:
     • REDIS_HOST=your-redis-host
     • REDIS_PORT=6379
     • REDIS_PASSWORD=your-password (if using authentication)
     • REDIS_DB=0
   • Redeploy: vercel --prod

Important Notes:

• Ensure Redis is accessible from Vercel's servers
• Consider using Redis Cloud (Upstash) or a publicly accessible Redis instance
• Use environment variables for sensitive configuration

---

Option 2: Docker

Deploy using Docker containers.

Create Dockerfile:

# Create this file: Dockerfile
FROM node:18-alpine AS base

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

COPY package.json package-lock.json ./
RUN npm ci

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

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:

import type { NextConfig } from 'next';

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

export default nextConfig;

Build and Run:

# Build the Docker image
docker build -t hasher:latest .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e REDIS_HOST=redis \
  -e REDIS_PORT=6379 \
  --name hasher \
  hasher:latest

Docker Compose:

Create docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped
    command: redis-server --appendonly yes

volumes:
  redis-data:

Run with:

docker-compose up -d

---

Option 3: Traditional VPS (Ubuntu/Debian)

Deploy to a traditional server.

1. Install Node.js:

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

2. Install PM2 (Process Manager):

sudo npm install -g pm2

3. Clone and Build:

cd /var/www
git clone <your-repo-url> hasher
cd hasher
npm install
npm run build

4. Configure Environment:

cat > .env.local << EOF
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password
REDIS_DB=0
NODE_ENV=production
EOF

5. Start with PM2:

pm2 start npm --name "hasher" -- start
pm2 save
pm2 startup

6. Configure Nginx (Optional):

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 the site:

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

---

Redis Setup

Option 1: Redis Cloud (Managed)

1. Sign up at Redis Cloud or Upstash
2. Create a database
3. Note the connection details (host, port, password)
4. Update REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD environment variables

Option 2: Self-Hosted

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install redis-server

# Configure
sudo nano /etc/redis/redis.conf
# Set: bind 0.0.0.0  (to allow remote connections)
# Set: requirepass your-strong-password  (for security)

# Start
sudo systemctl start redis-server
sudo systemctl enable redis-server

---

Security Considerations

1. Redis Security

• Enable authentication with requirepass
• Use TLS for Redis connections (Redis 6+)
• Restrict network access with firewall rules
• Update credentials regularly
• Disable dangerous commands (FLUSHDB, FLUSHALL, etc.)

2. Application Security

• Use environment variables for secrets
• Enable HTTPS (SSL/TLS)
• Implement rate limiting
• Add CORS restrictions
• Monitor logs for suspicious activity

3. Network Security

# Example UFW firewall rules
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow from YOUR_IP to any port 6379  # Redis
sudo ufw enable

---

Monitoring

Application Monitoring

# PM2 monitoring
pm2 monit

# View logs
pm2 logs hasher

Redis Monitoring

# Health check
redis-cli ping

# Get info
redis-cli INFO

# Database stats
redis-cli INFO stats

# Memory usage
redis-cli INFO memory

---

Backup and Recovery

Redis Backups

# Enable AOF (Append Only File) persistence
redis-cli CONFIG SET appendonly yes

# Save RDB snapshot manually
redis-cli SAVE

# Configure automatic backups in redis.conf
save 900 1      # Save if 1 key changed in 15 minutes
save 300 10     # Save if 10 keys changed in 5 minutes
save 60 10000   # Save if 10000 keys changed in 1 minute

# Backup files location (default)
# RDB: /var/lib/redis/dump.rdb
# AOF: /var/lib/redis/appendonly.aof

# Restore from backup
sudo systemctl stop redis-server
sudo cp /backup/dump.rdb /var/lib/redis/
sudo systemctl start redis-server

---

Scaling

Horizontal Scaling

1. Deploy multiple Next.js instances
2. Use a load balancer (nginx, HAProxy)
3. Share the same Redis instance or cluster

Redis Scaling

1. Use Redis Cluster for horizontal scaling
2. Set up Redis Sentinel for high availability
3. Use read replicas for read-heavy workloads
4. Consider Redis Enterprise for advanced features

---

Troubleshooting

Check Application Status

pm2 status
pm2 logs hasher --lines 100

Check Redis

redis-cli ping
redis-cli DBSIZE
redis-cli INFO stats

Common Issues

Issue: Cannot connect to Redis

• Check firewall rules
• Verify Redis is running: redis-cli ping
• Check REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD environment variables

Issue: Out of memory

• Increase Node.js memory: NODE_OPTIONS=--max-old-space-size=4096
• Configure Redis maxmemory and eviction policy
• Use Redis persistence (RDB/AOF) carefully

Issue: Slow searches

• Verify O(1) lookups are being used (direct key access)
• Check Redis memory and CPU usage
• Consider using Redis Cluster for distribution
• Optimize key patterns

---

Performance Optimization

1. Enable Next.js Static Optimization
2. Use CDN for static assets
3. Enable Redis pipelining for bulk operations
4. Configure appropriate maxmemory for Redis
5. Use SSD storage for Redis persistence
6. Enable Redis connection pooling (already implemented)

---

Support

For deployment issues, check:

• Next.js Deployment Docs
• Redis Setup Guide
• ioredis Documentation
• Project GitHub Issues