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:

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

Add your database configuration:

```env
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:

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

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

```yaml
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:

```bash
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:

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

### Verify Deployment

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

```bash
# 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

```bash
# 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

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

### Migration Failures

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