merchbay_admin/DEPLOYMENT-SETUP.md

Deployment Setup Guide

This guide will help you set up your deployment infrastructure for the MerchBay Admin application.

Quick Start

We've created two helper scripts to simplify the setup process:

1. Setup SSH Keys (setup-ssh-keys.sh)

Generate and configure SSH keys for Gitea deployment.

./setup-ssh-keys.sh

What it does:

• Generates an SSH key pair for deployment
• Shows you the private key to add to Gitea secrets
• Optionally deploys the public key to your server
• Tests the SSH connection

2. Setup Server Environment (setup-server-env.sh)

Configure .env files on your deployment servers.

./setup-server-env.sh

What it does:

• Guides you through environment configuration
• Creates .env file on your server
• Shows you which Gitea secrets are needed
• Supports both production and development environments

Manual Setup (Alternative)

If you prefer manual setup, follow these steps:

Step 1: Generate SSH Keys

# Generate SSH key
ssh-keygen -t ed25519 -C "gitea-deploy-key" -f ~/.ssh/gitea_deploy_key -N ""

# View private key (for Gitea)
cat ~/.ssh/gitea_deploy_key

# View public key (for server)
cat ~/.ssh/gitea_deploy_key.pub

Step 2: Add Public Key to Server

# SSH to your server
ssh user@your-server

# Add public key
mkdir -p ~/.ssh
echo "your-public-key-here" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Step 3: Create .env Files on Server

Production Server:

ssh user@prod-server

mkdir -p /var/www/merchbay_admin
cat > /var/www/merchbay_admin/.env << 'EOF'
APP_ENV=production
APP_DEBUG=false
APP_URL=https://merchbay.com
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=merchbay_prod
DB_USERNAME=merchbay_user
DB_PASSWORD=your_secure_password
DOMAIN=merchbay.com
EOF

chmod 600 /var/www/merchbay_admin/.env

Development Server:

ssh user@dev-server

mkdir -p /var/www/merchbay_admin_dev
cat > /var/www/merchbay_admin_dev/.env << 'EOF'
APP_ENV=staging
APP_DEBUG=false
APP_URL=https://dev-admin.merchbay.app
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=merchbay_dev
DB_USERNAME=merchbay_user
DB_PASSWORD=your_dev_password
DOMAIN=dev-admin.merchbay.app
EOF

chmod 600 /var/www/merchbay_admin_dev/.env

Step 4: Add Secrets to Gitea

Go to your Gitea repository → Settings → Secrets

For Production (deploy.yml):

• PROD_DEPLOY_SSH_KEY - Your private SSH key content
• PROD_DEPLOY_USER - SSH username (e.g., root)
• PROD_DEPLOY_HOST - Server IP/hostname

For Development (deploy-dev.yml):

• DEPLOY_SSH_KEY - Your private SSH key content
• DEPLOY_USER - SSH username (e.g., root)
• DEPLOY_HOST - Server IP/hostname

For Docker Registry (build-push.yml):

• DOCKER_REGISTRY_URL - Your registry URL
• DOCKER_USERNAME - Registry username
• DOCKER_PASSWORD - Registry password

Benefits of This Approach

✅ Fewer Secrets - Only 3 secrets per environment instead of 8+ ✅ Centralized - All database/app secrets stay on the server ✅ Reusable - Same SSH credentials work for all apps ✅ Secure - Secrets never appear in CI/CD logs ✅ Easy Updates - Edit .env files directly on server

Troubleshooting

SSH Connection Issues

# Test SSH connection
ssh -i ~/.ssh/gitea_deploy_key user@server

# Check SSH key permissions
chmod 600 ~/.ssh/gitea_deploy_key
chmod 644 ~/.ssh/gitea_deploy_key.pub

Workflow Fails with "Could not resolve hostname"

• Make sure all secrets are added to Gitea
• Verify DEPLOY_HOST / PROD_DEPLOY_HOST is correct
• Check DEPLOY_USER / PROD_DEPLOY_USER is set

.env File Not Found

• Run ./setup-server-env.sh to create it
• Or manually create .env file on server at:
  • Production: /var/www/merchbay_admin/.env
  • Development: /var/www/merchbay_admin_dev/.env

Multiple Applications

To deploy multiple applications using the same setup:

1. Use the same SSH keys - No need to generate new ones
2. Create separate .env files - One per app on the server
3. Only 3 Gitea secrets total - Reuse across all apps!

Example for another app:

# Same SSH key works!
# Just create new .env file
ssh user@server
mkdir -p /var/www/another_app
cat > /var/www/another_app/.env << 'EOF'
# App-specific configuration
EOF

Security Best Practices

• ✅ Never commit .env files to git
• ✅ Keep private keys secure
• ✅ Use strong database passwords
• ✅ Restrict SSH key permissions (600)
• ✅ Use different passwords for prod/dev
• ✅ Regularly rotate credentials