GeiserX · dependabot · Mar 15, 2026 · Mar 15, 2026 · Mar 15, 2026 · Mar 15, 2026
diff --git a/.env.example b/.env.example
@@ -17,17 +17,37 @@ DATABASE_URL=postgresql://propel:propel@localhost:5433/propel
 # ---------------------------------------------------------------------------
 
 # ISO 3166-1 alpha-2 code for initial map view (default: ES)
-# Supported: ES, FR, DE, IT, GB, AT, PT
+# Supported: ES, FR, DE, IT, GB, AT, PT, SI, NL, BE, LU, RO, GR, IE, HR
 PROPEL_DEFAULT_COUNTRY=ES
 
 # Comma-separated ISO codes to enable (default: all countries with scrapers)
 # Example: ES,FR,DE — limits the app to only those countries
-PROPEL_ENABLED_COUNTRIES=ES
+# PROPEL_ENABLED_COUNTRIES=ES,FR,PT,IT,AT,DE,GB,SI,NL,BE,LU,RO,GR,IE,HR
 
 # Override default fuel type (default: per-country, e.g. B7 for Spain)
 # See src/types/fuel.ts for valid codes
 # PROPEL_DEFAULT_FUEL=B7
 
+# Enable station clustering at low zoom levels (default: true)
+# Set to false to always show individual station points
+# PROPEL_CLUSTER_STATIONS=true
+
+# Station search corridor width in km for route planning (default: 5, range: 0.5-50)
+# PROPEL_CORRIDOR_KM=5
+
+# Price sanity bounds for scraper validation (EUR/GBP/CHF per litre)
+# Prices outside this range are rejected as bad data. Other currencies use 25x max.
+# PROPEL_PRICE_MIN=0.30
+# PROPEL_PRICE_MAX=4.00
+
+# ---------------------------------------------------------------------------
+# Scraper Schedule
+# ---------------------------------------------------------------------------
+
+# Automatic scraping interval in hours (default: 24)
+# Runs once on startup + repeats on this interval. Set to 0 to disable.
+# PROPEL_SCRAPE_INTERVAL_HOURS=24
+
 # ---------------------------------------------------------------------------
 # External Services (optional — only needed when those features are enabled)
 # ---------------------------------------------------------------------------

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -13,6 +13,7 @@ jobs:
     name: Analyze
     runs-on: ubuntu-latest
     permissions:
+      actions: read
       security-events: write
       contents: read
 

diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
@@ -52,6 +52,7 @@ jobs:
         with:
           images: ${{ env.DOCKER_IMAGE }}
           tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
             type=semver,pattern={{version}}
             type=semver,pattern={{raw}}
             type=raw,value=${{ github.event.inputs.tag }},enable=${{ github.event.inputs.tag != '' }}

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/README.md b/README.md
@@ -15,55 +15,144 @@
   <a href="https://hub.docker.com/r/drumsergio/propel"><img src="https://img.shields.io/docker/pulls/drumsergio/propel?style=flat-square&logo=docker&label=Docker%20Pulls" alt="Docker Pulls"></a>
 </p>
 
+<br>
+
 ---
 
 **No app in the world combines route planning with real-time energy prices, detour time calculation, and smart refueling recommendations. Propel does.**
 
 ## Features
 
-- Real-time fuel prices from government open data APIs (Spain, France, Germany, Italy, UK, Austria, Portugal)
-- Interactive map with 65,000+ stations across Europe
-- Route planning with energy station filtering along the route
-- "Cheapest within N minutes detour" — calculates if a detour is worth it
-- Smart refuel/recharge advisor based on your remaining range
+- Real-time fuel prices from government open data APIs across 15 European countries
+- Interactive map with 84,000+ stations across Europe
+- Route planning with geocoding autocomplete, alternative routes, and corridor station filtering
+- "Cheapest within N minutes detour" — filters stations by detour time with price comparison
+- Smart refuel/recharge advisor based on your remaining range (planned)
 - EV charging integration (planned)
 - Multi-language, multi-currency, multi-unit support
-- Self-hostable with Docker Compose
+- Fully self-hostable with Docker Compose
 - 100% open source (GPL-3.0)
 
-## Quick Start
+## Self-Hosting
+
+### Requirements
+
+| Resource | First-time build | Steady state |
+|---|---|---|
+| **RAM** | 24 GB (Valhalla 15-country tile build) | 6-8 GB |
+| **Disk** | ~250 GB (15-country Photon + Valhalla) | ~80 GB |
+| **CPU** | Multi-core recommended | Any |
+
+> **Important**: On first start, Valhalla builds routing tiles from OpenStreetMap data (3-6 hours for 15 countries) and Photon imports geocoding data (20+ hours for 15 countries). These are one-time operations — data persists across restarts.
+
+### Quick Start
+
+1. Clone and configure:
 
 ```bash
 git clone https://github.com/GeiserX/propel.git
 cd propel
-docker compose -f docker/docker-compose.yml up -d
+cp .env.example .env
+# Edit .env — set DATABASE_URL and optionally PROPEL_DEFAULT_COUNTRY
+```
+
+2. Start the stack:
+
+```bash
+docker compose up -d
+```
+
+3. Wait for the first-time setup to complete:
+
+```bash
+# Watch Valhalla build routing tiles (~20 min)
+docker logs -f propel-valhalla
+
+# Watch Photon download geocoding data (~30 min)
+docker logs -f propel-photon
+```
+
+4. Seed station data:
+
+```bash
 npm install
 npx prisma generate
 npm run scraper:run -- --country=ES --once
-npm run dev
 ```
 
-Open http://localhost:3000
+5. Open http://localhost:3000
 
-## Self-Hosting
+### What Happens on First Start
+
+| Service | First start | Subsequent starts |
+|---|---|---|
+| **Valhalla** | Builds routing tiles from 15-country merged PBF (~20 GB). Uses 8 threads, peaks at ~15 GB RAM. Takes 3-6 hours. | Loads pre-built tiles instantly (~2 GB RAM) |
+| **Photon** | Downloads Photon 1.0.1 JAR (~92 MB) + 15 country geocoding dumps. Imports 200M+ documents (20+ hours). | Starts with existing index (~3 GB RAM) |
+| **PostGIS** | Creates database schema | Ready immediately |
+| **App** | Ready immediately | Ready immediately |
+
+### Docker Compose Services
+
+| Service | Image | Steady-state RAM | Internal Port |
+|---|---|---|---|
+| app | `drumsergio/propel` | 512 MB | 3000 (exposed as 3200) |
+| db | `postgis/postgis:17-3.4` | 2 GB | 5432 |
+| valhalla | `ghcr.io/gis-ops/docker-valhalla/valhalla:3.5.1` | 512 MB | 8002 |
+| photon | `eclipse-temurin:21-jre` + Photon 1.0.1 JAR | 1 GB | 2322 |
+
+### Disk Usage (15 countries)
+
+| Directory | Size | Contents |
+|---|---|---|
+| `valhalla/` | ~30 GB | 15-country merged PBF + routing tiles |
+| `photon/` | ~250 GB | Combined JSONL + OpenSearch index |
+| `pgdata/` | ~2 GB | PostGIS database (84K+ stations) |
+| **Total** | **~280 GB** | |
+
+### Configuration
+
+| Variable | Description | Default |
+|---|---|---|
+| `DATABASE_URL` | PostGIS connection string | Required |
+| `PROPEL_DEFAULT_COUNTRY` | ISO code for initial map view | `ES` |
+| `PROPEL_ENABLED_COUNTRIES` | Comma-separated ISO codes | All |
+| `PROPEL_DEFAULT_FUEL` | Override default fuel type | Per-country |
+| `PROPEL_CLUSTER_STATIONS` | Enable map marker clustering | `true` |
+| `PROPEL_CORRIDOR_KM` | Route corridor width in km (0.5–50) | `5` |
+| `VALHALLA_URL` | Valhalla routing endpoint | `http://propel-valhalla:8002` |
+| `PHOTON_URL` | Photon geocoding endpoint | `http://propel-photon:2322` |
+
+### Using a Different Country
+
+Valhalla and Photon can be configured for any country:
 
-See [docker/docker-compose.yml](docker/docker-compose.yml) for the full stack. Total requirements: ~6-10 GB RAM, ~80 GB disk for Europe.
+1. **Valhalla**: Change `tile_urls` to the country PBF from [Geofabrik](https://download.geofabrik.de/)
+2. **Photon**: Change `-country-codes es` to your country code in the docker-compose entrypoint
+3. **App**: Set `PROPEL_DEFAULT_COUNTRY` and `PROPEL_ENABLED_COUNTRIES`
 
 ## Data Sources
 
 | Country | Source | Stations | Update |
 |---|---|---|---|
-| Spain | MITECO | ~12,000 | Daily |
-| France | prix-carburants.gouv.fr | ~9,800 | 10 min |
-| Germany | Tankerkoenig (MTS-K) | ~14,000 | 4 min |
-| Italy | MIMIT | ~22,000 | Daily |
-| UK | CMA Open Data | ~8,000 | Varies |
-| Austria | E-Control | All | Real-time |
-| Portugal | DGEG | ~3,500 | Daily |
+| Italy | MIMIT | ~23,600 | Daily |
+| Germany | Tankerkoenig (MTS-K) | ~14,300 | Hourly |
+| Spain | MITECO | ~12,200 | Daily |
+| France | prix-carburants.gouv.fr | ~9,900 | Daily |
+| Netherlands | ANWB | ~3,900 | Daily |
+| UK | CMA Open Data | ~3,500 | Daily |
+| Portugal | DGEG | ~3,200 | Daily |
+| Belgium | ANWB | ~3,200 | Daily |
+| Greece | FuelGR | ~3,100 | Daily |
+| Austria | E-Control | ~2,700 | Real-time |
+| Romania | Peco Online | ~1,400 | Daily |
+| Ireland | Pick A Pump | ~1,300 | Daily |
+| Croatia | MZOE | ~900 | Daily |
+| Slovenia | goriva.si | ~550 | Daily |
+| Luxembourg | ANWB | ~240 | Daily |
 
 ## Tech Stack
 
-Next.js 15, React 19, MapLibre GL JS, Tailwind CSS, PostGIS, Valhalla, OpenFreeMap, Photon, next-intl.
+Next.js 15, React 19, MapLibre GL JS, Tailwind CSS, PostGIS 17, Valhalla 3.5.1, Photon 1.0.1, OpenFreeMap.
 
 ## Roadmap