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:

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

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

# 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

# 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)

# 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)

# 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

# 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)

# 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

# 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

# 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

# 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

# Check Redis is running
docker ps | grep redis

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

Image pull fails

# 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

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

docker-compose ps

View resource usage

docker stats retail-pos-api retail-pos-redis

Access API documentation

http://localhost:3000/api/docs

---

Backup and Restore

Redis Data

# 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.