merchbay_admin/DEPLOYMENT.md

Gitea Actions Deployment Guide

This repository uses Gitea Actions for automated deployment to your server.

Workflows

1. Deploy Workflow (.gitea/workflows/deploy.yml)

Automatically deploys the application when code is pushed to main or master branch.

Steps:

1. Builds Docker image
2. Transfers image to deployment server
3. Stops existing container
4. Starts new container
5. Runs database migrations
6. Clears and caches Laravel configuration

2. Build and Push Workflow (.gitea/workflows/build-push.yml)

Builds and pushes Docker images to a registry when a version tag is created.

Required Secrets

Configure these secrets in your Gitea repository settings: Settings → Secrets → Actions

Deployment Secrets

Secret Name	Description	Example
DEPLOY_HOST	Deployment server hostname or IP	192.168.1.100 or example.com
DEPLOY_USER	SSH username for deployment	deploy or ubuntu
DEPLOY_SSH_KEY	Private SSH key for authentication	-----BEGIN RSA PRIVATE KEY-----...
DEPLOY_PORT	SSH port (optional, defaults to 22)	22
DEPLOY_DIR	Deployment directory (optional)	/var/www/merchbay_admin

Docker Registry Secrets (Optional)

Only required if using the build-push workflow or private registry:

Secret Name	Description	Example
DOCKER_REGISTRY_URL	Docker registry URL	registry.example.com or docker.io
DOCKER_USERNAME	Registry username	myuser
DOCKER_PASSWORD	Registry password or token	mypassword

Database Configuration on Server

Create a .env file in your deployment directory with database credentials:

# On your deployment server
sudo mkdir -p /var/www/merchbay_admin
sudo nano /var/www/merchbay_admin/.env

Add your database configuration:

DB_HOST=your-mysql-host
DB_PORT=3306
DB_DATABASE=merchbay_admin
DB_USERNAME=your-mysql-user
DB_PASSWORD=your-mysql-password
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:YOUR_APP_KEY_HERE

Setup Instructions

1. Generate SSH Key for Deployment

On your local machine or CI server:

# Generate a new SSH key pair
ssh-keygen -t rsa -b 4096 -f ~/.ssh/deploy_key -N ""

# Copy the public key to your deployment server
ssh-copy-id -i ~/.ssh/deploy_key.pub user@your-server

# Copy the private key content for Gitea secret
cat ~/.ssh/deploy_key

2. Configure Gitea Secrets

1. Go to your Gitea repository
2. Navigate to Settings → Secrets → Actions
3. Add each required secret listed above
4. For DEPLOY_SSH_KEY, paste the entire private key content

3. Prepare Deployment Server

On your deployment server, install Docker and Docker Compose:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

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

# Create .env file with database credentials
nano /var/www/merchbay_admin/.env

4. Update docker-compose.yml for Production

Ensure your docker-compose.yml references the .env file:

services:
  app:
    environment:
      - DB_HOST=${DB_HOST}
      - DB_PORT=${DB_PORT}
      - DB_DATABASE=${DB_DATABASE}
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}

Triggering Deployment

Automatic Deployment

Push to main/master branch:

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

Manual Deployment

1. Go to your Gitea repository
2. Click on Actions
3. Select Deploy MerchBay Admin workflow
4. Click Run workflow

Monitoring Deployment

View Workflow Logs

1. Go to Actions tab in your Gitea repository
2. Click on the running/completed workflow
3. View logs for each step

Check Application Logs

On your deployment server:

cd /var/www/merchbay_admin
docker compose logs -f app

Verify Deployment

# Check container status
docker compose ps

# Test application
curl http://localhost:8080

# Access application shell
docker compose exec app bash

Rollback Procedure

If deployment fails, you can quickly rollback:

# On deployment server
cd /var/www/merchbay_admin

# Stop current container
docker compose down

# Load previous image (if available)
docker images  # Find previous image ID
docker tag <previous-image-id> merchbay_admin:latest

# Start with previous version
docker compose up -d

Troubleshooting

SSH Connection Issues

# Test SSH connection from CI to server
ssh -i ~/.ssh/deploy_key user@your-server

# Check SSH key permissions
chmod 600 ~/.ssh/deploy_key

Docker Permission Issues

# On deployment server, ensure user is in docker group
sudo usermod -aG docker $USER
newgrp docker

Migration Failures

# Manually run migrations
docker compose exec app php artisan migrate --force

# Check database connection
docker compose exec app php artisan tinker
>>> DB::connection()->getPdo();

Security Best Practices

1. Use SSH keys, not passwords for server authentication
2. Restrict SSH key to only deployment commands if possible
3. Use secrets for all sensitive data, never commit to repository
4. Set proper file permissions on deployment server (755 for directories, 644 for files)
5. Enable firewall on deployment server and restrict access
6. Use HTTPS with SSL certificates in production
7. Regular backups of database and uploaded files

Advanced Configuration

Using Docker Registry

To use a private registry:

1. Add registry secrets to Gitea
2. Update deployment script to pull from registry instead of transferring image
3. Use the build-push workflow to automate image publishing

Zero-Downtime Deployment

For zero-downtime deployments, consider:

1. Using a load balancer
2. Running multiple container instances
3. Implementing blue-green deployment strategy

Environment-Specific Deployments

Create separate workflows for staging and production:

• .gitea/workflows/deploy-staging.yml (triggered on develop branch)
• .gitea/workflows/deploy-production.yml (triggered on main branch)