# 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.

```bash
./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.

```bash
./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

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

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

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