notes. rollup cpature.
This commit is contained in:
338
GEOCoder/GISGraphy-App/Setup-Guide.md
Normal file
338
GEOCoder/GISGraphy-App/Setup-Guide.md
Normal file
@@ -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)*
|
||||
Reference in New Issue
Block a user