Docker Setup

Vercel For Frontend uses Docker to build frontend projects in isolated containers. The deploy service creates temporary Docker images for each project, runs the build, and extracts the output.

How Docker is Used

The build process (deploy-service/src/utils/buildProject.ts:22) follows these steps:

Create Dockerfile: Generates a Node.js 20 Alpine-based Dockerfile in the project directory
Build Image: docker build -t frontend-build-{id} .
Create Container: docker create --name build-container-{id}
Extract Build Output: docker cp the /app/build or /app/dist folder
Cleanup: Remove container and image

Docker must be installed and the daemon must be running for builds to work.

Installation

macOS
Linux (Ubuntu/Debian)
Linux (CentOS/RHEL)
Windows

Download Docker Desktop

Download Docker Desktop from docker.com.

Install Docker

Open the downloaded .dmg file
Drag Docker to Applications folder
Launch Docker from Applications
Follow the setup wizard

Start Docker

Docker Desktop should start automatically. Look for the Docker icon in the menu bar.

Allow Docker to access your filesystem when prompted.

Verify Installation

docker --version
docker run hello-world

You should see version information and a welcome message.

Remove Old Versions

sudo apt-get remove docker docker-engine docker.io containerd runc

Install Dependencies

sudo apt-get update
sudo apt-get install -y \
  ca-certificates \
  curl \
  gnupg \
  lsb-release

Add Docker's Official GPG Key

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Set Up Repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Start Docker Service

sudo systemctl start docker
sudo systemctl enable docker

Verify Installation

sudo docker run hello-world

Remove Old Versions

sudo yum remove docker docker-client docker-client-latest docker-common \
  docker-latest docker-latest-logrotate docker-logrotate docker-engine

Install Dependencies

sudo yum install -y yum-utils

Add Docker Repository

sudo yum-config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

Install Docker

sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Start Docker Service

sudo systemctl start docker
sudo systemctl enable docker

Verify Installation

sudo docker run hello-world

System Requirements

Ensure you have:

Windows 10 64-bit: Pro, Enterprise, or Education (Build 19041+)
Or Windows 11 64-bit
WSL 2 feature enabled
Virtualization enabled in BIOS

Enable WSL 2

Open PowerShell as Administrator:

wsl --install

Restart your computer if prompted.

Download Docker Desktop

Download from docker.com.

Install Docker Desktop

Run the installer
Ensure “Use WSL 2 instead of Hyper-V” is checked
Follow the installation wizard
Restart your computer

Start Docker Desktop

Launch Docker Desktop from the Start menu. Wait for it to start completely.

Verify Installation

Open PowerShell or CMD:

docker --version
docker run hello-world

Post-Installation Setup

Add User to Docker Group (Linux)

Avoid using sudo for every Docker command:

sudo usermod -aG docker $USER
newgrp docker

Log out and back in for changes to take effect.

The docker group grants privileges equivalent to root. Only add trusted users.

Test without sudo:

docker run hello-world

Configure Docker Daemon

Optimize Docker for build performance:

Linux
macOS/Windows

Create or edit /etc/docker/daemon.json:

/etc/docker/daemon.json

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "default-address-pools": [
    {
      "base": "172.17.0.0/16",
      "size": 24
    }
  ]
}

Restart Docker:

sudo systemctl restart docker

Open Docker Desktop settings:

Click Docker icon in system tray
Go to Settings → Docker Engine
Add configuration:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Click “Apply & Restart”

Testing Docker for Builds

Test the exact build process used by the platform:

Create Test Project

mkdir test-build
cd test-build

Create a simple package.json:

package.json

{
  "name": "test-project",
  "version": "1.0.0",
  "scripts": {
    "build": "echo 'Build successful' && mkdir -p dist && echo '<h1>Test</h1>' > dist/index.html"
  }
}

Create Dockerfile

Dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

This matches the Dockerfile generated in buildProject.ts:12.

Build Image

docker build -t test-frontend-build .

Should complete without errors.

Create Container

docker create --name test-container test-frontend-build

Extract Build Output

docker cp test-container:/app/dist ./output

Verify output:

ls -la output/
cat output/index.html

Cleanup

docker rm test-container
docker rmi test-frontend-build
rm -rf output
cd ..
rm -rf test-build

If all steps succeed, Docker is correctly configured for the platform’s build process.

Docker Daemon Management

Check Docker Status

sudo systemctl status docker

Start/Stop Docker

# Start
sudo systemctl start docker

# Stop
sudo systemctl stop docker

# Restart
sudo systemctl restart docker

Auto-Start on Boot

Linux
macOS/Windows

sudo systemctl enable docker

Monitoring and Cleanup

Monitor Running Builds

# List running containers
docker ps

# Watch container logs
docker logs -f build-container-{id}

# Monitor resource usage
docker stats

Clean Up Build Artifacts

The platform automatically removes containers and images after builds, but orphaned resources can accumulate:

# Remove stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Remove build cache
docker builder prune -f

# Nuclear option (removes everything)
docker system prune -a --volumes -f

docker system prune removes ALL unused containers, images, networks, and volumes. Use with caution.

Automated Cleanup

Schedule regular cleanup with cron (Linux/macOS):

crontab -e

Add:

# Clean Docker weekly on Sunday at 2 AM
0 2 * * 0 docker system prune -f

Troubleshooting

Docker Daemon Not Running

Error: Cannot connect to the Docker daemonSolutions:

Linux
macOS/Windows

# Check status
sudo systemctl status docker

# Start daemon
sudo systemctl start docker

# Check logs
sudo journalctl -u docker -n 50

Permission Denied

Error: permission denied while trying to connect to the Docker daemon socketSolutions:

# Add user to docker group
sudo usermod -aG docker $USER

# Apply group changes
newgrp docker

# Or log out and back in

# Test
docker ps

Build Failed

Error: Execution error: Command failedSolutions:

Check Docker daemon is running: docker info
Verify Node.js image is available: docker pull node:20-alpine
Check disk space: df -h
View build logs: docker logs build-container-{id}

Test build manually:

cd dist/output/{id}
docker build -t test-build .

Out of Disk Space

Error: no space left on deviceSolutions:

Check Docker disk usage: docker system df
Clean up:
```
docker system prune -a --volumes
```
Increase Docker Desktop disk limit (Settings → Resources → Disk image size)
Move Docker data directory (Linux):
/etc/docker/daemon.json
```
{
  "data-root": "/new/path/to/docker"
}
```

Build Timeout

Symptom: Builds hang indefinitelySolutions:

Check container status: docker ps -a | grep build-container

Kill stuck containers:

docker kill build-container-{id}
docker rm build-container-{id}

Increase timeout in buildProject.ts (modify exec options)
Check network connectivity for npm install

Cannot Remove Container

Error: Error response from daemon: container is runningSolutions:

# Stop container first
docker stop build-container-{id}

# Force remove
docker rm -f build-container-{id}

# If still stuck, restart Docker daemon
sudo systemctl restart docker

Performance Optimization

Use BuildKit

Enable Docker BuildKit for faster builds:

export DOCKER_BUILDKIT=1

Or configure permanently:

/etc/docker/daemon.json

{
  "features": {
    "buildkit": true
  }
}

Allocate More Resources

macOS/Windows
Linux

Docker Desktop → Settings → Resources:

CPUs: Allocate 50-75% of available cores
Memory: At least 4GB, 8GB recommended
Swap: 2GB
Disk: 60GB+ for multiple builds

Docker uses host resources directly. Ensure sufficient:

# Check resources
free -h
df -h
nproc

Cache npm Dependencies

Modify the Dockerfile to cache node_modules:

FROM node:20-alpine AS builder
WORKDIR /app

# Copy package files first (cached layer)
COPY package*.json ./
RUN npm ci --only=production

# Copy source (changes frequently)
COPY . .
RUN npm run build

Security Best Practices

Run Rootless Docker

Run Docker daemon as non-root user:

# Install rootless Docker
curl -fsSL https://get.docker.com/rootless | sh

# Enable at startup
systemctl --user enable docker

Scan Images for Vulnerabilities

# Scan Node.js image
docker scan node:20-alpine

# Enable automatic scanning
docker scan --accept-license

Limit Container Resources

Prevent resource exhaustion:

docker run --memory="512m" --cpus="1.0" \
  image-name

Use Read-Only Filesystem

docker run --read-only \
  --tmpfs /tmp \
  image-name

Get Started

Core Features

Configuration

Guides

How Docker is Used

Installation

Post-Installation Setup

Add User to Docker Group (Linux)

Configure Docker Daemon

Testing Docker for Builds

Docker Daemon Management

Check Docker Status

Start/Stop Docker

Auto-Start on Boot

Monitoring and Cleanup

Monitor Running Builds

Clean Up Build Artifacts

Automated Cleanup

Troubleshooting

Performance Optimization

Use BuildKit

Allocate More Resources

Cache npm Dependencies

Security Best Practices

Run Rootless Docker

Scan Images for Vulnerabilities

Limit Container Resources

Use Read-Only Filesystem

Next Steps

Environment Variables

Quick Start

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Guides

​How Docker is Used

​Installation

​Post-Installation Setup

​Add User to Docker Group (Linux)

​Configure Docker Daemon

​Testing Docker for Builds

​Docker Daemon Management

​Check Docker Status

​Start/Stop Docker

​Auto-Start on Boot

​Monitoring and Cleanup

​Monitor Running Builds

​Clean Up Build Artifacts

​Automated Cleanup

​Troubleshooting

​Performance Optimization

​Use BuildKit

​Allocate More Resources

​Cache npm Dependencies

​Security Best Practices

Run Rootless Docker

Scan Images for Vulnerabilities

Limit Container Resources

Use Read-Only Filesystem

​Next Steps

Environment Variables

Quick Start

Build docs developers (and LLMs) love

How Docker is Used

Installation

Post-Installation Setup

Add User to Docker Group (Linux)

Configure Docker Daemon

Testing Docker for Builds

Docker Daemon Management

Check Docker Status

Start/Stop Docker

Auto-Start on Boot

Monitoring and Cleanup

Monitor Running Builds

Clean Up Build Artifacts

Automated Cleanup

Troubleshooting

Performance Optimization

Use BuildKit

Allocate More Resources

Cache npm Dependencies

Security Best Practices

Next Steps