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

```bash
# 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**:

```bash
# 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**:
```json
{
  "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.)