Simplified SSH Setup for GitHub Actions Documentation Deployment¶

Branch Strategy¶

Before setting up SSH, understand the deployment branch strategy: - dev-* (e.g., dev-tony, dev-feature) → Production deployment (current setup) - Pull requests → Preview builds (no deployment)

Quick Setup¶

1. Create Deploy User on Server¶

# SSH into your server
ssh root@your-server.com

# Create deploy user if it doesn't exist
addu1ser deploy
usermod -aG sudo deploy

# Create SSH key for GitHub Actions
sudo -u deploy ssh-keygen -t ed25519 -C "github-actions-deploy" -f /home/deploy/.ssh/github-actions-key

# Press Enter for all prompts (no passphrase)

# Setup authorized_keys
sudo -u deploy cp /home/deploy/.ssh/github-actions-key.pub /home/deploy/.ssh/authorized_keys

# Set permissions
sudo -u deploy chmod 600 /home/deploy/.ssh/authorized_keys
sudo -u deploy chmod 700 /home/deploy/.ssh
sudo -u deploy chmod 600 /home/deploy/.ssh/github-actions-key

# Test the key works
sudo -u deploy ssh -i /home/deploy/.ssh/github-actions-key deploy@localhost "echo SSH key works!"

2. Configure Passwordless Sudo (Required)¶

The deployment workflow needs to run commands with sudo (mkdir, chown, nginx reload, etc.).

# Option A: Run the setup script (recommended)
bash /path/to/mbpanelapi/scripts/setup-deploy-user.sh

# Option B: Manually configure sudoers
sudo tee /etc/sudoers.d/deploy > /dev/null <<'EOF'
# Passwordless sudo for deploy user for documentation deployment
Defaults:deploy !lecture
Defaults:deploy !authenticate

# Deployment commands
deploy ALL=(ALL) NOPASSWD: /bin/mkdir, /bin/chown, /bin/chmod, /bin/rm, /bin/mv, /usr/bin/find, /bin/cp, /bin/rmdir

# Nginx management
deploy ALL=(ALL) NOPASSWD: /usr/sbin/nginx, /bin/systemctl reload nginx, /bin/systemctl status nginx
EOF

# Set correct permissions
sudo chmod 440 /etc/sudoers.d/deploy

# Verify syntax
sudo visudo -c

Test passwordless sudo:

sudo -u deploy sudo -n whoami
# Should output "root" without password prompt

3. Add GitHub Secrets¶

Get the private key:

sudo cat /home/deploy/.ssh/github-actions-key

Add these secrets to your GitHub repository:

Secret Name	Value
`PRODUCTION_HOST`	your-server.com
`PRODUCTION_USER`	deploy
`PRODUCTION_SSH_KEY`	[paste entire private key]
`PRODUCTION_PATH`	/var/www/mbpanel-docs
`PRODUCTION_URL`	https://docs.yourdomain.com

4. Test Connection¶

Create a test workflow or use workflow_dispatch:

name: Test SSH Connection

on:
  workflow_dispatch:

jobs:
  test-ssh:
    runs-on: ubuntu-latest
    steps:
    - name: Test SSH
      uses: appleboy/ssh-action@v1.0.3
      with:
        host: ${{ secrets.PRODUCTION_HOST }}
        username: ${{ secrets.PRODUCTION_USER }}
        key: ${{ secrets.PRODUCTION_SSH_KEY }}
        script: |
          whoami
          sudo whoami
          ls -la /var/www/mbpanel-docs/

Deployment Workflow¶

Once configured, documentation deployment is automatic: - Push to dev-* branch → Builds and deploys to production - Create PR → Builds documentation (no deployment)

Troubleshooting¶

SSH connection fails:

# On server, check permissions
sudo ls -la /home/deploy/.ssh/

# Test SSH locally
sudo -u deploy ssh -i /home/deploy/.ssh/github-actions-key deploy@localhost "echo test"

# Check SSH logs
sudo journalctl -u sshd | grep "deploy"

Sudo password prompt appears:

# Test passwordless sudo
sudo -u deploy sudo -n whoami

# Check sudoers configuration
sudo cat /etc/sudoers.d/deploy

# Verify sudoers syntax
sudo visudo -c

Permission denied on rsync:

# Check deploy path ownership
ls -la /var/www/ | grep mbpanel-docs

# The nginx user should own the files, deploy user needs sudo to modify
sudo chown -R nginx:nginx /var/www/mbpanel-docs

Security Notes¶

The SSH key has no passphrase (required for GitHub Actions)
Only the deploy user can use this key
Passwordless sudo is restricted to specific commands only
Key is stored securely in GitHub Secrets
You can rotate the key anytime by regenerating on server