foss4g-workshop/README.md

# Hands-on Coding Workshop - Serving and Displaying Vector Tiles with PostgreSQL, Tegola, and OpenLayers

This project sets up a complete OpenStreetMap (OSM) vector tile server using Tegola and PostgreSQL with PostGIS.

## Services

### PostgreSQL with PostGIS
- **Image**: `kartoza/postgis:15-3.3`
- **Database**: `osm`
- **User/Password**: `postgres/postgres`
- **Port**: `5432`
- **Extensions**: PostGIS, PostGIS Topology, hstore

### Tegola Vector Tile Server
- **Image**: `gospatial/tegola:latest`
- **Port**: `8080` (mapped to container port 8080)
- **Configuration**: `tegola_config.toml`

## Setup and Usage

### 1. Start the Services
```bash
docker-compose up -d
```

### 2. Monitor the Setup Process
The PostgreSQL container will automatically:
1. Initialize the `osm` database
2. Install PostGIS and hstore extensions
3. Install osm2pgsql package
4. Download OSM data for Bosnia and Herzegovina
5. Import the data using osm2pgsql

Monitor the progress:
```bash
docker-compose logs -f postgres
```

### 3. Verify the Setup
Check if all services are healthy:
```bash
docker-compose ps
```
Wait until all services are in the `healthy` state.

Connect to PostgreSQL to verify data:
```bash
docker exec -it workshop-postgres psql -U postgres -h 127.0.0.1 -d osm
```

Check table counts:
```sql
SELECT 'planet_osm_point' as table_name, count(*) as row_count FROM planet_osm_point
UNION ALL
SELECT 'planet_osm_line' as table_name, count(*) as row_count FROM planet_osm_line
UNION ALL
SELECT 'planet_osm_polygon' as table_name, count(*) as row_count FROM planet_osm_polygon;
```

### 4. Access Vector Tiles
Once setup is complete, access vector tiles at:
- Tegola capabilities: `http://localhost:8080/capabilities`
- Map tiles: `http://localhost:8080/maps/osm/{z}/{x}/{y}.mvt`

## Data

### OSM Data Source
- **Region**: Bosnia and Herzegovina
- **Source**: Geofabrik (https://download.geofabrik.de/europe/bosnia-herzegovina-latest.osm.pbf)
- **Update**: Manual (re-run import script to update)

### Available Layers
- **Roads**: `osm.roads` (zoom levels 9-16)
- **Buildings**: `osm.buildings` (zoom levels 12-18)

## File Structure
```
.
├── docker-compose.yml          # Docker services configuration
├── tegola_config.toml          # Tegola server configuration
├── init-scripts/               # PostgreSQL initialization scripts
│   ├── 01-init-database.sql    # Database and extensions setup
│   ├── 02-install-osm2pgsql.sh # Install osm2pgsql package
│   └── 03-download-import-osm.sh # Download and import OSM data
├── osm-data/                   # OSM data storage directory
└── README.md                   # This file
```

## Troubleshooting

### Container Issues
```bash
# Check container status
docker-compose ps

# View logs
docker-compose logs postgres
docker-compose logs tegola

# Restart services
docker-compose restart
```

### Database Issues
```bash
# Connect to database
docker exec -it workshop-postgres psql -U postgres -h 127.0.0.1 -d osm

# Check extensions
\dx

# Check tables
\dt
```

### Re-import Data
To re-import OSM data with fresh data:
```bash
# Stop services
docker-compose down

# Remove old data
docker volume rm list-workshop_postgres_data
rm -rf osm-data/*.pbf

# Start services (will trigger fresh import)
docker-compose up -d
```

## Performance Notes

- Initial setup may take 5-10 minutes depending on internet speed and system performance
- OSM data file size: ~50-100MB for Bosnia and Herzegovina
- Database size after import: ~500MB-1GB
- Memory usage: ~512MB cache for osm2pgsql import

## Map Center
The default map center is set to Mostar (17.8078, 43.3430) in `tegola_config.toml`. You may want to update this to a location within Bosnia and Herzegovina:
- Sarajevo: `[18.4131, 43.8563, 12.0]`
- Banja Luka: `[17.1910, 44.7666, 12.0]`