task_receipts/DOCKER.md

Docker Setup for Task Receipts

This document explains how to build and run the Task Receipts application using Docker.

Prerequisites

• Docker installed and running
• Docker Compose (usually included with Docker Desktop)

Quick Start

Option 1: Using Docker Compose (Recommended)

1. Build and run both services:

   docker-compose up --build
   

2. Run in background:

   docker-compose up -d --build
   

3. Stop services:

   docker-compose down
   

Option 2: Using the Build Script

1. Build both images:

   ./build-docker.sh
   

2. Build with specific version:

   ./build-docker.sh v1.0.0
   

3. Run containers individually:

   # Run server
   docker run -p 4000:4000 task-receipts-server:latest
   
   # Run client (in another terminal)
   docker run -p 80:80 task-receipts-client:latest
   

Services

Server

• Port: 4000
• Health Check: GraphQL endpoint at /graphql
• Database: SQLite (persisted in ./server/data)
• Features:
  • GraphQL API
  • YAML import/export
  • Receipt printing
  • Database management

Client

• Port: 80
• Web Server: Nginx
• Features:
  • React application
  • Material-UI components
  • Apollo Client for GraphQL

Docker Images

Client Image (task-receipts-client)

• Base: nginx:stable (Ubuntu-based)
• Build: Multi-stage build with Node.js 18 (Ubuntu-based)
• Size: Optimized for production
• Features:
  • Static file serving
  • Gzip compression
  • Security headers

Server Image (task-receipts-server)

• Base: node:18-slim (Ubuntu-based)
• Build: Multi-stage build with Node.js 18 (Ubuntu-based)
• Size: Optimized for production
• Features:
  • Non-root user execution
  • Health checks
  • Graceful shutdown handling
  • Signal handling with dumb-init

Development

Building Individual Images

# Build client only
cd client
docker build -t task-receipts-client:dev .

# Build server only
cd server
docker build -t task-receipts-server:dev .

Development with Docker Compose

Create a docker-compose.dev.yml for development:

version: '3.8'

services:
  server:
    build:
      context: ./server
      dockerfile: Dockerfile
    ports:
      - "4000:4000"
    environment:
      - NODE_ENV=development
    volumes:
      - ./server/src:/app/src
      - ./shared:/app/shared
    command: npm run dev

  client:
    build:
      context: ./client
      dockerfile: Dockerfile
    ports:
      - "5173:80"
    volumes:
      - ./client/src:/app/src
      - ./shared:/app/shared

Configuration

Environment Variables

The server supports the following environment variables:

• NODE_ENV: Environment (production/development)
• PORT: Server port (default: 4000)

Database Persistence

The server's SQLite database is persisted in the ./server/data directory when using Docker Compose.

Troubleshooting

Common Issues

1. Port conflicts:

   • Ensure ports 80 and 4000 are available
   • Modify ports in docker-compose.yml if needed

2. Build failures:

   • Check Docker is running
   • Ensure all source files are present
   • Check network connectivity for npm packages

3. Client can't connect to server:

   • Verify server is running and healthy
   • Check CORS configuration
   • Ensure proper network connectivity

Logs

# View all logs
docker-compose logs

# View specific service logs
docker-compose logs server
docker-compose logs client

# Follow logs in real-time
docker-compose logs -f

Health Checks

# Check service health
docker-compose ps

# Check individual container health
docker inspect task-receipts-server | grep Health -A 10

Production Deployment

Using Docker Compose

1. Build and deploy:

   docker-compose -f docker-compose.yml up -d --build
   

2. Update services:

   docker-compose pull
   docker-compose up -d
   

Using Individual Containers

1. Build images:

   ./build-docker.sh v1.0.0
   

2. Deploy with orchestration:

   # Example with Docker Swarm or Kubernetes
   docker stack deploy -c docker-compose.yml task-receipts
   

Security Considerations

• Images run as non-root users
• Ubuntu-based images for better security and performance
• No sensitive data in images
• Health checks for monitoring
• Graceful shutdown handling

Performance Optimization

• Multi-stage builds reduce image size
• Nginx for static file serving
• Ubuntu-based images for better performance
• Production-only dependencies in final images
• Layer caching optimization

Monitoring

Health Checks

• Server: GraphQL endpoint availability
• Client: Nginx process status

Metrics

• Container resource usage
• Application logs
• Health check status

Support

For issues with the Docker setup:

1. Check the troubleshooting section
2. Review container logs
3. Verify Docker and Docker Compose versions
4. Ensure all prerequisites are met