cv-site/GITHUB-ACTION-SETUP.md

# GitHub Actions Deployment Setup

This guide will help you configure automated deployment for your CV server.

## How It Works

When you push to the `main` branch, GitHub Actions will:
1. SSH into your server
2. Pull the latest code with `git pull origin main`
3. Restart your systemd service
4. Verify the deployment by checking the health endpoint

## Prerequisites

✅ Your server must have:
- Git repository cloned at the deployment path
- Systemd service configured to run `go run .`
- SSH access configured
- `sudo` permissions for the user (to restart systemd service)

## GitHub Secrets Configuration

Go to your GitHub repository → Settings → Secrets and variables → Actions → New repository secret

### Required Secrets

| Secret Name | Description | Example Value |
|-------------|-------------|---------------|
| `SSH_PRIVATE_KEY` | Your SSH private key | `-----BEGIN OPENSSH PRIVATE KEY-----`<br>`...`<br>`-----END OPENSSH PRIVATE KEY-----` |
| `SSH_HOST` | Your server's IP or domain | `192.168.1.100` or `cv.example.com` |
| `SSH_USER` | SSH username | `deploy` or `ubuntu` |

### Optional Secrets (with defaults)

| Secret Name | Description | Default Value |
|-------------|-------------|---------------|
| `SSH_PORT` | SSH port number | `22` |
| `SERVICE_NAME` | Systemd service name | `cv-server` |
| `REPO_PATH` | Path to repository on server | `/opt/cv-server` |

## Step-by-Step Setup

### 1. Generate SSH Key Pair (if you don't have one)

On your local machine:

```bash
ssh-keygen -t ed25519 -C "github-actions-cv-deploy" -f ~/.ssh/cv-deploy
```

This creates:
- `~/.ssh/cv-deploy` (private key) - Add to GitHub Secrets
- `~/.ssh/cv-deploy.pub` (public key) - Add to server

### 2. Add Public Key to Server

Copy the public key to your server:

```bash
ssh-copy-id -i ~/.ssh/cv-deploy.pub your-user@your-server
```

Or manually:

```bash
# On your server
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "YOUR_PUBLIC_KEY_CONTENT" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```

### 3. Add Private Key to GitHub Secrets

```bash
# Copy the private key content
cat ~/.ssh/cv-deploy
```

Copy the **entire output** (including `-----BEGIN` and `-----END` lines) and add it as `SSH_PRIVATE_KEY` secret in GitHub.

### 4. Configure Sudoers (for service restart)

Your SSH user needs permission to restart the systemd service without a password:

```bash
# On your server
sudo visudo -f /etc/sudoers.d/cv-deploy
```

Add this line (replace `your-user` with your SSH username):

```
your-user ALL=(ALL) NOPASSWD: /bin/systemctl restart cv-server, /bin/systemctl status cv-server, /bin/systemctl is-active cv-server, /usr/bin/journalctl -u cv-server*
```

Save and verify:

```bash
sudo -l  # Should show the commands without requiring password
```

### 5. Example Systemd Service

Your systemd service should be configured to run `go run .`. Example at `/etc/systemd/system/cv-server.service`:

```ini
[Unit]
Description=CV Server - Go Hot Reload
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/opt/cv-server
Environment="GO_ENV=production"
Environment="PORT=1999"
ExecStart=/usr/local/go/bin/go run .
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl daemon-reload
sudo systemctl enable cv-server
sudo systemctl start cv-server
```

### 6. Add GitHub Secrets

In your GitHub repository:

1. Go to **Settings** → **Secrets and variables** → **Actions**
2. Click **New repository secret**
3. Add each secret:

```
SSH_PRIVATE_KEY: [paste entire private key]
SSH_HOST: your.server.ip.or.domain
SSH_USER: your-ssh-username
SSH_PORT: 22 (if using default, can skip)
SERVICE_NAME: cv-server (if different, update)
REPO_PATH: /opt/cv-server (if different, update)
```

## Testing the Deployment

### Manual Trigger

You can manually trigger the deployment:

1. Go to **Actions** tab in GitHub
2. Click **Deploy CV Server** workflow
3. Click **Run workflow** → **Run workflow**

### Automatic Trigger

Simply push to main:

```bash
git add .
git commit -m "Test deployment"
git push origin main
```

### Verify Deployment

Check the Actions tab in GitHub to see the deployment progress. The workflow will:
- ✅ Pull latest code
- ✅ Restart service
- ✅ Check service status
- ✅ Verify health endpoint

## Troubleshooting

### SSH Connection Issues

```bash
# Test SSH connection from GitHub Actions
ssh -i ~/.ssh/cv-deploy -p 22 user@host "echo 'Connection successful'"
```

### Service Restart Issues

```bash
# Check service logs
sudo journalctl -u cv-server -n 50 --no-pager

# Check service status
sudo systemctl status cv-server
```

### Permission Issues

```bash
# Verify sudoers configuration
sudo -l

# Test restart command
sudo systemctl restart cv-server
```

### Health Check Failures

```bash
# Test health endpoint on server
curl http://localhost:1999/health

# Check if service is listening
sudo netstat -tlnp | grep 1999
```

## Security Best Practices

✅ Use ED25519 SSH keys (more secure than RSA)
✅ Restrict sudo permissions to specific commands only
✅ Use a dedicated deployment user (not root)
✅ Regularly rotate SSH keys
✅ Enable firewall rules to restrict SSH access
✅ Use SSH key passphrase (store in GitHub Secrets if needed)

## Next Steps

After setup is complete:
1. Test the deployment with a small change
2. Monitor the first few deployments
3. Set up notifications for failed deployments (GitHub Actions settings)
4. Consider adding deployment tags/releases for rollback capability