Assist_Design/DEPLOYMENT-GUIDE.md

🚀 Pre-built Images Deployment Guide

This guide shows how to deploy using pre-built Docker images instead of building on Plesk.

Benefits

• ✅ No build failures on Plesk
• ✅ Faster deployments (no compilation time)
• ✅ Consistent images across environments
• ✅ Better security (build in controlled environment)
• ✅ Easy rollbacks and version control

Prerequisites

1. GitHub Account (for free container registry)
2. Docker installed locally (for building images)
3. Plesk with Docker extension

Step 1: Setup GitHub Container Registry

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Create a new token with these permissions:
   • write:packages (to push images)
   • read:packages (to pull images)
3. Save the token securely

Step 2: Login to GitHub Container Registry

# Replace YOUR_USERNAME and YOUR_TOKEN
echo "YOUR_TOKEN" | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Step 3: Update Build Script

Edit scripts/build-and-push.sh:

# Change this line:
NAMESPACE="your-github-username"  # Replace with your actual GitHub username

Step 4: Build and Push Images

# Build and push with version tag
./scripts/build-and-push.sh v1.0.0

# Or build and push as latest
./scripts/build-and-push.sh

Step 5: Update Plesk Compose File

Edit compose-plesk.yaml and replace:

image: ghcr.io/your-github-username/portal-frontend:latest
image: ghcr.io/your-github-username/portal-backend:latest

With your actual GitHub username.

Step 6: Deploy to Plesk

1. Upload compose-plesk.yaml to your Plesk server
2. Plesk → Docker → Add Stack
3. Paste the contents of compose-plesk.yaml
4. Deploy

Step 7: Configure Plesk Reverse Proxy

1. Plesk → Domains → your-domain.com → Apache & Nginx Settings
2. Add to "Additional directives for HTTP":

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache_bypass $http_upgrade;
}

location /api {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Step 8: Secure Database Access

Add to Plesk Firewall:

# Allow Docker bridge network
ACCEPT from 172.17.0.0/16 to any port 5432
ACCEPT from 172.17.0.0/16 to any port 6379

# Deny external access to database
DROP from any to any port 5432
DROP from any to any port 6379

Updating Your Application

1. Make code changes
2. Build and push new images:

   ./scripts/build-and-push.sh v1.0.1
   

3. Update compose-plesk.yaml with new version tag
4. Redeploy in Plesk

Troubleshooting

Images not found

• Check if you're logged in: docker login ghcr.io
• Verify image names match your GitHub username
• Ensure images are public or Plesk can authenticate

Build failures

• Run locally first: docker build -f apps/portal/Dockerfile .
• Check Docker logs for specific errors
• Ensure all dependencies are in package.json

Connection issues

• Verify firewall allows Docker bridge network (172.17.0.0/16)
• Check that DATABASE_URL uses correct IP (172.17.0.1)
• Test database connection from backend container

Security Notes

• Database is only accessible from Docker bridge network
• Backend API is only accessible via reverse proxy
• Use strong passwords and JWT secrets
• Consider using Docker secrets for sensitive data
• Regularly update base images for security patches