retail-nest/DEPLOYMENT.md

# Docker Deployment Guide

## Overview

This project can be deployed using Docker in two ways:
1. **Build and Push to Registry** (Recommended for production)
2. **Build from Source** (Good for development/testing)

---

## Option 1: Using Pre-built Image (Recommended)

### Step 1: Build and Push Image

On your **local machine or CI/CD**:

```bash
# 1. Login to Docker Hub (or your registry)
docker login

# 2. Build the image
docker build -t retail-pos-api:latest .

# 3. Tag for your registry
docker tag retail-pos-api:latest your-username/retail-pos-api:latest

# 4. Push to registry
docker push your-username/retail-pos-api:latest
```

Or use the automated script:
```bash
# Edit the script first to set your registry username
nano build-and-push.sh

# Run the script
./build-and-push.sh
```

### Step 2: Deploy on Target Server

On your **deployment server**:

```bash
# 1. Copy docker-compose.prod.yml to server
scp docker-compose.prod.yml user@server:/path/to/deployment/

# 2. SSH into server
ssh user@server

# 3. Edit docker-compose.prod.yml to update image name and env vars
nano docker-compose.prod.yml

# 4. Pull and start services
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d

# 5. Check status
docker-compose -f docker-compose.prod.yml ps
docker-compose -f docker-compose.prod.yml logs -f api
```

---

## Option 2: Build from Source

### On Target Server

```bash
# 1. Clone repository (or copy files)
git clone your-repo-url
cd retail-nest

# 2. Create/edit .env file if needed
cp .env.example .env
nano .env

# 3. Build and start
docker-compose up -d --build

# 4. Check status
docker-compose ps
docker-compose logs -f api
```

---

## File Structure

```
retail-nest/
├── Dockerfile                  # Multi-stage build configuration
├── docker-compose.yml          # For local development (builds from source)
├── docker-compose.prod.yml     # For production (uses pre-built image)
├── build-and-push.sh          # Automated build and push script
└── .dockerignore              # Files to exclude from Docker build
```

---

## Environment Variables

All environment variables can be configured in `docker-compose.prod.yml`:

### Database (Aiven PostgreSQL)
- `DB_HOST`: Your Aiven database host
- `DB_PORT`: Database port (usually 20912 for Aiven)
- `DB_USERNAME`: Database username
- `DB_PASSWORD`: Database password
- `DB_DATABASE`: Database name
- `DB_SSL`: "true" (required for Aiven)

### Application
- `NODE_ENV`: production
- `PORT`: 3000
- `API_PREFIX`: api
- `JWT_SECRET`: Your JWT secret key
- `CORS_ORIGIN`: Allowed origins

### Redis
- `REDIS_HOST`: redis (container name)
- `REDIS_PORT`: 6379
- `CACHE_TTL`: 300

---

## Useful Commands

### Development (docker-compose.yml)
```bash
# Start services (builds from source)
docker-compose up -d

# View logs
docker-compose logs -f api

# Restart API
docker-compose restart api

# Stop services
docker-compose down

# Rebuild
docker-compose up -d --build
```

### Production (docker-compose.prod.yml)
```bash
# Pull latest image and start
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f api

# Restart API
docker-compose -f docker-compose.prod.yml restart api

# Stop services
docker-compose -f docker-compose.prod.yml down

# Update to new version
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d
```

### Docker Commands
```bash
# View running containers
docker ps

# View images
docker images

# Remove unused images
docker image prune -a

# View logs of specific container
docker logs retail-pos-api -f

# Execute command in container
docker exec -it retail-pos-api sh

# Check health
docker inspect retail-pos-api --format='{{.State.Health.Status}}'
```

---

## Registry Options

### Docker Hub (Public/Private)
```bash
# Login
docker login

# Build and push
docker build -t your-username/retail-pos-api:latest .
docker push your-username/retail-pos-api:latest
```

### GitHub Container Registry
```bash
# Login
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Build and push
docker build -t ghcr.io/username/retail-pos-api:latest .
docker push ghcr.io/username/retail-pos-api:latest
```

### Private Registry
```bash
# Login
docker login registry.your-domain.com

# Build and push
docker build -t registry.your-domain.com/retail-pos-api:latest .
docker push registry.your-domain.com/retail-pos-api:latest
```

---

## Health Checks

The API includes health check endpoints:

- **Application Health**: `http://localhost:3000/api/health`
- **Root Health**: `http://localhost:3000/api`

Docker automatically monitors these endpoints and will restart the container if unhealthy.

---

## Troubleshooting

### Container won't start
```bash
# Check logs
docker-compose logs api

# Check environment variables
docker exec retail-pos-api env

# Verify database connection
docker exec retail-pos-api wget -qO- http://localhost:3000/api/health
```

### Database connection issues
- Verify `DB_SSL` is set to "true" for Aiven
- Check database credentials in docker-compose.prod.yml
- Ensure firewall allows connections to Aiven

### Redis connection issues
```bash
# Check Redis is running
docker ps | grep redis

# Test Redis connection
docker exec retail-pos-redis redis-cli ping
```

### Image pull fails
```bash
# Re-login to registry
docker login

# Check image name is correct
docker pull your-username/retail-pos-api:latest
```

---

## Security Best Practices

1. **Never commit secrets**: Keep sensitive data in environment variables
2. **Use private registry**: For production deployments
3. **Regular updates**: Keep base images updated
4. **Scan images**: Use `docker scan` to check for vulnerabilities
5. **Use secrets management**: Consider Docker secrets or external vaults
6. **Limit resources**: Add resource limits in docker-compose.yml

---

## CI/CD Integration

### GitHub Actions Example
```yaml
name: Build and Push Docker Image

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Login to Docker Hub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v2
        with:
          context: .
          push: true
          tags: your-username/retail-pos-api:latest
```

---

## Monitoring

### Check service status
```bash
docker-compose ps
```

### View resource usage
```bash
docker stats retail-pos-api retail-pos-redis
```

### Access API documentation
```
http://localhost:3000/api/docs
```

---

## Backup and Restore

### Redis Data
```bash
# Backup
docker exec retail-pos-redis redis-cli SAVE
docker cp retail-pos-redis:/data/dump.rdb ./backup/

# Restore
docker cp ./backup/dump.rdb retail-pos-redis:/data/
docker-compose restart redis
```

### Database (Aiven handles backups automatically)
Check your Aiven console for backup options.