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