KNEL-SwEng-Platform-GIS/GEOCoder/GISGraphy-App/Setup-Guide.md

Gisgraphy Docker Compose Setup Guide

This repository provides a Docker Compose configuration for running Gisgraphy - 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

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

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

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

# CHANGE THIS PASSWORD for security!
POSTGRES_PASSWORD=your_secure_password_here

Step 3: Create Data Directory Structure

Option A: Using the setup script (recommended)

# 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

# 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

# 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

# .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

# .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

# 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

# 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

# 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)

# 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

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

# Increase memory allocation
JAVA_OPTS=-Xmx4g -Xms2g

# Or for limited resources
JAVA_OPTS=-Xmx1g -Xms512m

---

🚨 Troubleshooting

Common Issues

Container won't start:

# Check logs
docker-compose logs gisgraphy

# Verify ports are available
netstat -tulpn | grep :[YOUR_PORT]

# Check disk space
df -h

Permission errors:

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

# 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

# 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
• Docker Hub Repository
• Original GitHub Repository

---

🆘 Getting Help

If you encounter issues:

1. Check the troubleshooting section 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)