homelab/scripts/README.md

Homelab Infrastructure Scripts

This directory contains operational scripts for maintaining and troubleshooting homelab infrastructure services.

Directory Structure

scripts/
├── README.md                          # This file
├── fix_n8n_db_permissions.sh          # PostgreSQL permission fix for n8n
└── crawlers-exporters/                # Data export and migration tools
    ├── export_cf_dns.py               # Cloudflare DNS configuration export
    ├── cloudflare_dns_export.json     # Example DNS records export
    └── cloudflare_full_config.json    # Example full config export

Scripts

fix_n8n_db_permissions.sh

Purpose: Fix PostgreSQL 15+ permission issues for n8n database

Background: PostgreSQL 15+ removed default CREATE permission from the PUBLIC role on the 'public' schema. This breaking change causes n8n database migrations to fail with "permission denied for schema public" errors.

What it does:

1. Creates timestamped backup of existing n8n database
2. Drops and recreates database with proper ownership (OWNER n8n_user)
3. Grants explicit schema permissions for PostgreSQL 15+ compatibility
4. Tests permissions by creating and dropping a test table
5. Restarts n8n service and verifies successful startup

Usage:

# Method 1: Set password via environment variable (recommended)
export N8N_DB_PASSWORD='your_password_here'
bash fix_n8n_db_permissions.sh

# Method 2: Edit DB_PASSWORD in script directly
# Edit line 28 to replace YOUR_DB_PASSWORD_HERE with actual password
bash fix_n8n_db_permissions.sh

Requirements:

• Must run as root
• PostgreSQL service must be running
• n8n service must be installed

Output:

• Database backup: /var/backups/n8n/n8n_db_backup_YYYYMMDD_HHMMSS.sql
• Log file: /var/log/n8n_db_fix_YYYYMMDD_HHMMSS.log

Expected Runtime: 15-30 seconds

See Also:

• Complete troubleshooting documentation: /home/jramos/homelab/CLAUDE_STATUS.md (section: "Post-Deployment Troubleshooting")
• n8n setup documentation: /home/jramos/homelab/n8n/N8N-SETUP-PLAN.md

---

export_cf_dns.py

Purpose: Export Cloudflare DNS configuration and zone settings for backup or migration

What it does:

1. Fetches all DNS records from specified Cloudflare zone (with pagination support)
2. Retrieves key zone settings (SSL mode, TLS version, websockets, etc.)
3. Exports combined configuration to JSON file
4. Provides clean, structured output for infrastructure-as-code workflows

Usage:

# Method 1: Set credentials via environment variables (recommended)
export CF_ZONE_ID='your_zone_id_here'
export CF_API_TOKEN='your_api_token_here'
python3 export_cf_dns.py

# Method 2: Edit credentials in script directly
# Edit lines 7-8 to replace placeholders with actual credentials
python3 export_cf_dns.py

Requirements:

• Python 3.6+
• requests library: pip install requests
• Cloudflare API token with Zone:Read permissions
• Cloudflare Zone ID for the target domain

Output:

• cloudflare_full_config.json - Combined DNS records and zone settings

Example Output Structure:

{
  "metadata": {
    "zone_id": "abc123...",
    "export_date": "Now"
  },
  "zone_settings": {
    "ssl": "strict",
    "always_use_https": "on",
    "min_tls_version": "1.2",
    "websockets": "on"
  },
  "dns_records": [
    {
      "name": "example.com",
      "type": "A",
      "content": "192.168.1.1",
      "proxied": true,
      "ttl": 1
    }
  ]
}

Use Cases:

• Backup DNS configuration before major changes
• Document current DNS state for disaster recovery
• Export for migration to another Cloudflare account
• Generate infrastructure-as-code templates

Security Notes

• Scripts in this directory may require credentials to be set via environment variables
• Never commit scripts containing plaintext passwords to version control
• Use .gitignore to exclude credential-containing variants
• Delete or shred scripts with embedded credentials after use

Contributing

When adding new scripts:

1. Include comprehensive header comments explaining purpose and usage
2. Parameterize credentials (use environment variables or prompts)
3. Add error handling and logging
4. Document in this README
5. Follow bash best practices (set -euo pipefail, quote variables, etc.)