# Deployment Setup Guide

This guide covers the deployment script and GitHub Actions workflow for HOALedgerIQ_Website.

## Files Created

1. **`deploy.sh`** - Server-side deployment script
2. **`.github/workflows/deploy.yml`** - GitHub Actions workflow

## Server Setup

### 1. Copy the deployment script to your server

```bash
# SSH into your Debian server
ssh ubuntu@your-server-ip

# Copy the deploy script
cd /home/ubuntu/www
curl -O https://raw.githubusercontent.com/your-org/HOALedgerIQ_Website/main/deploy.sh
# Or copy it manually via scp
```

### 2. Make it executable

```bash
chmod +x deploy.sh
```

### 3. Configure environment variables (optional)

The script uses these defaults, but you can override them:

| Variable | Default | Description |
|----------|---------|-------------|
| `DEPLOY_DIR` | `/home/ubuntu/www` | Application directory |
| `SERVICE_NAME` | `hoaledgeriq` | Debian service name |
| `GIT_REMOTE` | `origin` | Git remote name |
| `GIT_BRANCH` | `main` | Branch to deploy |
| `CACHE_CLEAR_CMD` | `rm -rf cache/*` | Cache clearing command |

You can set these in `/etc/environment`, `.bashrc`, or pass them inline.

## GitHub Secrets Setup

Add these secrets to your GitHub repository (Settings → Secrets and variables → Actions):

| Secret | Description | Example |
|--------|-------------|---------|
| `DEPLOY_HOST` | Server IP or hostname | `192.168.1.100` or `server.example.com` |
| `DEPLOY_USERNAME` | SSH username | `ubuntu` |
| `DEPLOY_SSH_KEY` | Private SSH key for deployment | `-----BEGIN OPENSSH PRIVATE KEY-----...` |
| `DEPLOY_PORT` | SSH port (optional) | `22` |
| `DEPLOY_DIR` | Deploy directory (optional) | `/home/ubuntu/www` |
| `SERVICE_NAME` | Service name (optional) | `hoaledgeriq` |
| `GIT_BRANCH` | Branch to deploy (optional) | `main` |

### Generate SSH Key for GitHub Actions

```bash
# On your local machine
ssh-keygen -t ed25519 -C "github-actions-deploy" -f github-actions-deploy

# Copy public key to server
ssh-copy-id -i github-actions-deploy.pub ubuntu@your-server-ip

# Get private key content for GitHub secret
cat github-actions-deploy | pbcopy
```

## How It Works

1. **On every push to `main`**: GitHub Actions triggers the workflow
2. **SSH connection**: The workflow connects to your Debian server
3. **Deploy script runs**: Executes `deploy.sh` which:
   - Pulls latest code from git
   - Clears application cache
   - Restarts the service
   - Verifies the service is running

## Testing

Before enabling auto-deploy, test the script manually:

```bash
# On your server
cd /home/ubuntu/www
./deploy.sh
```

## Troubleshooting

### Service won't start
```bash
# Check service status
sudo systemctl status hoaledgeriq

# View logs
sudo journalctl -u hoaledgeriq -f
```

### Git pull fails
```bash
# Check git remote
git remote -v

# Verify SSH keys on server
ssh -T git@github.com
```

### Permission issues
Ensure the deploy user has:
- Write access to the deploy directory
- Permission to restart the service (via sudo)

Add to `/etc/sudoers`:
```
ubuntu ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart hoaledgeriq
```