How to Integrate Bolt.new with Docker

Docker configuration files need to be added to your project locally — you cannot run Docker commands from Bolt's WebContainer browser environment. The first step is getting your Bolt project onto your local machine through GitHub. In Bolt, open the Git panel and push your project to a GitHub repository if you have not already. Once the push completes, open a terminal on your local machine and clone the repository. Navigate into the project directory and install dependencies to verify the project is intact. At this point, verify that the Bolt project builds successfully in a clean local environment by running the build command. This is an important check because Bolt's WebContainer and a local Node.js installation can sometimes behave differently — TypeScript strict mode settings, peer dependency requirements, and environment variable handling may surface issues that were hidden in Bolt's environment. Fix any build errors before proceeding to Docker configuration. Note a critical architectural difference that Docker resolves: in Bolt's WebContainer, native Node.js modules that require compilation (like bcrypt, sharp, or canvas) fail because WebContainers enforce a no-addons flag. In a Docker container running real Node.js on Linux, these modules compile and run normally. If your Bolt project had to use JavaScript alternatives to these modules (e.g., bcryptjs instead of bcrypt), you can switch to the native version after adding Docker. However, if the app uses Supabase and only makes HTTP calls, no changes are needed — the exported code works as-is.

1# Clone and set up the project locally:
2git clone https://github.com/yourusername/your-bolt-project.git
3cd your-bolt-project
4npm install
5
6# Verify the project builds without errors:
7npm run build
8
9# If build succeeds, you should see a dist/ directory (Vite)
10# or a .next/ directory (Next.js)
11ls -la

The Dockerfile defines how to package your Bolt app into a container image. The multi-stage build pattern is the best practice for production containers — a separate build stage with all development dependencies produces a smaller, more secure final image. For Vite projects (Bolt's default when you ask for a React app), the output is a folder of static HTML, CSS, and JavaScript files. The most efficient way to serve these is with nginx, a high-performance web server. The build stage uses Node.js to run npm run build, and the final stage copies only the built files into an nginx container. The resulting image is typically 20-40 MB — much smaller than a Node.js-based server. For Next.js projects (Bolt generates these when you request Next.js or server-side features), the app needs to run as a Node.js server since it may include server-side rendering or API routes. The multi-stage build installs dependencies, runs npm run build with the standalone output mode enabled in next.config.js, and the final stage runs only the standalone server output. The Dockerfiles below are production-ready for Bolt-generated projects. Choose the appropriate one based on your project type — you can determine this by checking whether your project has a vite.config.ts (Vite) or next.config.js (Next.js) file.

1# Dockerfile for Vite/React Bolt projects (static output served by nginx):
2
3# Build stage
4FROM node:18-alpine AS builder
5
6WORKDIR /app
7
8# Copy package files first for better layer caching
9COPY package*.json ./
10RUN npm ci --only=production=false
11
12# Copy source files and build
13COPY . .
14RUN npm run build
15
16# Production stage
17FROM nginx:alpine AS production
18
19# Copy built files from build stage
20COPY --from=builder /app/dist /usr/share/nginx/html
21
22# Copy nginx config for SPA routing
23COPY nginx.conf /etc/nginx/conf.d/default.conf
24
25EXPOSE 80
26
27CMD ["nginx", "-g", "daemon off;"]

The Dockerfile alone is not quite complete — Vite SPAs need a special nginx configuration for client-side routing to work, and all projects benefit from a .dockerignore file to speed up builds. For Vite Bolt projects using React Router or Wouter for navigation, nginx needs to be configured to serve index.html for all routes (not just the root path). Without this, navigating directly to a URL like /dashboard will return a 404 from nginx. The nginx.conf below fixes this with a try_files directive that falls back to index.html for any unresolved path. The .dockerignore file is conceptually similar to .gitignore — it prevents specified directories and files from being sent to the Docker daemon as part of the build context. Including node_modules/ (typically 200-500 MB) in the build context makes every docker build command take minutes to upload, even if nothing changed. Excluding it ensures Docker only processes your source files. For Next.js Bolt projects, you also need to update next.config.js to enable standalone output mode. This causes Next.js to output a self-contained server in .next/standalone that can be deployed without installing node_modules — making the Docker image significantly smaller and faster to start. After adding these files, commit them to your repository and push to GitHub. Bolt will see these new files when you next pull from GitHub, so the Docker configuration becomes part of the Bolt project going forward.

1# nginx.conf for Vite SPA routing:
2server {
3    listen 80;
4    server_name _;
5    root /usr/share/nginx/html;
6    index index.html;
7
8    # Serve static files directly, fallback to index.html for SPA routing
9    location / {
10        try_files $uri $uri/ /index.html;
11    }
12
13    # Cache static assets for 1 year
14    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
15        expires 1y;
16        add_header Cache-Control "public, immutable";
17    }
18
19    # Don't cache HTML
20    location ~* \.html$ {
21        expires -1;
22        add_header Cache-Control "no-store";
23    }
24}
25
26---
27
28# .dockerignore:
29node_modules
30dist
31.next
32build
33.env
34.env.local
35.env.*.local
36npm-debug.log*
37.DS_Store
38.git
39.gitignore
40README.md
41*.md

If your Bolt project uses Supabase in production but you want to run a real database locally (outside Bolt's WebContainer limitations), docker-compose makes this straightforward. You can run your Bolt app container alongside a PostgreSQL container on your local machine, replicating the production architecture without any cloud services. An important context here: in Bolt's WebContainer, you cannot use raw TCP database connections — the standard pg npm package that connects directly to PostgreSQL fails because WebContainers cannot open TCP sockets. Bolt solves this by using Supabase's HTTP-based PostgREST interface. But once you have exported your project and are running it in Docker, real TCP connections work perfectly. This means locally with Docker, you can run a PostgreSQL container and connect to it using the pg package or Prisma directly — a workflow impossible in Bolt's browser environment. The docker-compose.yml below defines two services: your Bolt app (built from the Dockerfile) and a PostgreSQL database. The app service depends on the database, so docker-compose starts PostgreSQL first. Environment variables pass the database connection string to the app. A named volume persists the database data between container restarts so you do not lose your development data. Note that this docker-compose setup is for local development only — it is not the recommended production deployment pattern. For production, use a managed database (Supabase, Neon, PlanetScale) and deploy the app container separately to your chosen cloud platform.

1# docker-compose.yml for local development:
2version: '3.8'
3
4services:
5  app:
6    build: .
7    ports:
8      - '3000:80'    # Vite nginx: 80
9      # - '3000:3000'  # Next.js: 3000
10    environment:
11      - NODE_ENV=development
12      - VITE_SUPABASE_URL=http://localhost:54321  # Local Supabase alternative
13      # Or use Postgres directly (requires code changes from Supabase HTTP client):
14      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp
15    depends_on:
16      db:
17        condition: service_healthy
18    volumes:
19      - ./src:/app/src  # Mount src for hot-reloading (dev mode)
20
21  db:
22    image: postgres:15-alpine
23    environment:
24      POSTGRES_DB: myapp
25      POSTGRES_USER: postgres
26      POSTGRES_PASSWORD: postgres
27    ports:
28      - '5432:5432'  # Expose for direct database client access
29    volumes:
30      - postgres_data:/var/lib/postgresql/data
31    healthcheck:
32      test: ['CMD-SHELL', 'pg_isready -U postgres']
33      interval: 10s
34      timeout: 5s
35      retries: 5
36
37volumes:
38  postgres_data:

With a working Dockerfile, deploying to cloud container platforms is straightforward. The most developer-friendly options for Bolt projects are Railway and Render, which connect directly to your GitHub repository and build the Docker image automatically on every push. This creates the same automation you get from Bolt's publish button, but via Docker with container-platform capabilities. For Railway: create a new project at railway.app, click 'Deploy from GitHub repo,' select the repository, and Railway automatically detects the Dockerfile and builds it. Add environment variables in Railway's 'Variables' tab (SUPABASE_URL, SUPABASE_ANON_KEY, and any other keys your app needs). Railway provides a public URL with automatic HTTPS. The Starter plan is free with limited usage. For Google Cloud Run (for higher traffic or team use): build and push the Docker image to Google Container Registry, then create a Cloud Run service pointing to that image. Cloud Run scales to zero when not in use, making it cost-effective for Bolt prototypes that do not receive constant traffic. Regarding the WebContainer limitation and deployment: Bolt's browser-based development environment cannot receive incoming webhooks, run persistent background processes, or use raw TCP sockets. Once your app is deployed as a Docker container, all of these work normally. If your Bolt app integrated with services that require webhooks (Stripe, GitHub Apps, Twilio), register your Docker deployment URL as the webhook endpoint — not the Bolt preview URL. Deploy first, then configure the webhook URLs.

1# Build and push Docker image to Docker Hub (then deploy anywhere):
2docker build -t yourusername/your-bolt-app:latest .
3docker push yourusername/your-bolt-app:latest
4
5# Or build and deploy to Google Cloud Run:
6gcloud auth login
7gcloud config set project your-project-id
8
9docker build -t gcr.io/your-project-id/bolt-app:latest .
10docker push gcr.io/your-project-id/bolt-app:latest
11
12gcloud run deploy bolt-app \
13  --image gcr.io/your-project-id/bolt-app:latest \
14  --platform managed \
15  --region us-central1 \
16  --allow-unauthenticated \
17  --set-env-vars SUPABASE_URL=https://yourproject.supabase.co