cv-site/DEPLOYMENT_SETUP.md

# Deployment Setup Guide

This guide will help you configure GitHub Actions for automatic deployment of your CV site.

## Overview

The deployment system is now fully configured with:
- ✅ GitHub Actions workflows (`.github/workflows/`)
- ✅ Deployment scripts (`scripts/`)
- ✅ Systemd service configuration (`config/systemd/cv.service`)
- ✅ Updated Makefile with CI/CD targets

## Required GitHub Secrets

To enable automatic deployment, you need to configure these secrets in your GitHub repository:

Go to: **Settings → Secrets and variables → Actions → New repository secret**

### Essential Secrets

| Secret Name | Value | Description |
|------------|-------|-------------|
| `SSH_PRIVATE_KEY` | Your private SSH key | Used to connect to the production server |
| `SSH_HOST` | `localhost` or your server IP | Production server hostname |
| `SSH_USER` | `txeo` | SSH username for deployment |
| `SSH_PORT` | `22` (default) | SSH port (optional if using default) |

### Optional Secrets

| Secret Name | Description |
|------------|-------------|
| `SLACK_WEBHOOK` | Slack webhook URL for deployment notifications |

## Setting Up SSH Key for GitHub Actions

Since this machine is both the development and production server, you need to set up SSH access for GitHub Actions to deploy here.

### Option 1: Deploy to localhost (Recommended for same-machine setup)

If GitHub Actions will run on the same machine, you can use localhost:

```bash
# Generate a deployment key (reusable for all projects)
ssh-keygen -t ed25519 -C "github-actions-deployment" -f ~/.ssh/github-deploy -N ""

# Add the public key to authorized_keys
cat ~/.ssh/github-deploy.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# Copy the private key to add to GitHub Secrets (use this for ALL projects)
cat ~/.ssh/github-deploy
# Copy the entire output (including BEGIN and END lines)
```

**GitHub Secrets Configuration:**
- `SSH_PRIVATE_KEY`: (paste the private key output from above)
- `SSH_HOST`: `localhost` or `127.0.0.1`
- `SSH_USER`: `txeo`
- `SSH_PORT`: `22`

### Option 2: Deploy from GitHub hosted runners

If using GitHub's hosted runners to deploy to this server:

```bash
# Generate a deployment key (reusable for all projects)
ssh-keygen -t ed25519 -C "github-actions-deployment" -f ~/.ssh/github-deploy -N ""

# Add the public key to authorized_keys
cat ~/.ssh/github-deploy.pub >> ~/.ssh/authorized_keys

# Get your public IP address
curl ifconfig.me

# Copy the private key (use this for ALL projects)
cat ~/.ssh/github-deploy
```

**GitHub Secrets Configuration:**
- `SSH_PRIVATE_KEY`: (paste the private key output)
- `SSH_HOST`: (your public IP from `curl ifconfig.me`)
- `SSH_USER`: `txeo`
- `SSH_PORT`: `22`

## Reusing Secrets Across Multiple Projects

**Important**: If you have multiple projects deploying to the same server, use **one shared SSH key** for all of them.

### Why One Shared Key?

✅ **Advantages:**
- **Simpler management** - One key to rotate/update instead of multiple
- **Same access level** - All projects deploy as the same user anyway
- **Easier setup** - Generate once, reuse everywhere
- **Standard practice** - CI/CD systems typically use one deploy key per server

❌ **You don't need separate keys because:**
- All projects deploy to the same server
- All projects use the same user account (`txeo`)
- Separation is already handled by different deployment paths and services

### Shared Secrets (Same for All 3+ Projects)

Copy these exact same values to all your project repositories:
- `SSH_PRIVATE_KEY` - The `~/.ssh/github-deploy` key you generated once
- `SSH_HOST` - Same server (localhost or your IP)
- `SSH_USER` - Same user (`txeo`)
- `SSH_PORT` - Same SSH port (`22`)
- `SLACK_WEBHOOK` - Same notification channel (optional)

### Project-Specific Configuration

Only change these in each project's `.github/workflows/deploy.yml` (in the `env` section):

| Project | APP_NAME | SERVICE_NAME | DEPLOY_PATH | PORT |
|---------|----------|--------------|-------------|------|
| CV Site | cv-server | cv | /home/txeo/Git/yo/cv | 1999 |
| Project 2 | project2-server | project2 | /home/txeo/Git/yo/project2 | 2000 |
| Project 3 | project3-server | project3 | /home/txeo/Git/yo/project3 | 2001 |

### Setup Process

1. **Generate SSH key once** on the server:
   ```bash
   ssh-keygen -t ed25519 -C "github-actions-deployment" -f ~/.ssh/github-deploy -N ""
   cat ~/.ssh/github-deploy.pub >> ~/.ssh/authorized_keys
   ```

2. **Copy the key** for use in all projects:
   ```bash
   cat ~/.ssh/github-deploy
   ```

3. **Add to each repository's GitHub Secrets** (same values):
   - Repository 1 (cv) → Add secrets
   - Repository 2 (project2) → Add **same** secrets
   - Repository 3 (project3) → Add **same** secrets

4. **Customize each workflow** by editing only the `env` section in `deploy.yml`

## Service Configuration

The systemd service configuration has been created at:
- **Template**: `config/systemd/cv.service`
- **Active service**: `/etc/systemd/system/cv.service`

### Update the Active Service (if needed)

If you want to use the new service template with better security settings:

```bash
# Update the systemd service
make update-service

# Or manually:
sudo cp config/systemd/cv.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl restart cv
sudo systemctl status cv
```

## Testing the Deployment Locally

Before pushing to GitHub, you can test the deployment scripts locally:

```bash
# Build the binary
make ci-build

# Test the deployment script
cd build
tar -czf cv-server-test.tar.gz cv-server
cd ..
mv build/cv-server-test.tar.gz ./cv-server.new
chmod +x scripts/deploy.sh
./scripts/deploy.sh cv-server cv

# Check service status
systemctl status cv

# Test health check
make health-check
```

## Deployment Workflow

Once configured, the deployment works automatically:

1. **Push to main branch** → Triggers deployment
2. **Run tests** → Ensures code quality
3. **Build binary** → Creates production binary
4. **Deploy to server** → Uploads and installs new version
5. **Health check** → Verifies deployment success
6. **Send notification** → (if Slack webhook configured)

### Manual Deployment

You can also trigger deployment manually:

1. Go to **Actions** tab in GitHub
2. Select **Deploy CV Site to Production**
3. Click **Run workflow**
4. Choose options (e.g., skip tests)
5. Click **Run workflow**

## Rollback

If a deployment fails or you need to rollback:

```bash
# View available backups
./scripts/rollback.sh cv-server cv

# Rollback to the most recent version
./scripts/rollback.sh cv-server cv latest

# Rollback to specific version (e.g., version #2)
./scripts/rollback.sh cv-server cv 2
```

## Monitoring

### Check Service Status

```bash
# Service status
systemctl status cv

# View logs
journalctl -u cv -f

# View recent logs
journalctl -u cv -n 50 --no-pager
```

### Check Application Health

```bash
# Local health check
curl http://localhost:1999/health

# Public health check
curl https://juan.andres.morenorub.io/health

# Or use the make target
make health-check
```

## File Structure

```
cv/
├── .github/
│   └── workflows/
│       ├── deploy.yml      # Main deployment workflow
│       └── test.yml        # Testing workflow
├── scripts/
│   ├── deploy.sh           # Deployment script
│   ├── healthcheck.sh      # Health check script
│   └── rollback.sh         # Rollback script
├── config/
│   └── systemd/
│       └── cv.service      # Systemd service template
├── backups/                # (created during deployment)
│   └── cv-server.*         # Binary backups
└── Makefile               # Build and deployment targets
```

## Troubleshooting

### Deployment Fails with SSH Error

```bash
# Test SSH connection
ssh -p 22 txeo@localhost "echo 'SSH works'"

# Check SSH key permissions
ls -la ~/.ssh/github-deploy
# Should show: -rw------- (600)
```

### Service Won't Start

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

# Test binary manually
./cv-server

# Check port availability
sudo netstat -tlnp | grep 1999
```

### Health Check Fails

```bash
# Check if service is running
systemctl is-active cv

# Test health endpoint
curl -v http://localhost:1999/health

# Check firewall
sudo ufw status
```

## Next Steps

1. **Add GitHub Secrets** as documented above
2. **Push to main branch** to trigger first deployment
3. **Monitor the deployment** in GitHub Actions tab
4. **Verify deployment** by checking https://juan.andres.morenorub.io

## Support

For issues or questions:
- Check GitHub Actions logs in the **Actions** tab
- Review systemd logs: `journalctl -u cv -f`
- Review the main deployment guide: `GITHUB_ACTIONS_DEPLOYMENT_GUIDE.md`