cue-ai 0.3.0

package/resources/skills/skills/hostinger/vps/deployment-workflow.md

@@ -0,0 +1,375 @@
+# SSH-First Deployment Workflow for Hostinger VPS
+
+End-to-end operational guide for deploying and managing Dockerized applications on Hostinger VPS. Uses SSH + Docker Compose as the primary deployment mechanism, with the Hostinger API for account-level infrastructure operations.
+
+## When to Use This vs. Docker Manager API
+
+| Use SSH + Docker Compose | Use Hostinger Docker Manager API |
+|--------------------------|----------------------------------|
+| Production deployments with existing compose files | Quick prototyping without SSH access |
+| Complex multi-service apps with migrations | Simple single-container deployments |
+| When you need fine-grained control over startup order | When you want to deploy from a GitHub URL |
+| When the repo already has deployment scripts | When you don't need custom startup logic |
+
+**Rule of thumb:** If the project already has a working `docker-compose.yaml` and deployment scripts, use SSH. Don't replace a working SSH + Docker Compose workflow with the Docker Manager API unless explicitly requested.
+
+## Workflow Overview
+
+```
+1. Gather Inputs → 2. SSH Key Setup → 3. VPS Baseline → 4. Deploy/Update → 5. Verify → 6. Rollback Plan → 7. API Guardrails
+```
+
+## Step 1: Gather Inputs
+
+Collect these values before running any commands:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `HOSTINGER_API_TOKEN` | API bearer token | From hPanel > Profile > API |
+| `HOSTINGER_VPS_ID` | Virtual machine ID | `12345` |
+| `SSH_USER` | SSH username | `root` |
+| `SSH_HOST` | VPS IP or hostname | `198.51.100.10` |
+| `SSH_PRIVATE_KEY_PATH` | Path to SSH private key | `~/.ssh/hostinger_vps` |
+| `REMOTE_APP_DIR` | App directory on VPS | `~/app` |
+
+```bash
+export HOSTINGER_API_TOKEN="your-token"
+export HOSTINGER_VPS_ID="12345"
+export SSH_USER="root"
+export SSH_HOST="198.51.100.10"
+export SSH_KEY="~/.ssh/hostinger_vps"
+export REMOTE_APP_DIR="~/app"
+```
+
+**Important:** If the current repository already has deployment scripts or runbooks, reuse them first rather than reimplementing generic commands.
+
+## Step 2: SSH Key Setup
+
+### Generate a Keypair (if missing)
+
+```bash
+ssh-keygen -t ed25519 -C "hostinger-vps" -f ~/.ssh/hostinger_vps
+```
+
+### Register and Attach via Hostinger API
+
+```bash
+# 1. Register the public key in your Hostinger account
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/public-keys" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"name\": \"deploy-key-$(hostname)\",
+    \"key\": \"$(cat ~/.ssh/hostinger_vps.pub)\"
+  }"
+# Note the returned key ID
+
+# 2. Attach the key to your VPS
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/public-keys/attach/$HOSTINGER_VPS_ID" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "ids": [KEY_ID_FROM_STEP_1] }'
+
+# 3. Verify SSH access
+ssh -i ~/.ssh/hostinger_vps $SSH_USER@$SSH_HOST "echo SSH_OK && whoami && hostname"
+```
+
+**Python SDK:**
+
+```python
+from hostinger_api import Hostinger
+import subprocess
+
+client = Hostinger(api_token="YOUR_API_TOKEN")
+
+# Read public key
+with open(os.path.expanduser("~/.ssh/hostinger_vps.pub")) as f:
+    pub_key = f.read().strip()
+
+# Register key
+key = client.vps.public_keys.create(name="deploy-key", key=pub_key)
+
+# Attach to VPS
+client.vps.public_keys.attach(vm_id=12345, ids=[key.id])
+
+# Verify SSH
+result = subprocess.run(
+    ["ssh", "-i", "~/.ssh/hostinger_vps", "root@198.51.100.10", "echo SSH_OK"],
+    capture_output=True, text=True
+)
+assert "SSH_OK" in result.stdout
+```
+
+## Step 3: VPS Baseline (First-Time Setup)
+
+Run these checks on the VPS via SSH before the first deployment:
+
+```bash
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'SETUP'
+# Install Docker (Ubuntu/Debian)
+if ! command -v docker &> /dev/null; then
+    curl -fsSL https://get.docker.com | sh
+    systemctl enable docker
+    systemctl start docker
+fi
+
+# Install Docker Compose plugin
+if ! docker compose version &> /dev/null; then
+    apt-get update && apt-get install -y docker-compose-plugin
+fi
+
+# Create deployment directory
+mkdir -p ~/app
+
+# Verify
+docker --version
+docker compose version
+SETUP
+```
+
+### Baseline Checklist
+
+- [ ] Docker engine installed and running
+- [ ] Docker Compose plugin available (`docker compose version`)
+- [ ] Deployment directory exists
+- [ ] `.env` file exists with all required variables (non-empty)
+- [ ] Firewall allows SSH (22) and required app ports only
+- [ ] Database ports are NOT publicly exposed unless explicitly needed
+
+### Configure Firewall via API
+
+```bash
+# Create firewall with SSH + app ports only
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/firewall" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "name": "app-deploy" }'
+
+# Add SSH rule
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/firewall/FW_ID/rules" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "protocol": "tcp", "port": "22", "source": "0.0.0.0/0", "action": "accept" }'
+
+# Add app port (e.g., 443 for HTTPS)
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/firewall/FW_ID/rules" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "protocol": "tcp", "port": "443", "source": "0.0.0.0/0", "action": "accept" }'
+
+# Activate and sync
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/firewall/FW_ID/activate/$HOSTINGER_VPS_ID" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+```
+
+## Step 4: Deploy and Update
+
+### First Deployment
+
+```bash
+# 1. Sync project files to VPS
+rsync -avz -e "ssh -i $SSH_KEY" \
+  --exclude='.git' \
+  --exclude='node_modules' \
+  --exclude='.env.local' \
+  ./ $SSH_USER@$SSH_HOST:$REMOTE_APP_DIR/
+
+# 2. Copy environment file (never commit this)
+scp -i $SSH_KEY .env.production $SSH_USER@$SSH_HOST:$REMOTE_APP_DIR/.env
+
+# 3. Deploy on VPS
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'DEPLOY'
+cd ~/app
+
+# Start database dependencies first
+docker compose up -d db redis
+
+# Wait for DB to be ready
+echo "Waiting for database..."
+sleep 10
+
+# Run migrations
+docker compose run --rm app npm run migrate
+# or: docker compose run --rm app python manage.py migrate
+
+# Start application services
+docker compose up -d
+
+# Verify
+docker compose ps
+docker compose logs --tail=50
+DEPLOY
+```
+
+### Subsequent Updates
+
+Follow the same order — this keeps deployments predictable:
+
+```bash
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'UPDATE'
+cd ~/app
+
+# Pull latest images (if using registry)
+docker compose pull
+
+# Or sync updated code first (if building locally)
+# rsync done before this SSH session
+
+# Restart with minimal downtime
+docker compose up -d --build
+
+# Run any new migrations
+docker compose run --rm app npm run migrate
+
+# Verify
+docker compose ps
+docker compose logs --tail=50 app
+UPDATE
+```
+
+**Key rules for updates:**
+- Keep the same startup order: dependencies → migrations → app
+- Avoid `docker compose down -v` — this destroys volumes and data
+- Use `docker compose up -d` which recreates only changed services
+- Commands should be idempotent — safe to run multiple times
+
+## Step 5: Verify
+
+Three levels of verification, from infrastructure to functionality:
+
+### Level 1: Container Health
+
+```bash
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'CHECK'
+cd ~/app
+
+# All containers should show "Up" or "healthy"
+docker compose ps
+
+# Check for restart loops
+docker compose ps --format json | jq '.[] | select(.State != "running")'
+CHECK
+```
+
+### Level 2: Application Logs
+
+```bash
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'LOGS'
+cd ~/app
+
+# Recent logs from app service
+docker compose logs --tail=200 app
+
+# Check for errors across all services
+docker compose logs --tail=100 | grep -i "error\|fatal\|exception"
+LOGS
+```
+
+### Level 3: Functional Smoke Test
+
+```bash
+# HTTP health check (from local machine or VPS)
+curl -sf https://your-app.example.com/health || echo "HEALTH CHECK FAILED"
+
+# Or from VPS internally
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "curl -sf http://localhost:3000/health"
+```
+
+For application-specific tests (e.g., Discord bot, API endpoints), run a real end-to-end test from the client surface to confirm the deployed service works as expected.
+
+## Step 6: Rollback
+
+### Pre-Deploy Safety Net
+
+**Always** before risky deployments (database migrations, major version bumps):
+
+```bash
+# Create VPS snapshot via API
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/$HOSTINGER_VPS_ID/snapshot" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+
+# And/or create a database backup on VPS
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'BACKUP'
+cd ~/app
+docker compose exec db pg_dump -U postgres mydb > /tmp/backup_$(date +%Y%m%d_%H%M%S).sql
+# or for MySQL:
+# docker compose exec db mysqldump -u root -p mydb > /tmp/backup_$(date +%Y%m%d_%H%M%S).sql
+BACKUP
+```
+
+### If Deploy Fails
+
+```bash
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST << 'ROLLBACK'
+cd ~/app
+
+# 1. Restore previous compose/image version
+git checkout HEAD~1 -- docker-compose.yaml
+# or: docker compose pull app:previous-tag
+
+# 2. Restart services
+docker compose up -d
+
+# 3. If migration was incompatible, restore DB
+docker compose exec -T db psql -U postgres mydb < /tmp/backup_YYYYMMDD_HHMMSS.sql
+
+# 4. Verify
+docker compose ps
+docker compose logs --tail=50
+ROLLBACK
+```
+
+### Full VPS Rollback (Nuclear Option)
+
+```bash
+# Restore from VPS snapshot (overwrites everything)
+curl -sS -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/$HOSTINGER_VPS_ID/snapshot/restore" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+```
+
+## Step 7: Hostinger API — When to Use What
+
+| Operation | Use SSH | Use API |
+|-----------|---------|---------|
+| Deploy/update app | Yes | No (unless using Docker Manager for simple cases) |
+| Run migrations | Yes | No |
+| View logs | Yes | No |
+| Register SSH keys | No | Yes |
+| Configure firewall | No | Yes |
+| Create snapshots/backups | No | Yes |
+| Check VM status | Either | Yes (for automation) |
+| Restart VM | Either | Yes |
+| Install Monarx malware scanner | No | Yes |
+
+## Safety Rules
+
+1. **Never print secrets** in terminal output — use env vars, not inline values
+2. **Never commit `.env` files** — add to `.gitignore`
+3. **Never run `docker compose down -v`** in production unless explicitly approved — this destroys data volumes
+4. **Validate critical env vars** before deployment — check `.env` has non-empty values for required keys
+5. **Keep commands idempotent** — every command should be safe to run multiple times
+6. **Snapshot before migrations** — database schema changes are the riskiest part of any deploy
+7. **Don't expose database ports** publicly unless explicitly needed — keep them internal to the Docker network
+
+## Quick Reference: Common SSH Commands
+
+```bash
+# Deploy
+rsync -avz -e "ssh -i $SSH_KEY" ./ $SSH_USER@$SSH_HOST:~/app/
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "cd ~/app && docker compose up -d"
+
+# Status
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "cd ~/app && docker compose ps"
+
+# Logs
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "cd ~/app && docker compose logs --tail=100"
+
+# Restart
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "cd ~/app && docker compose restart"
+
+# Shell into container
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "cd ~/app && docker compose exec app sh"
+
+# DB backup
+ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "cd ~/app && docker compose exec db pg_dump -U postgres mydb > /tmp/backup.sql"
+```

package/resources/skills/skills/hostinger/vps/docker-patterns.md

@@ -0,0 +1,281 @@
+# Docker Deployment Patterns on Hostinger VPS
+
+Deep dive into deploying and managing Docker Compose projects via the Hostinger VPS API.
+
+## Deployment Methods
+
+### From Inline Content
+
+Provide `docker-compose.yaml` content directly in the API request. Best for simple projects or when you want full control over the compose file.
+
+**curl:**
+
+```bash
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_name": "webapp",
+    "content": "version: \"3.8\"\nservices:\n  web:\n    image: nginx:alpine\n    ports:\n      - \"80:80\"\n    volumes:\n      - ./html:/usr/share/nginx/html\n  db:\n    image: postgres:16\n    environment:\n      POSTGRES_PASSWORD: secret\n    volumes:\n      - pgdata:/var/lib/postgresql/data\nvolumes:\n  pgdata:"
+  }'
+```
+
+**TypeScript SDK:**
+
+```typescript
+import { Hostinger } from "hostinger-api-sdk";
+
+const client = new Hostinger({ apiToken: "YOUR_API_TOKEN" });
+
+await client.vps.docker.createProject(12345, {
+  projectName: "webapp",
+  content: `
+version: "3.8"
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: secret
+`,
+});
+```
+
+**PHP SDK:**
+
+```php
+use Hostinger\Api\HostingerApi;
+
+$client = new HostingerApi('YOUR_API_TOKEN');
+
+$client->vps->docker->createProject(12345, [
+    'project_name' => 'webapp',
+    'content' => 'version: "3.8"
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "80:80"',
+]);
+```
+
+### From GitHub Repository
+
+Provide a GitHub URL — the API auto-resolves to `docker-compose.yaml` in the master branch.
+
+```bash
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_name": "my-app",
+    "url": "https://github.com/user/repo"
+  }'
+```
+
+### From Any URL
+
+Any URL that returns raw `docker-compose.yaml` content works.
+
+```bash
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_name": "my-app",
+    "url": "https://raw.githubusercontent.com/user/repo/main/docker-compose.yaml"
+  }'
+```
+
+## Common Application Stacks
+
+### WordPress with MySQL
+
+```yaml
+version: "3.8"
+services:
+  wordpress:
+    image: wordpress:latest
+    ports:
+      - "80:80"
+    environment:
+      WORDPRESS_DB_HOST: db
+      WORDPRESS_DB_USER: wordpress
+      WORDPRESS_DB_PASSWORD: wp_secret_123
+      WORDPRESS_DB_NAME: wordpress
+    volumes:
+      - wp_data:/var/www/html
+    depends_on:
+      - db
+  db:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: root_secret
+      MYSQL_DATABASE: wordpress
+      MYSQL_USER: wordpress
+      MYSQL_PASSWORD: wp_secret_123
+    volumes:
+      - db_data:/var/lib/mysql
+volumes:
+  wp_data:
+  db_data:
+```
+
+### Node.js API with Redis and PostgreSQL
+
+```yaml
+version: "3.8"
+services:
+  api:
+    image: node:20-alpine
+    working_dir: /app
+    command: npm start
+    ports:
+      - "3000:3000"
+    environment:
+      DATABASE_URL: postgresql://api:secret@db:5432/myapp
+      REDIS_URL: redis://cache:6379
+    depends_on:
+      - db
+      - cache
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: api
+      POSTGRES_PASSWORD: secret
+      POSTGRES_DB: myapp
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+  cache:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+volumes:
+  pgdata:
+  redis_data:
+```
+
+### Reverse Proxy with SSL (Traefik)
+
+```yaml
+version: "3.8"
+services:
+  traefik:
+    image: traefik:v3.0
+    command:
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.websecure.address=:443"
+      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
+      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
+      - "--certificatesresolvers.letsencrypt.acme.email=admin@example.com"
+      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - letsencrypt:/letsencrypt
+  app:
+    image: my-app:latest
+    labels:
+      - "traefik.http.routers.app.rule=Host(`app.example.com`)"
+      - "traefik.http.routers.app.tls.certresolver=letsencrypt"
+volumes:
+  letsencrypt:
+```
+
+## Project Lifecycle Management
+
+### Monitoring Project Health
+
+```bash
+# Get all projects with container status
+curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+
+# Get detailed container stats (CPU, memory, network)
+curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/containers" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+
+# Check logs for debugging (last 300 entries)
+curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/logs" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+```
+
+### Update Workflow
+
+When you need to deploy new image versions:
+
+```bash
+# Update pulls latest images and recreates containers
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/update" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+```
+
+This preserves data volumes while refreshing containers — ideal for rolling out application updates.
+
+### Graceful Restart
+
+```bash
+# Stop all services (preserves data)
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/stop" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+
+# Start services back up
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/start" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+
+# Or restart in one step (preserves volumes and networks)
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/restart" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+```
+
+### Tear Down (Irreversible)
+
+```bash
+# Stops containers, removes networks/volumes/images
+curl -X DELETE "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/webapp/down" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
+```
+
+## Replacing Existing Projects
+
+Deploying a project with the same name as an existing one **replaces** it. Use this for zero-config redeployment:
+
+```bash
+# Redeploy with updated compose file
+curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
+  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_name": "webapp",
+    "content": "...updated compose content..."
+  }'
+```
+
+## Troubleshooting Docker Deployments
+
+### Container Keeps Restarting
+- Check logs: `GET .../docker/{name}/logs`
+- Common causes: missing environment variables, incorrect image name, port conflicts
+- Verify the image exists and is accessible from the VPS
+
+### Port Already in Use
+- Only one service can bind to a host port at a time
+- Check existing projects: `GET .../docker`
+- Use different host ports or remove conflicting projects
+
+### Out of Disk Space
+- Check VM metrics: `GET .../metrics`
+- Docker images and volumes consume disk — clean up unused projects
+- Consider upgrading the VPS plan for more storage
+
+### GitHub URL Not Working
+- URL must be in format `https://github.com/[user]/[repo]`
+- Repo must have `docker-compose.yaml` in the root of the master branch
+- For other branches, use the raw file URL instead