Skip to main content
The boilerplate includes a Dev Container configuration for a consistent, reproducible development environment using Docker.

​
What is a Dev Container?

A Dev Container is a Docker-based development environment that runs inside VS Code. It provides:
  • Consistent environment across all developers
  • Zero manual setup - dependencies are pre-installed
  • Isolation from your local system
  • Reproducibility - same environment every time

​
What’s Included

The Dev Container includes:

Ubuntu

Latest Ubuntu base image

Node.js

Managed via Volta for version consistency

PostgreSQL 18

Pre-configured database instance

Python 3.12

Via pyenv for backend integration examples

Zsh

Oh My Zsh with autosuggestions and syntax highlighting

Git

Pre-installed and configured

​
Prerequisites

Before using the Dev Container, install:
  1. VS Code
  2. Dev Containers extension
  3. Docker Desktop
Windows users: Docker Desktop requires WSL 2. Follow the Windows setup guide.

​
Quick Start

​
1. Open in Dev Container

In VS Code:
  1. Open the boilerplate repository
  2. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
  3. Select “Dev Containers: Reopen in Container”
  4. Wait for the container to build (first time takes ~5 minutes)

​
2. Install Prerequisites

Once inside the container, run: 
volta install node
pyenv install 3.12
pyenv global 3.12
These commands install the exact Node.js and Python versions specified in the project configuration.

​
3. Configure Environment

Copy the example environment file: 
cp .env.example .env
Then edit .env to add your Google OAuth credentials:
.env
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
Get credentials from Google Cloud Console. Set the redirect URI to http://localhost:3000/api/auth/callback/google.

​
4. Install and Run

npm install
npm run db:push    # Push schema to PostgreSQL
npm run dev        # Start dev server on :3000
The app is now running at http://localhost:3000.

​
Dev Container Configuration

​
Docker Compose

The Dev Container uses Docker Compose to run multiple services:
.devcontainer/docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ../..:/workspaces:cached
    command: sleep infinity
    networks:
      - dc-ubuntu-pg-network
    depends_on:
      - postgres

  postgres:
    image: postgres:18
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    networks:
      - dc-ubuntu-pg-network

​
devcontainer.json

The devcontainer.json file configures VS Code and the container:
.devcontainer/devcontainer.json
{
  "name": "Development Environment",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
  "features": {
    "ghcr.io/devcontainers/features/common-utils": {
      "installZsh": true,
      "installOhMyZsh": true,
      "configureZshAsDefaultShell": true
    },
    "ghcr.io/devcontainers-extra/features/zsh-plugins:0": {
      "plugins": "zsh-autosuggestions zsh-syntax-highlighting"
    }
  },
  "customizations": {
    "vscode": {
      "settings": {
        "editor.tabSize": 4,
        "terminal.integrated.defaultProfile.linux": "zsh"
      }
    }
  },
  "postCreateCommand": "chmod +x .devcontainer/scripts/post-create.sh && .devcontainer/scripts/post-create.sh"
}

​
Database Connection

The PostgreSQL instance is accessible within the container:
.env
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/postgres?schema=public"
The hostname is postgres (the service name in Docker Compose), not localhost.

​
Accessing PostgreSQL

Connect to the database using the terminal: 
psql -h postgres -U postgres -d postgres
Or use Drizzle Studio: 
npm run db:studio

​
Customizing the Dev Container

​
Add VS Code Extensions

Install extensions automatically when the container starts:
.devcontainer/devcontainer.json
{
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ]
    }
  }
}

​
Add System Packages

Install additional packages in the Dockerfile:
.devcontainer/Dockerfile
RUN apt-get update && apt-get install -y \
    curl \
    git \
    vim \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

​
Add Node.js Tools

Install global npm packages in the post-create script:
.devcontainer/scripts/post-create.sh
#!/bin/bash

volta install node
npm install -g typescript tsx pnpm

​
Troubleshooting

​
Container Won’t Start

Problem: Docker fails to start the container. Solution:
  1. Ensure Docker Desktop is running
  2. Check Docker has enough resources (CPU, memory, disk)
  3. Rebuild the container: Cmd+Shift+P → “Dev Containers: Rebuild Container”

​
Port Already in Use

Problem: Port 3000 or 5432 is already in use. Solution: Stop the conflicting service on your local machine, or change the port in docker-compose.yml: 
ports:
  - "3001:3000"  # Map container port 3000 to host port 3001

​
Can’t Connect to PostgreSQL

Problem: npm run db:push fails with connection error. Solution:
  1. Verify PostgreSQL is running: docker ps
  2. Check DATABASE_URL uses postgres as hostname (not localhost)
  3. Restart the container: Cmd+Shift+P → “Dev Containers: Rebuild Container”

​
Slow Performance (Mac)

Problem: File system operations are slow on macOS. Solution: The :cached flag in docker-compose.yml improves performance: 
volumes:
  - ../..:/workspaces:cached
For even better performance, use named volumes for node_modules: 
volumes:
  - ../..:/workspaces:cached
  - node_modules:/workspaces/auth-ui-boilerplate/node_modules

​
Container Runs Out of Disk Space

Problem: Docker runs out of disk space. Solution: Clean up unused Docker resources: 
docker system prune -a --volumes
This removes all unused images, containers, and volumes. Make sure you don’t have important data in stopped containers.

​
Manual Setup (Without Dev Container)

If you prefer not to use the Dev Container:
  1. Install Node.js 22+ and PostgreSQL locally
  2. Copy .env.example to .env
  3. Update DATABASE_URL to point to your local PostgreSQL: 
    DATABASE_URL="postgresql://your_user:your_password@localhost:5432/your_db"
  4. Run: 
    npm install
npm run db:push
npm run dev

​
Benefits of Dev Containers

All team members use the exact same environment, eliminating “works on my machine” issues.
New developers can start contributing in minutes instead of hours setting up dependencies.
Dependencies are isolated from your local machine, preventing version conflicts.
The environment is defined in code, so it can be versioned and shared.
Your local environment matches CI/CD, reducing deployment surprises.

​
Next Steps

Project Structure

Understand the codebase organization

Database

Learn how to work with Drizzle ORM

Customization

Customize the boilerplate for your app

Build docs developers (and LLMs) love

Get started for freeTalk to us