# Playbook: Automated Document Server Deployment & CI/CD via GitHub Actions

This specification file is designed for an autonomous execution agent (e.g., Antigravity Agent) operating within the local repository and targeting a remote Linux VPS (Ubuntu/Debian).

---

## 1. Goal & Architecture

- **Service**: Standalone HTTP Document Server bound to local interface (`127.0.0.1:8080`) managed by `systemd`.
- **Gateway**: Nginx reverse proxy listening on ports `80` (HTTP) and `443` (HTTPS) pointing to `127.0.0.1:8080`.
- **Security**: TLS certificate managed automatically via Let's Encrypt / Certbot.
- **CI/CD Pipeline**: GitHub Actions triggered on push to `main`, synchronizing repository files into `/var/www/documents` on the VPS via `rsync` over SSH.

---

## 2. Environment Variables & Inputs

The agent requires the following context variables:

| Variable | Description | Example |
| :--- | :--- | :--- |
| `SERVER_IP` | Public IPv4 of target VPS | `203.0.113.10` |
| `SERVER_USER` | Remote SSH user | `ubuntu` |
| `SSH_PORT` | SSH Port | `22` |
| `DOMAIN_NAME` | Fully qualified domain/subdomain | `docs.example.com` |
| `TARGET_DIR` | Target storage path on VPS | `/var/www/documents` |

---

## 3. Remote VPS Provisioning Tasks

*The agent can execute these tasks via SSH or a remote provision script.*

### Step 3.1: Directory & Permission Setup
```bash
sudo mkdir -p /var/www/documents
sudo usermod -aG www-data "$USER"
sudo chown -R "$USER":www-data /var/www/documents
sudo chmod -R 775 /var/www/documents
```

### Step 3.2: Systemd Unit Configuration
Create `/etc/systemd/system/docserver.service`:
```ini
[Unit]
Description=Document File Server
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/documents
ExecStart=/usr/bin/python3 -m http.server 8080 --bind 127.0.0.1
Restart=always
RestartSec=3

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

Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now docserver.service
```

### Step 3.3: Nginx Installation & Virtual Host Setup
1. Install Nginx:
   ```bash
   sudo apt-get update && sudo apt-get install -y nginx
   ```

2. Create virtual host file `/etc/nginx/sites-available/docserver.conf`:
   ```nginx
   server {
       listen 80;
       server_name docs.example.com; # Replace with ${DOMAIN_NAME}

       client_max_body_size 100M;

       location / {
           proxy_pass http://127.0.0.1:8080;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }
   ```

3. Enable site and reload:
   ```bash
   sudo ln -sf /etc/nginx/sites-available/docserver.conf /etc/nginx/sites-enabled/
   sudo rm -f /etc/nginx/sites-enabled/default
   sudo nginx -t && sudo systemctl reload nginx
   ```

### Step 3.4: TLS / HTTPS Configuration via Certbot
```bash
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx --non-interactive --agree-tos -m admin@${DOMAIN_NAME} -d ${DOMAIN_NAME}
```

### Step 3.5: UFW Firewall Hardening
```bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw --force enable
```

---

## 4. Local Repository & GitHub Actions Setup

The agent will create the workflow file in the local workspace.

### Step 4.1: Create Workflow File
Path: `.github/workflows/deploy.yml`

```yaml
name: Continuous Deployment to VPS

on:
  push:
    branches:
      - main

concurrency:
  group: deploy-vps
  cancel-in-progress: true

jobs:
  deploy:
    name: Sync Documents to VPS
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Rsync Deploy to Remote Target
        uses: easingthemes/ssh-deploy@v5.1.0
        with:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
          REMOTE_HOST: ${{ secrets.SERVER_IP }}
          REMOTE_USER: ${{ secrets.SERVER_USER }}
          SSH_PORT: ${{ secrets.SSH_PORT }}
          SOURCE: "/"
          TARGET: "/var/www/documents"
          EXCLUDE: "/.git/, /.github/, /README.md"
          ARGS: "-avzr --delete"
```

---

## 5. SSH Key Pair Generation & GitHub Secrets Injection

The agent must ensure that a dedicated SSH key exists for GitHub Actions deployment:

1. **Generate SSH Key (if not present):**
   ```bash
   ssh-keygen -t ed25519 -N "" -C "github-actions-deploy" -f ./deploy_key
   ```
2. **Append Public Key to VPS:**
   Append `./deploy_key.pub` into `~/.ssh/authorized_keys` on the remote VPS.
3. **Set Secrets on GitHub Repository via GitHub CLI (`gh`):**
   ```bash
   gh secret set SERVER_IP --body "<VPS_IP>"
   gh secret set SERVER_USER --body "<VPS_USER>"
   gh secret set SSH_PORT --body "22"
   gh secret set SSH_PRIVATE_KEY < ./deploy_key
   ```
4. **Clean up local private key:**
   ```bash
   rm -f ./deploy_key ./deploy_key.pub
   ```

---

## 6. Verification & Health Check Procedure

Once committed and pushed:

1. **Verify GitHub Actions Run:**
   ```bash
   gh run list --limit 1
   ```
2. **Verify HTTP/HTTPS Response:**
   ```bash
   curl -I https://${DOMAIN_NAME}
   ```
   *Expected result: `HTTP/2 200` or `HTTP/1.1 200 OK`.*
3. **Verify Local Directory Sync:**
   Ensure test files placed in the repository root are accessible via `https://${DOMAIN_NAME}/<filename>`.