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

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:

docker-compose logs -f postgres

3. Verify the Setup

Check if all services are healthy:

docker-compose ps

Wait until all services are in the healthy state.

Connect to PostgreSQL to verify data:

docker exec -it workshop-postgres psql -U postgres -h 127.0.0.1 -d osm

Check table counts:

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

# Check container status
docker-compose ps

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

# Restart services
docker-compose restart

Database Issues

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

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