188 lines
4.5 KiB
Markdown
188 lines
4.5 KiB
Markdown
# 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
|