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:**
   ```bash
   docker-compose up --build
   ```

2. **Run in background:**
   ```bash
   docker-compose up -d --build
   ```

3. **Stop services:**
   ```bash
   docker-compose down
   ```

### Option 2: Using the Build Script

1. **Build both images:**
   ```bash
   ./build-docker.sh
   ```

2. **Build with specific version:**
   ```bash
   ./build-docker.sh v1.0.0
   ```

3. **Run containers individually:**
   ```bash
   # 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

```bash
# 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:

```yaml
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

```bash
# 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

```bash
# 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:**
   ```bash
   docker-compose -f docker-compose.yml up -d --build
   ```

2. **Update services:**
   ```bash
   docker-compose pull
   docker-compose up -d
   ```

### Using Individual Containers

1. **Build images:**
   ```bash
   ./build-docker.sh v1.0.0
   ```

2. **Deploy with orchestration:**
   ```bash
   # 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