Deployment

Overview

Popcorn Vision is built with Next.js 14, making it deployable to any platform that supports Next.js applications. This guide covers deployment to popular platforms and self-hosted environments.

Popcorn Vision uses Next.js App Router and requires a platform that supports Next.js 14+ features.

Quick Deploy Options

Vercel

RecommendedZero-config deployment with automatic optimizations. Best for Next.js apps.

Netlify

Easy SetupSimple deployment with good Next.js support via their plugin.

Self-Hosted

Full ControlDeploy to your own VPS, Docker container, or cloud provider.

Prerequisites

Before deploying, ensure you have:

TMDB API Credentials

Obtain your API key and Read Access Token from TMDB. See TMDB API Setup for details.

Environment Variables Ready

Prepare all required environment variables from Environment Configuration.

Code Repository

Push your code to a Git repository (GitHub, GitLab, or Bitbucket).

Test Locally

Verify the production build works locally:

npm run build
npm start

Deploy to Vercel

Vercel is the recommended platform for Next.js applications, offering zero-config deployment and automatic optimizations.

One-Click Deploy

The fastest way to deploy:

Click Deploy Button

Use the Deploy to Vercel button from the Popcorn Vision repository (if available), or manually import:

Go to Vercel
Click Add New > Project
Import your Git repository

Configure Environment Variables

In the Vercel project setup, add your environment variables:

API_URL=https://api.themoviedb.org/3
API_KEY=your_tmdb_api_key
API_READ=your_tmdb_read_token
GA_MEASUREMENT_ID=G-XXXXXXXXXX

Do not add NEXT_PUBLIC_API_IMAGE_* variables here unless you need to override them. They’re already set in your codebase.

Deploy

Click Deploy and wait for the build to complete.Vercel will:

Install dependencies
Build your Next.js application
Deploy to a production URL
Generate preview URLs for pull requests

Configure Custom Domain (Optional)

After deployment:

Go to your project settings
Navigate to Domains
Add your custom domain
Update DNS records as instructed

Manual CLI Deploy

Deploy using Vercel CLI:

# Install Vercel CLI
npm i -g vercel

# Login to Vercel
vercel login

# Deploy to production
vercel --prod

Vercel Configuration

Popcorn Vision works with default Vercel settings, but you can customize with vercel.json:

vercel.json

{
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm install",
  "framework": "nextjs",
  "regions": ["iad1"],
  "env": {
    "API_URL": "https://api.themoviedb.org/3"
  }
}

Vercel automatically detects Next.js and uses optimal build settings. You rarely need a vercel.json file.

Deploy to Netlify

Netlify supports Next.js through their Essential Next.js plugin.

Connect Repository

Log in to Netlify
Click Add new site > Import an existing project
Connect your Git provider and select your repository

Configure Build Settings

Netlify should auto-detect Next.js. Verify these settings:Build command: npm run build or pnpm buildPublish directory: .nextFunctions directory: .netlify/functions

Add Environment Variables

In Site settings > Environment variables, add:

API_URL=https://api.themoviedb.org/3
API_KEY=your_tmdb_api_key
API_READ=your_tmdb_read_token
GA_MEASUREMENT_ID=G-XXXXXXXXXX

Enable Next.js Plugin

The Essential Next.js plugin should be automatically enabled. If not:

Go to Integrations
Search for “Essential Next.js”
Install and enable the plugin

Deploy

Click Deploy site and wait for the build to complete.

Netlify Configuration

Create a netlify.toml file in your project root:

netlify.toml

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

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

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

Self-Hosted Deployment

Deploy Popcorn Vision to your own infrastructure.

Using Node.js Server

Build the Application

npm run build

This creates an optimized production build in .next/ directory.

Set Environment Variables

On your server, create a .env.production file:

API_URL=https://api.themoviedb.org/3
API_KEY=your_tmdb_api_key
API_READ=your_tmdb_read_token
NEXT_PUBLIC_API_IMAGE_500=https://image.tmdb.org/t/p/w500
# ... all other variables

Start the Production Server

npm start

By default, this runs on http://localhost:3000.

Use a Process Manager

Keep the application running with PM2:

# Install PM2
npm install -g pm2

# Start the app
pm2 start npm --name "popcorn-vision" -- start

# Save PM2 configuration
pm2 save

# Set PM2 to start on boot
pm2 startup

Configure Reverse Proxy

Use Nginx or Apache to proxy requests to your Next.js server.Nginx example:

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;
  }
}

Using Docker

Deploy with Docker for containerized deployment:

FROM node:18-alpine AS base

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

COPY package.json pnpm-lock.yaml* ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

# Build the application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED 1

RUN corepack enable pnpm && pnpm run build

# Production image
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

CMD ["node", "server.js"]

Build and run:

# Build the Docker image
docker build -t popcorn-vision .

# Run the container
docker run -p 3000:3000 --env-file .env.production popcorn-vision

# Or use docker-compose
docker-compose up -d

You’ll need to enable Next.js standalone output in next.config.mjs for Docker:

const nextConfig = {
  output: 'standalone',
  // ... other config
};

Build Configuration

Popcorn Vision’s build configuration is defined in next.config.mjs:

next.config.mjs

const nextConfig = {
  reactStrictMode: false,
  experimental: {
    staleTimes: {
      dynamic: 3600,  // Cache dynamic data for 1 hour
      static: 3600,   // Cache static data for 1 hour
    },
  },
};

export default nextConfig;

Key Configuration Options

reactStrictMode

boolean

default:"false"

React Strict Mode for identifying potential problems. Disabled by default for production performance.

experimental.staleTimes.dynamic

number

default:"3600"

Cache duration (in seconds) for dynamic routes. Set to 3600 (1 hour) to reduce TMDB API calls.

experimental.staleTimes.static

number

default:"3600"

Cache duration (in seconds) for static routes. Helps with build-time optimizations.

Optional Optimizations

For production deployments, consider these additional options:

next.config.mjs

const nextConfig = {
  reactStrictMode: false,
  
  // Image optimization
  images: {
    domains: ['image.tmdb.org'],
    formats: ['image/avif', 'image/webp'],
  },
  
  // Standalone output for Docker
  output: 'standalone',
  
  // Compression
  compress: true,
  
  // Experimental features
  experimental: {
    staleTimes: {
      dynamic: 3600,
      static: 3600,
    },
  },
  
  // Security headers
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
          {
            key: 'X-XSS-Protection',
            value: '1; mode=block',
          },
        ],
      },
    ];
  },
};

Performance Optimization

Enable Image Optimization

Configure Next.js Image component to use TMDB’s CDN:

next.config.mjs

const nextConfig = {
  images: {
    domains: ['image.tmdb.org'],
    formats: ['image/avif', 'image/webp'],
    minimumCacheTTL: 86400, // Cache images for 24 hours
  },
};

Configure Caching Strategy

Popcorn Vision uses aggressive caching to minimize API calls:

Static content: Cached indefinitely
Dynamic routes: Revalidated every hour
API responses: Cached for 1 hour

Adjust staleTimes in next.config.mjs based on your needs.

Use CDN for Static Assets

Deploy static assets (images, CSS, JS) to a CDN:

next.config.mjs

const nextConfig = {
  assetPrefix: process.env.CDN_URL || '',
};

Then set CDN_URL environment variable to your CDN domain.

Enable Compression

Ensure gzip/brotli compression is enabled:

next.config.mjs

const nextConfig = {
  compress: true, // Enable gzip compression
};

Most hosting platforms (Vercel, Netlify) enable this automatically.

Monitor Performance

Use Google Analytics (configured via GA_MEASUREMENT_ID) or integrate other monitoring tools:

Vercel Analytics
Sentry for error tracking
LogRocket for session replay

Troubleshooting

Build Fails with Environment Variable Errors

Problem: Build fails with “API_KEY is not defined” or similar.Solution: Ensure environment variables are set in your deployment platform:

Vercel: Project Settings > Environment Variables
Netlify: Site Settings > Environment Variables
Self-hosted: Set in .env.production file

Required variables:

API_URL
API_KEY
API_READ
All NEXT_PUBLIC_API_IMAGE_* variables

Images Not Loading in Production

Problem: Movie posters show broken image icons.Solutions:

Verify NEXT_PUBLIC_API_IMAGE_* variables are set

Check image domain is allowed in next.config.mjs:

images: {
  domains: ['image.tmdb.org'],
}

Ensure TMDB CDN is accessible from your deployment region

API Requests Failing (CORS Errors)

Problem: API calls fail with CORS errors in production.Cause: Direct client-side calls to TMDB API.Solution: Always use Popcorn Vision’s API routes (/api/*) instead of calling TMDB directly. These routes proxy requests server-side, avoiding CORS issues.

Slow Performance or Timeout Errors

Problem: Pages load slowly or time out.Solutions:

Enable caching: Verify staleTimes configuration in next.config.mjs
Optimize API calls: Reduce the number of API requests per page
Use a faster deployment region: Choose a region closer to TMDB servers (US East)
Implement Redis caching: Cache API responses externally

Application Crashes or Restarts

Problem: Application frequently crashes in production.Solutions:

Check memory usage - increase if needed
Review error logs for uncaught exceptions
Enable error tracking (Sentry, LogRocket)
Use a process manager (PM2) for automatic restarts
Check for rate limiting from TMDB API

Custom Domain Not Working

Problem: Custom domain shows SSL or DNS errors.Solutions:

Verify DNS records: Ensure A/CNAME records point to your host
Wait for propagation: DNS changes can take 24-48 hours
SSL certificate: Most platforms auto-generate SSL certs
Update environment: Set production URL in your config if needed

Security Best Practices

Always follow these security guidelines for production deployments.

Protect API Credentials

Never commit .env.local or .env.production to Git
Use platform environment variables for secrets
Rotate API keys periodically
Use different keys for development and production

Enable Security Headers

Add security headers in next.config.mjs:

async headers() {
  return [
    {
      source: '/(.*)',
      headers: [
        { key: 'X-Content-Type-Options', value: 'nosniff' },
        { key: 'X-Frame-Options', value: 'DENY' },
        { key: 'X-XSS-Protection', value: '1; mode=block' },
        {
          key: 'Strict-Transport-Security',
          value: 'max-age=31536000; includeSubDomains',
        },
      ],
    },
  ];
}

Rate Limiting

Popcorn Vision includes built-in rate limiting. For high-traffic sites, consider:

Implementing Redis-based rate limiting
Using a CDN with DDoS protection (Cloudflare)
Adding IP-based request throttling

Monitor for Suspicious Activity

Enable access logs
Set up alerts for unusual traffic patterns
Monitor API usage on TMDB dashboard
Use error tracking to catch security issues

Post-Deployment Checklist

After deploying, verify everything works correctly:

Next Steps

Environment Variables

Review all environment variable configuration options

TMDB API

Learn more about TMDB API usage and best practices

Get Started

Core Features

Configuration

Components

Overview

Quick Deploy Options

Vercel

Netlify

Self-Hosted

Prerequisites

Deploy to Vercel

One-Click Deploy

Manual CLI Deploy

Vercel Configuration

Deploy to Netlify

Netlify Configuration

Self-Hosted Deployment

Using Node.js Server

Using Docker

Build Configuration

Key Configuration Options

Optional Optimizations

Performance Optimization

Troubleshooting

Security Best Practices

Post-Deployment Checklist

Next Steps

Environment Variables

TMDB API

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Components

​Overview

​Quick Deploy Options

Vercel

Netlify

Self-Hosted

​Prerequisites

​Deploy to Vercel

​One-Click Deploy

​Manual CLI Deploy

​Vercel Configuration

​Deploy to Netlify

​Netlify Configuration

​Self-Hosted Deployment

​Using Node.js Server

​Using Docker

​Build Configuration

​Key Configuration Options

​Optional Optimizations

​Performance Optimization

​Troubleshooting

​Security Best Practices

​Post-Deployment Checklist

​Next Steps

Environment Variables

TMDB API

Build docs developers (and LLMs) love

Overview

Quick Deploy Options

Prerequisites

Deploy to Vercel

One-Click Deploy

Manual CLI Deploy

Vercel Configuration

Deploy to Netlify

Netlify Configuration

Self-Hosted Deployment

Using Node.js Server

Using Docker

Build Configuration

Key Configuration Options

Optional Optimizations

Performance Optimization

Troubleshooting

Security Best Practices

Post-Deployment Checklist

Next Steps