From 5503b22efcca86705e44f6fa30580b954d991788 Mon Sep 17 00:00:00 2001
From: ReachableCEO <charles@turnsys.com>
Date: Sun, 20 Jul 2025 13:44:50 -0500
Subject: [PATCH] putting a self hosted geocoder together. a key pre-requiste
 for any mapping stuff we do.

---
 GEOCoder/GISGraphy/.env               |  25 ++
 GEOCoder/GISGraphy/Setup-Guide.md     | 338 ++++++++++++++++++++++++++
 GEOCoder/GISGraphy/docker-compose.yml |  51 ++++
 GEOCoder/GISGraphy/setup-gisgraphy.sh |  82 +++++++
 4 files changed, 496 insertions(+)
 create mode 100644 GEOCoder/GISGraphy/.env
 create mode 100644 GEOCoder/GISGraphy/Setup-Guide.md
 create mode 100644 GEOCoder/GISGraphy/docker-compose.yml
 create mode 100644 GEOCoder/GISGraphy/setup-gisgraphy.sh

diff --git a/GEOCoder/GISGraphy/.env b/GEOCoder/GISGraphy/.env
new file mode 100644
index 0000000..73837ff
--- /dev/null
+++ b/GEOCoder/GISGraphy/.env
@@ -0,0 +1,25 @@
+# Gisgraphy Docker Compose Environment Variables
+
+# IMPORTANT: Change these paths and ports for your environment!
+# Data Directory Configuration - CUSTOMIZE THIS PATH
+GISGRAPHY_DATA_DIR=/home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy
+
+# Port Configuration - CUSTOMIZE THESE PORTS
+GISGRAPHY_WEB_PORT=12001
+GISGRAPHY_API_PORT=12002
+
+# PostgreSQL Configuration
+POSTGRES_PASSWORD=gisgraphy123
+
+# Gisgraphy Configuration
+GISGRAPHY_HOST=localhost
+
+# Java Configuration (adjust based on your system resources)
+JAVA_OPTS=-Xmx2g -Xms1g
+
+# Optional: Custom hostname for the container
+CONTAINER_HOSTNAME=gisgraphy.local
+
+# Data Import Configuration (if using premium dumps)
+# IMPORT_DATA=true
+# DUMP_PATH=/opt/dumps
\ No newline at end of file
diff --git a/GEOCoder/GISGraphy/Setup-Guide.md b/GEOCoder/GISGraphy/Setup-Guide.md
new file mode 100644
index 0000000..cf569db
--- /dev/null
+++ b/GEOCoder/GISGraphy/Setup-Guide.md
@@ -0,0 +1,338 @@
+# Gisgraphy Docker Compose Setup Guide
+
+This repository provides a Docker Compose configuration for running [Gisgraphy](https://www.gisgraphy.com/) - a geographical search engine and geocoding service.
+
+## 🚨 **IMPORTANT: Customize Before Use**
+
+**⚠️ You MUST customize the following before deployment:**
+
+1. **📁 Data Directory Path** - Change the storage location to match your environment
+2. **🌐 Port Numbers** - Ensure ports don't conflict with other services
+3. **🔐 Database Password** - Change the default password for security
+
+---
+
+## 📋 **Prerequisites**
+
+- Docker and Docker Compose installed
+- Sufficient disk space (recommend 10GB+ for data storage)
+- Available ports for web interface and API
+
+---
+
+## 🛠️ **Quick Setup**
+
+### Step 1: Clone and Prepare
+
+```bash
+# Clone or download this repository
+git clone <your-repo-url>
+cd gisgraphy-docker
+
+# Make setup script executable
+chmod +x setup-gisgraphy.sh
+```
+
+### Step 2: **🔧 CUSTOMIZE Configuration**
+
+#### **📁 Data Directory** (REQUIRED)
+Edit the `.env` file and change the data directory path:
+
+```bash
+# CHANGE THIS PATH to match your environment!
+GISGRAPHY_DATA_DIR=/your/custom/path/to/gisgraphy/data
+
+# Examples:
+# GISGRAPHY_DATA_DIR=/home/username/docker-data/gisgraphy
+# GISGRAPHY_DATA_DIR=/opt/docker-data/gisgraphy
+# GISGRAPHY_DATA_DIR=/data/services/gisgraphy
+```
+
+#### **🌐 Port Configuration** (REQUIRED)
+Edit the `.env` file and set your desired ports:
+
+```bash
+# CHANGE THESE PORTS to avoid conflicts!
+GISGRAPHY_WEB_PORT=12001    # Web interface port
+GISGRAPHY_API_PORT=12002    # API port
+
+# Examples for different environments:
+# Development: 8080, 8081
+# Production: 80, 443 (with reverse proxy)
+# Multiple instances: 12001/12002, 13001/13002, etc.
+```
+
+#### **🔐 Security Configuration** (RECOMMENDED)
+Change the default database password:
+
+```bash
+# CHANGE THIS PASSWORD for security!
+POSTGRES_PASSWORD=your_secure_password_here
+```
+
+### Step 3: Create Data Directory Structure
+
+**Option A: Using the setup script (recommended)**
+```bash
+# Customize these values for your environment
+./setup-gisgraphy.sh /your/custom/path/to/gisgraphy/data yourusername
+
+# Example:
+./setup-gisgraphy.sh /home/john/docker-data/gisgraphy john
+```
+
+**Option B: Manual setup**
+```bash
+# Replace with your custom path and username
+DATA_DIR="/your/custom/path/to/gisgraphy/data"
+USERNAME="yourusername"
+
+mkdir -p "$DATA_DIR"/{data,app,logs,config,dumps}
+sudo chown -R "$USERNAME:$USERNAME" "$DATA_DIR"
+chmod -R 755 "$DATA_DIR"
+```
+
+### Step 4: Deploy
+
+```bash
+# Start the services
+docker-compose up -d
+
+# Check status
+docker-compose ps
+
+# View logs
+docker-compose logs -f
+```
+
+### Step 5: Access Gisgraphy
+
+Open your browser and navigate to:
+```
+http://localhost:[YOUR_WEB_PORT]
+
+# Examples:
+# http://localhost:12001
+# http://localhost:8080
+```
+
+---
+
+## 📂 **Data Directory Structure**
+
+Your configured data directory will contain:
+
+```
+/your/custom/path/to/gisgraphy/data/
+├── data/       # PostgreSQL database files
+├── app/        # Gisgraphy application files
+├── logs/       # Application and system logs  
+├── config/     # Custom configuration files (optional)
+└── dumps/      # Data import files (optional)
+```
+
+---
+
+## ⚙️ **Configuration Examples**
+
+### Development Environment
+```bash
+# .env file for development
+GISGRAPHY_DATA_DIR=/home/dev/gisgraphy-data
+GISGRAPHY_WEB_PORT=8080
+GISGRAPHY_API_PORT=8081
+POSTGRES_PASSWORD=dev_password
+```
+
+### Production Environment
+```bash
+# .env file for production (behind reverse proxy)
+GISGRAPHY_DATA_DIR=/opt/production/gisgraphy
+GISGRAPHY_WEB_PORT=12001
+GISGRAPHY_API_PORT=12002
+POSTGRES_PASSWORD=super_secure_production_password
+```
+
+### Multiple Instances
+```bash
+# Instance 1
+GISGRAPHY_DATA_DIR=/data/gisgraphy-instance1
+GISGRAPHY_WEB_PORT=13001
+GISGRAPHY_API_PORT=13002
+
+# Instance 2 (separate .env file)
+GISGRAPHY_DATA_DIR=/data/gisgraphy-instance2
+GISGRAPHY_WEB_PORT=14001
+GISGRAPHY_API_PORT=14002
+```
+
+---
+
+## 🔧 **Management Commands**
+
+### Basic Operations
+```bash
+# Start services
+docker-compose up -d
+
+# Stop services  
+docker-compose down
+
+# Restart services
+docker-compose restart
+
+# View status
+docker-compose ps
+
+# View logs
+docker-compose logs -f gisgraphy
+```
+
+### Maintenance
+```bash
+# Update to latest image
+docker-compose pull
+docker-compose up -d
+
+# Access container shell
+docker-compose exec gisgraphy bash
+
+# Check resource usage
+docker stats
+```
+
+---
+
+## 💾 **Backup and Restore**
+
+### Simple Backup (recommended)
+```bash
+# Backup entire data directory
+sudo tar czf gisgraphy-backup-$(date +%Y%m%d).tar.gz -C /your/custom/path/to/gisgraphy .
+
+# Restore from backup
+sudo tar xzf gisgraphy-backup-YYYYMMDD.tar.gz -C /your/custom/path/to/gisgraphy
+```
+
+### Database-Only Backup
+```bash
+# Backup database
+docker-compose exec gisgraphy pg_dump -U gisgraphy gisgraphy > backup.sql
+
+# Restore database
+docker-compose exec -T gisgraphy psql -U gisgraphy gisgraphy < backup.sql
+```
+
+---
+
+## 🎯 **Advanced Configuration**
+
+### Custom Configuration Files
+1. Place custom Gisgraphy config files in: `[DATA_DIR]/config/`
+2. Restart container: `docker-compose restart`
+
+### Data Import
+1. Place premium dump files in: `[DATA_DIR]/dumps/`
+2. Access container: `docker-compose exec gisgraphy bash`
+3. Run import scripts from within the container
+
+### Performance Tuning
+Edit `.env` file:
+```bash
+# Increase memory allocation
+JAVA_OPTS=-Xmx4g -Xms2g
+
+# Or for limited resources
+JAVA_OPTS=-Xmx1g -Xms512m
+```
+
+---
+
+## 🚨 **Troubleshooting**
+
+### Common Issues
+
+**Container won't start:**
+```bash
+# Check logs
+docker-compose logs gisgraphy
+
+# Verify ports are available
+netstat -tulpn | grep :[YOUR_PORT]
+
+# Check disk space
+df -h
+```
+
+**Permission errors:**
+```bash
+# Fix ownership (replace with your username and path)
+sudo chown -R yourusername:yourusername /your/custom/path/to/gisgraphy
+
+# Fix permissions  
+chmod -R 755 /your/custom/path/to/gisgraphy
+```
+
+**Port conflicts:**
+```bash
+# Check what's using your port
+sudo netstat -tulpn | grep :[YOUR_PORT]
+
+# Change ports in .env file and restart
+docker-compose down
+docker-compose up -d
+```
+
+**Performance issues:**
+- Increase memory allocation in `.env` file
+- Ensure sufficient disk space
+- Monitor with: `docker stats`
+
+### Health Check
+```bash
+# Check if service is responding
+curl http://localhost:[YOUR_WEB_PORT]/
+
+# View health status
+docker-compose ps
+```
+
+---
+
+## 🔒 **Security Considerations**
+
+1. **Change default passwords** in `.env` file
+2. **Restrict network access** as needed
+3. **Keep images updated** regularly
+4. **Backup data** regularly
+5. **Use reverse proxy** with SSL for production
+
+---
+
+## 📚 **Additional Resources**
+
+- [Gisgraphy Official Documentation](https://www.gisgraphy.com/documentation/)
+- [Docker Hub Repository](https://hub.docker.com/r/gisgraphy/gisgraphyofficial/)
+- [Original GitHub Repository](https://github.com/gisgraphy/gisgraphy-docker)
+
+---
+
+## 🆘 **Getting Help**
+
+If you encounter issues:
+
+1. Check the [troubleshooting section](#-troubleshooting) above
+2. Review Docker Compose logs: `docker-compose logs`
+3. Verify your `.env` configuration matches your environment
+4. Ensure proper file permissions and ownership
+5. Check available system resources (memory, disk space)
+
+---
+
+## 📄 **License**
+
+This configuration is provided "as is" without warranty. Use at your own risk.
+
+---
+
+*Last updated: $(date +%Y-%m-%d)*
\ No newline at end of file
diff --git a/GEOCoder/GISGraphy/docker-compose.yml b/GEOCoder/GISGraphy/docker-compose.yml
new file mode 100644
index 0000000..51d8686
--- /dev/null
+++ b/GEOCoder/GISGraphy/docker-compose.yml
@@ -0,0 +1,51 @@
+services:
+  gisgraphy:
+    image: gisgraphy/gisgraphyofficial:latest
+    container_name: KNELDevStack-CDS-gisgraphy-server
+    hostname: gisgraphy.local
+    ports:
+      - "${GISGRAPHY_WEB_PORT:-12001}:8080"   # Web interface
+      - "${GISGRAPHY_API_PORT:-12002}:8081"   # Additional Gisgraphy port if needed
+    environment:
+      - PGPASSWORD=${POSTGRES_PASSWORD:-gisgraphy123}
+      - JAVA_OPTS=-Xmx2g -Xms1g
+    volumes:
+      # Persist PostgreSQL data
+      - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/data:/var/lib/postgresql/data
+      # Persist Gisgraphy application data
+      - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/app:/usr/local/gisgraphy
+      # Persist logs
+      - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/logs:/var/log/gisgraphy
+      # Optional: Mount custom configuration
+      - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/config:/usr/local/gisgraphy/config:ro
+      # Optional: Mount data dumps for import
+      - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/dumps:/opt/dumps:ro
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+  # Optional: Separate PostgreSQL service if you want to manage DB separately
+  # Uncomment the section below if you prefer a separate database container
+  # 
+  # postgres:
+  #   image: postgis/postgis:13-3.1
+  #   container_name: gisgraphy-postgres
+  #   environment:
+  #     - POSTGRES_DB=gisgraphy
+  #     - POSTGRES_USER=gisgraphy
+  #     - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-gisgraphy123}
+  #     - POSTGRES_INITDB_ARGS="--encoding=UTF-8 --locale=en_US.UTF-8"
+  #   volumes:
+  #     - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/postgres:/var/lib/postgresql/data
+  #     - /home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy/init-scripts:/docker-entrypoint-initdb.d:ro
+  #   ports:
+  #     - "5432:5432"
+  #   restart: unless-stopped
+
+networks:
+  default:
+    name: gisgraphy-network
\ No newline at end of file
diff --git a/GEOCoder/GISGraphy/setup-gisgraphy.sh b/GEOCoder/GISGraphy/setup-gisgraphy.sh
new file mode 100644
index 0000000..82ec0b1
--- /dev/null
+++ b/GEOCoder/GISGraphy/setup-gisgraphy.sh
@@ -0,0 +1,82 @@
+#!/bin/bash
+
+# Gisgraphy Docker Setup Script
+# This script creates the necessary directory structure and sets permissions
+
+set -e
+
+# Default configuration - CUSTOMIZE THESE VALUES
+DEFAULT_DATA_DIR="/home/localuser/KNELDevStack-CDS/docker-data/GIS/gisgraphy"
+DEFAULT_USER="localuser"
+
+# Allow command line arguments to override defaults
+DATA_DIR="${1:-$DEFAULT_DATA_DIR}"
+USER="${2:-$DEFAULT_USER}"
+
+echo "🚀 Setting up Gisgraphy data directory structure..."
+echo "📁 Data directory: $DATA_DIR"
+echo "👤 User: $USER"
+echo ""
+
+# Validate user exists
+if ! id "$USER" &>/dev/null; then
+    echo "❌ Error: User '$USER' does not exist!"
+    echo "💡 Usage: $0 [DATA_DIR] [USER]"
+    echo "💡 Example: $0 /path/to/your/data/gisgraphy yourusername"
+    exit 1
+fi
+
+# Create the main data directory and subdirectories
+echo "📂 Creating directory structure at $DATA_DIR"
+mkdir -p "$DATA_DIR"/{data,app,logs,config,dumps}
+
+# Set ownership
+echo "🔑 Setting ownership to $USER:$USER"
+sudo chown -R "$USER:$USER" "$DATA_DIR"
+
+# Set permissions
+echo "🔒 Setting permissions (755)"
+chmod -R 755 "$DATA_DIR"
+
+# Create a simple README in the data directory
+cat > "$DATA_DIR/README.md" << EOF
+# Gisgraphy Data Directory
+
+This directory contains all persistent data for your Gisgraphy Docker setup.
+
+## Directory Structure:
+- **data/**: PostgreSQL database files
+- **app/**: Gisgraphy application files and configuration  
+- **logs/**: Application and system logs
+- **config/**: Custom Gisgraphy configuration files (place custom configs here)
+- **dumps/**: Data import files (place premium dump files here)
+
+## Configuration:
+- Data Path: $DATA_DIR
+- Owner: $USER
+- Created: $(date)
+
+## Setup by: Gisgraphy Docker Compose configuration
+EOF
+
+echo "✅ Directory structure created successfully!"
+echo ""
+echo "📁 Data directory: $DATA_DIR"
+echo "📋 Structure:"
+tree "$DATA_DIR" 2>/dev/null || ls -la "$DATA_DIR"
+echo ""
+echo "⚠️  IMPORTANT: Before running docker-compose:"
+echo "1. 📝 Edit .env file and update the data directory path:"
+echo "   GISGRAPHY_DATA_DIR=$DATA_DIR"
+echo ""
+echo "2. 🌐 Edit .env file and set your desired ports:"
+echo "   GISGRAPHY_WEB_PORT=12001"
+echo "   GISGRAPHY_API_PORT=12002"
+echo ""
+echo "3. 🚀 Start the services:"
+echo "   docker-compose up -d"
+echo ""
+echo "4. 🌍 Access Gisgraphy at:"
+echo "   http://localhost:12001 (or your configured port)"
+echo ""
+echo "📖 For complete setup instructions, see SetupGuide.md"
\ No newline at end of file