merchbay_admin/DEPLOYMENT-PORTAINER.md

Deployment with Portainer and Traefik

This guide covers deploying MerchBay Admin using your existing Portainer and Traefik setup.

Prerequisites

• ✅ Gitea self-hosted with Gitea runners configured
• ✅ Portainer installed and accessible
• ✅ Traefik reverse proxy running with:
  • web entrypoint (port 80)
  • websecure entrypoint (port 443)
  • Let's Encrypt certificate resolver named letsencrypt
  • External network named traefik

Deployment Methods

Method 1: Portainer Stack Deployment (Recommended)

Step 1: Prepare the Image

Build the Docker image via Gitea Actions or manually:

# Using Gitea Actions (will build automatically on push)
git push origin main

# OR build manually
docker build -t merchbay_admin:latest .

Step 2: Deploy in Portainer

1. Access Portainer → Stacks → Add stack

2. Stack Configuration:

   • Name: merchbay-admin
   • Build method: Web editor

3. Paste the content from docker-compose.portainer.yml and update:

   • APP_URL: Your domain (e.g., https://merchbay-admin.yourdomain.com)
   • DB_HOST: Your MySQL host
   • DB_DATABASE: Database name
   • DB_USERNAME: Database username
   • DB_PASSWORD: Database password
   • Traefik Host rule: Replace merchbay-admin.yourdomain.com with your actual domain

4. Deploy the stack

5. Run Initial Setup:

   • Go to Containers → Find merchbay_admin_app
   • Click Console → Connect with /bin/bash
   • Run:

     php artisan migrate --force
     php artisan config:cache
     php artisan route:cache
     

Method 2: Gitea Actions CI/CD (Automated)

Step 1: Configure Gitea Secrets

In your Gitea repository → Settings → Secrets → Actions, add:

Secret Name	Value	Description
DEPLOY_HOST	192.168.1.100	Your server IP/hostname
DEPLOY_USER	deploy	SSH username
DEPLOY_SSH_KEY	-----BEGIN RSA...	Private SSH key
DEPLOY_PORT	22	SSH port (optional)
DEPLOY_DIR	/var/www/merchbay_admin	Deployment directory
DOMAIN	merchbay-admin.yourdomain.com	Your domain for Traefik

Step 2: Prepare Deployment Server

# SSH into your server
ssh deploy@your-server

# Create deployment directory
sudo mkdir -p /var/www/merchbay_admin
sudo chown $USER:$USER /var/www/merchbay_admin
cd /var/www/merchbay_admin

# Create .env file
nano .env

Add to .env:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://merchbay-admin.yourdomain.com
DB_HOST=your-mysql-host
DB_PORT=3306
DB_DATABASE=merchbay_admin
DB_USERNAME=your-mysql-user
DB_PASSWORD=your-mysql-password
DOMAIN=merchbay-admin.yourdomain.com

Step 3: Ensure Traefik Network Exists

docker network inspect traefik >/dev/null 2>&1 || docker network create traefik

Step 4: Deploy

Simply push to your main branch:

git add .
git commit -m "Deploy application"
git push origin main

Gitea Actions will automatically:

1. Build the Docker image
2. Transfer to your server
3. Deploy with docker-compose
4. Connect to Traefik network
5. Run migrations
6. Cache configurations

Method 3: Manual Deployment with Script

# On your server
cd /var/www/merchbay_admin

# Pull latest code
git pull origin main

# Run deployment script
./deploy.sh

Traefik Configuration

Verify Traefik Setup

Ensure your Traefik configuration includes:

# traefik.yml or docker-compose.yml
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

certificatesResolvers:
  letsencrypt:
    acme:
      email: your-email@example.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

External Network

Ensure Traefik network exists and is external:

# Create network if it doesn't exist
docker network create traefik

# Verify
docker network inspect traefik

DNS Configuration

Point your domain to your server:

Type: A Record
Name: merchbay-admin (or @ for root domain)
Value: YOUR_SERVER_IP
TTL: 3600

Verification

1. Check Container Status

Via Portainer:

• Navigate to Containers
• Verify merchbay_admin_app is running

Via CLI:

docker ps | grep merchbay_admin

2. Check Traefik Dashboard

If you have Traefik dashboard enabled:

• Look for merchbay-admin@docker router
• Verify it's connected to the correct service

3. Test Application

# Test HTTPS
curl -I https://merchbay-admin.yourdomain.com

# Should return: HTTP/2 200

4. Check Logs

Via Portainer:

• Containers → merchbay_admin_app → Logs

Via CLI:

docker logs merchbay_admin_app -f

Troubleshooting

Issue: Container not accessible via domain

Check Traefik labels:

docker inspect merchbay_admin_app | grep -A 20 Labels

Verify network connection:

docker network inspect traefik | grep merchbay_admin

Solution:

# Reconnect to Traefik network
docker network connect traefik merchbay_admin_app

Issue: SSL certificate not generating

Check Traefik logs:

docker logs traefik | grep letsencrypt

Common fixes:

1. Ensure port 80 is accessible (Let's Encrypt HTTP challenge)
2. Verify DNS is pointing to your server
3. Check email in Traefik's ACME configuration
4. Ensure acme.json has correct permissions (600)

Issue: Database connection failed

Check environment variables:

docker exec merchbay_admin_app env | grep DB_

Test connection:

docker exec merchbay_admin_app php artisan tinker
>>> DB::connection()->getPdo();

Issue: 502 Bad Gateway

Possible causes:

1. Application not fully started
2. Wrong port in Traefik label (should be 80)
3. Application crashed

Check:

# Container status
docker ps -a | grep merchbay_admin

# Application logs
docker logs merchbay_admin_app --tail 100

# Restart container
docker restart merchbay_admin_app

Updating the Application

Via Gitea Actions (Automatic)

git add .
git commit -m "Update application"
git push origin main

Via Portainer

1. Go to Stacks → merchbay-admin
2. Click Editor
3. Update image or configuration
4. Click Update the stack
5. Enable "Re-pull image and redeploy"

Manual Update

ssh deploy@your-server
cd /var/www/merchbay_admin
./deploy.sh

Rollback

Via Portainer

1. Go to Stacks → merchbay-admin
2. Click on the stack
3. Find previous version in Stack History (if available)
4. Revert to previous version

Manual Rollback

# List available backups
ls -lh /var/www/merchbay_admin/backups/

# Restore from backup
cd /var/www/merchbay_admin
tar -xzf backups/backup_YYYYMMDD_HHMMSS.tar.gz

# Restart
docker compose restart

Security Best Practices

1. Use Strong Database Passwords: Generate with openssl rand -base64 32
2. Restrict SSH Access: Use key-based authentication only
3. Firewall Rules: Only allow necessary ports (80, 443, 22)
4. Regular Backups: Automated backups of database and storage
5. Keep Docker Updated: Regularly update Docker and images
6. Monitor Logs: Set up log monitoring/alerting
7. Use Secrets: Never commit sensitive data to repository
8. HTTPS Only: Ensure HTTP redirects to HTTPS

Performance Optimization

PHP-FPM Configuration

Consider switching to PHP-FPM for better performance:

FROM php:7.4-fpm-alpine
# ... additional configuration

Use Redis for Cache/Sessions

CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=redis

Add Redis service to docker-compose:

services:
  redis:
    image: redis:alpine
    networks:
      - default

Enable OPcache

Already included in Dockerfile, verify:

docker exec merchbay_admin_app php -i | grep opcache

Monitoring

View Real-time Logs in Portainer

1. Navigate to Containers
2. Click on merchbay_admin_app
3. Select Logs tab
4. Enable Auto-refresh

Set Up Alerts

Configure Portainer notifications:

1. Settings → Notifications
2. Add webhook or email notification
3. Set up container health checks

Support

For issues:

1. Check application logs in Portainer
2. Verify Traefik configuration
3. Test database connectivity
4. Review Gitea Actions logs if using CI/CD