ip-manager/README.md

Geofeed Manager

A complete solution for managing RFC 8805 compliant IP geolocation feeds (geofeeds). This system provides a modern web interface for managing geofeed entries, stores data in MariaDB/MySQL, and automatically exports to BunnyCDN via n8n workflows.

Features

• Modern Apple-esque UI - Clean, responsive interface with dark mode support
• RFC 8805 Compliant - Generates valid geofeed CSV files per the specification
• Authentication - Secure login with environment-based credentials
• CRUD Operations - Create, read, update, and delete geofeed entries
• Search & Filter - Find entries by IP prefix, city, region, or country
• Audit Logging - Track all changes to your geofeed with detailed history
• IP Enrichment - Automatic ISP and security flag data via ipregistry.co
• Client Logos - Associate logo images with client shortnames
• Webhook Integration - Debounced n8n webhooks for on-demand CDN updates
• Mobile Optimized - Full mobile Safari support with PWA capabilities
• CSRF Protection - Secure form submissions

What's New

Authentication

• Secure login page with session-based authentication
• Credentials configured via environment variables
• Automatic session timeout after 24 hours

IP Registry Integration

• Automatic IP enrichment when entries are created or imported
• ISP and organization data displayed in the table
• Security flags for: Abuser, Attacker, Bogon, Cloud Provider, Proxy, Relay, Tor, Tor Exit, VPN, Anonymous, Threat
• Manual enrichment option for existing entries

Webhook System

• On-demand webhook notifications to n8n (replaces hourly polling)
• Debouncing to batch multiple changes and reduce API calls
• Queue status monitoring in the Advanced tab

UI Improvements

• Dark mode with automatic OS detection
• Mobile Safari optimizations with safe area support
• Client logo management with grid display

Directory Structure

geofeed-manager/
├── database/
│   ├── schema.sql          # Database schema
│   └── import_csv.php      # CSV import utility (CLI)
├── webapp/
│   ├── config.php          # Configuration & helpers
│   ├── api.php             # RESTful API endpoints
│   ├── login.php           # Authentication page
│   └── index.php           # Main web interface
├── n8n/
│   └── geofeed-export-workflow.json  # n8n workflow
├── docker-compose.yml      # Docker Compose configuration
└── .env.example            # Environment variables template

Installation (Docker / Dokploy)

The application automatically pulls code from the Git repository on startup - no local files needed!

Quick Start

1. Set environment variables in Dokploy (or create .env file):

# Git Repository
GIT_REPO=https://git.prpl.tools/PurpleComputing/geofeed-manager.git
GIT_BRANCH=main

# Database
DB_ROOT_PASSWORD=your_secure_root_password
DB_NAME=geofeed_manager
DB_USER=geofeed
DB_PASSWORD=your_secure_password

# Authentication
AUTH_USERNAME=admin
AUTH_PASSWORD=your_secure_admin_password

# IP Registry (optional - for IP enrichment)
IPREGISTRY_API_KEY=your_ipregistry_api_key

# Cloudflare Tunnel (optional)
CLOUDFLARE_TUNNEL_TOKEN=your_tunnel_token

2. Deploy with Docker Compose:

docker compose up -d

3. Access the web interface at http://your-server:8080

4. Login with your configured credentials (default: admin/changeme)

5. Import your geofeed via the Advanced tab in the UI

How It Works

On startup, a git-sync container:

1. Clones the repository from Git
2. Copies webapp/ files to the PHP container volume
3. Copies database/schema.sql for MariaDB initialization
4. Exits after sync completes

The webapp and database containers then start with the synced code.

Updating Code

To pull the latest code from Git, simply restart the stack:

docker compose down
docker compose up -d

Or in Dokploy, just redeploy the service.

Container Details

Service	Port	Description
webapp	8080	PHP web interface
mariadb	3306	MariaDB database (exposed for n8n)
git-sync	-	Pulls code on startup, then exits
cloudflared	-	Cloudflare Tunnel (optional)
phpmyadmin	8081	Database admin (optional, use --profile admin)

Configuration

Authentication

Authentication is required to access the application. Configure credentials via environment variables:

AUTH_USERNAME=admin
AUTH_PASSWORD=your_secure_password

The login session expires after 24 hours of inactivity.

IP Registry Integration

To enable automatic IP enrichment:

1. Sign up for a free API key at ipregistry.co
2. Set the API key via environment variable:

   IPREGISTRY_API_KEY=your_api_key
   

   Or configure it in the Advanced tab of the web interface.
3. Enable auto-enrichment in the Advanced tab

When enabled, new IP entries are automatically enriched with:

• ISP and organization name
• ASN information
• Connection type
• Timezone
• Security flags (proxy, VPN, Tor, threat, etc.)

Webhook Integration

Configure webhooks in the Advanced tab to notify n8n when data changes:

1. Enter your n8n webhook URL
2. Set the debounce delay (1-60 minutes)
3. Enable webhook notifications

The system batches multiple changes within the debounce window to reduce API calls.

n8n Workflow Setup

1. In n8n, go to Settings > Environment Variables and add:

   • BUNNY_STORAGE_ZONE - Your BunnyCDN storage zone name
   • BUNNY_API_KEY - Your BunnyCDN Storage API key

2. Create MySQL credentials in n8n:

   • Go to Credentials
   • Add new MySQL credential
   • Configure with your database details
   • Note the credential ID

3. Import the workflow:

   • Go to Workflows
   • Click Import from File
   • Select n8n/geofeed-export-workflow.json

4. Update credential references:

   • Open the imported workflow
   • For each MySQL node, select your MySQL credential
   • Save the workflow

5. Activate the workflow - it will trigger via webhook when data changes

API Reference

Authentication

All API endpoints (except export and webhook_process) require authentication.

List Entries

GET api.php?action=list&page=1&limit=25&search=term&country=GB&sort=ip|custom

Get Single Entry

GET api.php?action=get&id=123

Create Entry

POST api.php?action=create
Content-Type: application/json

{
  "ip_prefix": "192.168.1.0/24",
  "country_code": "GB",
  "region_code": "GB-ENG",
  "city": "London",
  "postal_code": "EC1A 1BB",
  "client_short_name": "acme",
  "notes": "Main office",
  "csrf_token": "..."
}

Update Entry

POST api.php?action=update
Content-Type: application/json

{
  "id": 123,
  "ip_prefix": "192.168.1.0/24",
  "country_code": "GB",
  "region_code": "GB-ENG",
  "city": "Manchester",
  "postal_code": "M1 1AA",
  "csrf_token": "..."
}

Delete Entry

POST api.php?action=delete
Content-Type: application/json

{
  "id": 123,
  "csrf_token": "..."
}

Export CSV

GET api.php?action=export&format=download

Get Statistics

GET api.php?action=stats

Enrich Single IP

POST api.php?action=enrich_ip
Content-Type: application/json

{
  "id": 123,
  "csrf_token": "..."
}

Enrich All Un-enriched IPs

POST api.php?action=enrich_all
Content-Type: application/json

{
  "csrf_token": "..."
}

Update Sort Order

POST api.php?action=update_sort_order
Content-Type: application/json

{
  "orders": [
    {"id": 1, "sort_order": 0},
    {"id": 2, "sort_order": 1}
  ],
  "csrf_token": "..."
}

Geofeed Format (RFC 8805)

Each line in the exported CSV follows this format:

ip_prefix,country_code,region_code,city,postal_code

Example:

# Geofeed - Generated by Geofeed Manager
# Format: ip_prefix,country_code,region_code,city,postal_code
192.168.1.0/24,GB,GB-ENG,London,EC1A 1BB
10.0.0.0/8,US,US-CA,San Francisco,94105
2001:db8::/32,DE,DE-BY,Munich,80331

BunnyCDN Setup

1. Create a Storage Zone in BunnyCDN
2. Get your Storage API key from the FTP & API Access section
3. The workflow uploads to: https://storage.bunnycdn.com/{zone}/geofeed.csv
4. Your public URL will be: https://{zone}.b-cdn.net/geofeed.csv

Security Considerations

• Always use HTTPS in production (use Cloudflare Tunnel or reverse proxy)
• Change the default admin password immediately
• Keep your database credentials secure
• The application uses session-based authentication with CSRF protection
• IP Registry API keys are stored securely and masked in the UI
• Input validation is performed on all fields

Troubleshooting

Cannot login

• Verify AUTH_USERNAME and AUTH_PASSWORD environment variables are set
• Check container logs for authentication errors
• Clear browser cookies and try again

Import fails with "Invalid IP prefix"

Ensure your IP prefixes are in valid CIDR notation (e.g., 192.168.1.0/24)

IP enrichment not working

• Verify your ipregistry.co API key is valid
• Check that auto-enrichment is enabled in the Advanced tab
• Review container logs for API errors

n8n workflow fails

• Check that environment variables are set correctly
• Verify MySQL credentials are configured
• Check BunnyCDN API key permissions

Web interface shows database error

• Verify database credentials in environment variables
• Ensure the database and tables exist
• Check MySQL/MariaDB is running

Dark mode not working

• Ensure your browser/OS has dark mode enabled
• Try clearing browser cache

License

MIT License - Feel free to use and modify as needed.

---

Built with care by Purple Computing