338 lines
7.2 KiB
Markdown
338 lines
7.2 KiB
Markdown
# 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)* |