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:

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

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

   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:

   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:

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

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

# 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

# Service status
systemctl status cv

# View logs
journalctl -u cv -f

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

Check Application Health

# 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

# 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

# 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

# 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