Docker Deployment

Deploy PC Fix using Docker Compose for development and production

PC Fix includes a complete Docker Compose configuration for running the entire stack (PostgreSQL, API, and Web) in containers. This guide covers Docker-based deployment for both local development and production environments.

Overview

The Docker setup provides three services:

• postgres: PostgreSQL 15 Alpine database
• api: Express backend (Node.js)
• web: Astro frontend with React islands

All services are connected via Docker’s internal network, enabling seamless communication without exposing unnecessary ports.

Prerequisites

1. Install Docker

   Install Docker Desktop or Docker Engine:

   • Docker Desktop (Windows/Mac/Linux)
   • Docker Engine (Linux servers)
2. Install Docker Compose

   Docker Compose is included in Docker Desktop. For Linux:

   sudo apt-get install docker-compose-plugin
   
3. Verify Installation

   docker --version
   docker compose version
   

Docker Compose Configuration

The docker-compose.yml file defines the complete stack:

docker-compose.yml

services:
  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    container_name: pcfix-postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password123
      POSTGRES_DB: pcfix_db
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  # Backend API
  api:
    build:
      context: ./packages/api
      target: dev
    container_name: pcfix-api
    ports:
      - "3001:3001"
    environment:
      DATABASE_URL: "postgresql://admin:password123@postgres:5432/pcfix_db?schema=public"
      PORT: 3001
      JWT_SECRET: "your-jwt-secret"
      FRONTEND_URL: "http://localhost:4321"
    volumes:
      - ./packages/api:/app
      - /app/node_modules
    depends_on:
      - postgres
    command: sh -c "npx prisma migrate deploy && npm run dev"

  # Frontend Web
  web:
    build:
      context: ./packages/web
      target: dev
    container_name: pcfix-web
    ports:
      - "4321:4321"
    environment:
      PUBLIC_API_URL: "http://localhost:3001/api"
      SSR_API_URL: "http://api:3001/api"
    volumes:
      - ./packages/web:/app
      - /app/node_modules
    depends_on:
      - api

volumes:
  postgres_data:

Development Deployment

Initial Setup

1. Clone Repository

   git clone https://github.com/martin-ratti/PCFIX-Baru.git
   cd PCFIX-Baru
   
2. Configure Environment Variables

   Create .env files for both packages (see Environment Setup):

   # API environment
   cp packages/api/.env.example packages/api/.env
   
   # Web environment
   cp packages/web/.env.example packages/web/.env
   

   Edit both files with your actual credentials.

3. Build and Start Containers

   docker-compose up --build
   

   This will:

   • Build Docker images for API and Web
   • Start PostgreSQL container
   • Run Prisma migrations
   • Start API on port 3001
   • Start Web on port 4321

Access Services

Once running, access:

• Frontend: http://localhost:4321
• API: http://localhost:3001
• API Health Check: http://localhost:3001/health
• PostgreSQL: localhost:5432 (use any DB client)

Use Prisma Studio to explore the database:

docker exec -it pcfix-api npx prisma studio

Access at http://localhost:5555

Docker Commands Reference

Basic Operations

Start Services

# Start all services in detached mode
docker-compose up -d

# Start and rebuild images
docker-compose up --build

# Start specific service
docker-compose up web

Container Management

# List running containers
docker-compose ps

# Execute command in container
docker exec -it pcfix-api npm run db:studio

# Access container shell
docker exec -it pcfix-api sh

# View container resource usage
docker stats

Database Operations

# Run migrations
docker exec -it pcfix-api npx prisma migrate deploy

# Generate Prisma Client
docker exec -it pcfix-api npx prisma generate

# Seed database
docker exec -it pcfix-api npx prisma db seed

# Reset database (WARNING: deletes all data)
docker exec -it pcfix-api npx prisma migrate reset

Production Deployment

Docker Production Build

For production, create a docker-compose.prod.yml:

docker-compose.prod.yml

services:
  postgres:
    image: postgres:15-alpine
    container_name: pcfix-postgres-prod
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - postgres_prod_data:/var/lib/postgresql/data
    restart: always

  api:
    build:
      context: ./packages/api
      target: production
    container_name: pcfix-api-prod
    environment:
      NODE_ENV: production
      DATABASE_URL: ${DATABASE_URL}
      JWT_SECRET: ${JWT_SECRET}
      PORT: 3002
    ports:
      - "3002:3002"
    depends_on:
      - postgres
    restart: always

  web:
    build:
      context: ./packages/web
      target: production
    container_name: pcfix-web-prod
    environment:
      PUBLIC_API_URL: ${PUBLIC_API_URL}
      SSR_API_URL: http://api:3002/api
    ports:
      - "4321:4321"
    depends_on:
      - api
    restart: always

volumes:
  postgres_prod_data:

Deploy to Production

1. Set Production Environment

   Create .env.production with production credentials:

   DB_USER=prod_admin
   DB_PASSWORD=secure_password_here
   DB_NAME=pcfix_production
   DATABASE_URL=postgresql://prod_admin:secure_password_here@postgres:5432/pcfix_production
   JWT_SECRET=production-jwt-secret-change-this
   PUBLIC_API_URL=https://api.yoursite.com/api
   
2. Build Production Images

   docker-compose -f docker-compose.prod.yml build
   
3. Start Production Stack

   docker-compose -f docker-compose.prod.yml up -d
   
4. Run Migrations

   docker exec -it pcfix-api-prod npx prisma migrate deploy
   

Health Monitoring

Add health checks to docker-compose.prod.yml:

api:
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:3002/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s

web:
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:4321"]
    interval: 30s
    timeout: 10s
    retries: 3

Alternative Deployment Options

Vercel (Frontend)

Deploy the web package to Vercel:

1. Install Vercel CLI:

npm i -g vercel

2. Deploy from packages/web:

cd packages/web
vercel

3. Set environment variables in Vercel dashboard:

• PUBLIC_API_URL
• PUBLIC_GOOGLE_CLIENT_ID
• PUBLIC_SENTRY_DSN

PC Fix already includes @astrojs/vercel adapter in astro.config.mjs

Railway (Backend)

Deploy the API to Railway:

1. Sign up at railway.app
2. Create new project from GitHub repo
3. Add PostgreSQL service
4. Configure environment variables
5. Deploy

Railway will automatically:

• Detect Node.js project
• Install dependencies
• Run Prisma migrations
• Start the server

Docker + VPS

Deploy to a VPS (DigitalOcean, AWS EC2, etc.):

1. SSH into your server
2. Install Docker and Docker Compose
3. Clone repository
4. Configure production environment
5. Use docker-compose.prod.yml
6. Set up reverse proxy (Nginx/Caddy)
7. Configure SSL certificates (Let’s Encrypt)

Troubleshooting

Port already in use

If ports 3001, 4321, or 5432 are in use:

# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

# Or change ports in docker-compose.yml

Container won't start

Check container logs:

docker-compose logs api
docker-compose logs web
docker-compose logs postgres

Common issues:

• Missing environment variables
• Database connection failed
• Port conflicts

Database connection refused

Ensure:

• PostgreSQL container is running: docker ps
• Use host postgres in DATABASE_URL (not localhost)
• Wait for postgres to be ready before API starts

Changes not reflecting

Hot reload requires volumes to be mounted correctly:

# Rebuild without cache
docker-compose build --no-cache

# Restart services
docker-compose restart

Next Steps

Database Migrations

Learn how to manage schema changes

Testing

Run tests in Docker containers

Environment Setup

Configure environment variables

Architecture

Understand the system architecture