AgentSkillsCN

Docker & Environment Setup

SE104_VLEAGUE 项目的 Docker 基础设施、环境配置以及本地开发环境搭建指南。

SKILL.md
--- frontmatter
name: Docker & Environment Setup
description: Guide for Docker infrastructure, environment configuration, and local development setup for SE104_VLEAGUE

Docker & Environment Setup Skill

This skill covers all aspects of Docker infrastructure, environment configuration, and local development setup for the SE104_VLEAGUE project.

Infrastructure Overview

The project uses Docker for:

  • •PostgreSQL Database: Running PostgreSQL 15+ locally
  • •Optional Full Stack: Running API + Web + Database together

Docker Compose Configurations

Database Only (Recommended for Development)

Location: infra/docker-compose.db.yml

yaml
version: '3.8'

services:
  postgres:
    image: postgres:15
    container_name: vleague-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: vleague
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Usage:

bash
# Start PostgreSQL
docker compose -f infra/docker-compose.db.yml up -d

# Stop PostgreSQL
docker compose -f infra/docker-compose.db.yml down

# View logs
docker compose -f infra/docker-compose.db.yml logs -f

# Remove everything including volumes (WARNING: deletes data)
docker compose -f infra/docker-compose.db.yml down -v

Full Stack (Root docker-compose.yml)

Location: docker-compose.yml

Includes:

  • •PostgreSQL
  • •API (NestJS)
  • •Web (React + Vite)
bash
# Build and start all services
docker compose up --build

# Start in detached mode
docker compose up -d

# Stop all services
docker compose down

# View logs for specific service
docker compose logs api
docker compose logs web
docker compose logs postgres

Environment Variables

API Environment (.env for apps/api)

Create or copy from example:

bash
cp apps/api/.env.example apps/api/.env

Required variables:

env
# Database connection
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/vleague"

# Server configuration
PORT=8080
NODE_ENV=development

[!IMPORTANT] When running API in Docker, change localhost to postgres (the service name) in DATABASE_URL.

Docker version:

env
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/vleague"

Web Environment (.env for apps/web)

Create or copy from example:

bash
cp apps/web/.env.example apps/web/.env

Required variables:

env
# API base URL
VITE_API_BASE_URL=http://localhost:8080

[!NOTE] All Vite environment variables must be prefixed with VITE_ to be accessible in the browser.

Local Development Setup

Quick Start (Fresh Clone)

[!TIP] See docs/FRESH_CLONE_CHECKLIST.md for the complete setup guide.

  1. •

    Prerequisites:

    bash
    # Check Node.js version (>= 20)
node --version

# Enable corepack for pnpm
corepack enable
  2. •

    Install Dependencies:

    bash
    pnpm install
  3. •

    Start PostgreSQL:

    bash
    docker compose -f infra/docker-compose.db.yml up -d
  4. •

    Setup Environment Files:

    bash
    cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
  5. •

    Setup Database:

    bash
    cd apps/api
pnpm dlx prisma migrate dev --name init
pnpm run db:seed
cd ../..
  6. •

    Start Development Servers:

    bash
    pnpm dev

    This runs both API and Web in parallel:

Ports Configuration

ServicePortURL
PostgreSQL5432postgresql://localhost:5432
API8080http://localhost:8080
Web5173http://localhost:5173

[!WARNING] Port Conflicts: Make sure these ports are available on your system before starting services.

Docker Best Practices

For Development

  1. •

    Use Database-Only Docker:

    • •Run only PostgreSQL in Docker
    • •Run API and Web locally with hot-reload
    • •Faster feedback loop for development
    bash
    docker compose -f infra/docker-compose.db.yml up -d
pnpm dev
  2. •

    Check Container Status:

    bash
    docker ps                    # List running containers
docker compose ps            # List project containers
  3. •

    View Container Logs:

    bash
    docker compose logs postgres -f
  4. •

    Access PostgreSQL CLI:

    bash
    docker exec -it vleague-postgres psql -U postgres -d vleague

For Production/Testing

  1. •

    Use Full Stack Docker:

    bash
    docker compose up --build
  2. •

    Environment Variables:

    • •Use .env files or environment-specific configs
    • •Never commit .env files with secrets
  3. •

    Volume Management:

    bash
    # List volumes
docker volume ls

# Inspect volume
docker volume inspect <volume_name>

# Remove unused volumes
docker volume prune

Troubleshooting

PostgreSQL Connection Issues

Problem: Cannot connect to PostgreSQL

Solutions:

  1. •

    Check if container is running:

    bash
    docker ps | grep postgres
  2. •

    Check logs:

    bash
    docker compose -f infra/docker-compose.db.yml logs postgres
  3. •

    Verify DATABASE_URL in .env:

    env
    DATABASE_URL="postgresql://postgres:postgres@localhost:5432/vleague"
  4. •

    Test connection:

    bash
    cd apps/api
pnpm dlx prisma db pull

Port Already in Use

Problem: Port 5432/8080/5173 already in use

Solutions:

  1. •

    Find and kill the process:

    bash
    # Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 5432).OwningProcess
Stop-Process -Id <PID>

# Or change port in docker-compose
ports:
  - "5433:5432"  # Use different host port
  2. •

    Update DATABASE_URL to match new port

Docker Container Won't Start

Problem: Container exits immediately

Solutions:

  1. •

    Check logs for errors:

    bash
    docker compose logs
  2. •

    Remove and recreate:

    bash
    docker compose down -v
docker compose up --build
  3. •

    Check disk space:

    bash
    docker system df
docker system prune  # Clean up

Database Data Persists After down

This is expected behavior - Docker volumes persist data.

To completely reset:

bash
docker compose -f infra/docker-compose.db.yml down -v
docker compose -f infra/docker-compose.db.yml up -d
cd apps/api
pnpm dlx prisma migrate dev
pnpm run db:seed

[!CAUTION] Data Loss: The -v flag removes volumes and deletes all database data. Use with caution.

Environment-Specific Configurations

Development

env
# apps/api/.env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/vleague"
PORT=8080
NODE_ENV=development

Docker Compose

env
# apps/api/.env (when running in Docker)
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/vleague"
PORT=8080
NODE_ENV=production

CI/CD (GitHub Actions)

yaml
# .github/workflows/ci.yml
env:
  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/vleague_test

Docker Compose Commands Reference

bash
# Start services
docker compose up                    # Foreground
docker compose up -d                 # Background (detached)
docker compose up --build            # Rebuild images

# Stop services
docker compose stop                  # Stop without removing
docker compose down                  # Stop and remove containers
docker compose down -v               # Stop and remove volumes (DELETE DATA)

# View status and logs
docker compose ps                    # List containers
docker compose logs                  # All logs
docker compose logs -f api           # Follow API logs
docker compose logs --tail=100 web   # Last 100 lines

# Execute commands in containers
docker compose exec api sh           # Shell in API container
docker compose exec postgres psql -U postgres -d vleague

# Restart services
docker compose restart api           # Restart specific service
docker compose restart               # Restart all

# Build
docker compose build                 # Build all services
docker compose build --no-cache api  # Rebuild without cache

Development Workflows

Workflow 1: Local Development (Recommended)

bash
# 1. Start only PostgreSQL
docker compose -f infra/docker-compose.db.yml up -d

# 2. Run API and Web locally
pnpm dev

# Hot-reload enabled for both API and Web

Advantages:

  • •✅ Fast hot-reload
  • •✅ Easy debugging
  • •✅ Direct access to code

Workflow 2: Full Docker

bash
# Run everything in Docker
docker compose up --build

# Rebuild on code changes
docker compose up --build

Advantages:

  • •✅ Production-like environment
  • •✅ Consistent across machines

Disadvantages:

  • •❌ Slower feedback loop
  • •❌ Need to rebuild on changes

Workflow 3: Hybrid

bash
# PostgreSQL in Docker
docker compose -f infra/docker-compose.db.yml up -d

# API locally
cd apps/api
pnpm dev

# Web in Docker or locally
cd apps/web
pnpm dev

Health Checks

Check PostgreSQL

bash
# Via Docker
docker compose exec postgres pg_isready -U postgres

# Via psql
docker exec -it vleague-postgres psql -U postgres -d vleague -c "SELECT 1;"

Check API

bash
curl http://localhost:8080/health

Should return: {"status":"ok"}

Check Web

Open browser: http://localhost:5173

File Locations Reference

PurposeFile Path
Database Docker Composeinfra/docker-compose.db.yml
Full Stack Docker Composedocker-compose.yml
API Environmentapps/api/.env
API Environment Exampleapps/api/.env.example
Web Environmentapps/web/.env
Web Environment Exampleapps/web/.env.example
Fresh Clone Guidedocs/FRESH_CLONE_CHECKLIST.md
Local Dev Guidedocs/LOCAL_DEV.md

Common Issues and Solutions

"Prisma Client Not Found"

Cause: Prisma Client not generated after schema changes

Solution:

bash
cd apps/api
pnpm dlx prisma generate

"Migration Failed"

Cause: Database state conflicts with migrations

Solution:

bash
cd apps/api
pnpm dlx prisma migrate reset  # WARNING: Deletes all data
pnpm run db:seed

".env File Not Loaded"

Cause: Missing or incorrectly named file

Solution:

  1. •Check file name is exactly .env (not .env.txt)
  2. •Check file location matches service root
  3. •Restart the development server

Docker Volume Permission Issues

Cause: Volume ownership conflicts (rare on Windows)

Solution:

bash
docker compose down -v
docker volume prune
docker compose up -d