update docker

2025-10-10 17:13:45 +07:00
parent 87c12b9927
commit 8c34460889
5 changed files with 478 additions and 50 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -0,0 +1,350 @@
+# 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.