Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danizd/urbanviable/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running UrbanViable on your own machine. By the end you will have the ETL pipeline producing a normalised GeoJSON for Galicia, an optional MBTiles file served by TileServer GL, and the React frontend live at http://localhost:5173.

​
Prerequisites

Make sure the following tools are installed before you begin:
  • Python 3.11+ with geopandas, pandas, shapely, and osmium available (install via pip install -r etl/requirements.txt)
  • Node.js 18+ (the frontend uses Vite 6 and React 18)
  • Docker (optional) — only needed if you want to run TileServer GL for the full vector-tile stack
  • Tippecanoe — only needed to regenerate the .mbtiles file from the processed GeoJSON
In development mode the frontend loads galicia_scouting.geojson directly from the frontend/public/ directory using a standard fetch() call. No tileserver is required to run the app locally. Docker and Tippecanoe are only needed when you want to reproduce the full production tile pipeline or run the two-container Docker stack.

​
Steps

1

Clone the repository and set up your environment

Clone the repository and copy the example environment file:
git clone https://github.com/danizd/urbanviable.git
cd urbanviable
cp .env.example .env
Open .env and review the values. The file contains the following variables:
VariableDefaultDescription
DOMAINtu-dominio.comProduction domain name
ENVIRONMENTproductionDeployment environment
CORS_ORIGINhttps://tu-dominio.comAllowed CORS origin for TileServer GL
REACT_APP_TILE_URLhttps://tu-dominio.com/tilesTile endpoint the frontend fetches from
REACT_APP_DATA_STATUS_URLhttps://tu-dominio.com/api/statusURL for the last_update.json data-status manifest
REACT_APP_LAYER_NAMEseccionesMapLibre layer name for census section polygons
REACT_APP_SOURCE_NAMEgalicia-scoutingTileServer GL tileset key
For local development REACT_APP_TILE_URL is overridden automatically by start.bat (set to /tiles) so the frontend proxies tile requests to the local TileServer GL container.
2

Run the ETL pipeline

The ETL script downloads raw data from CNIG, INE, OSM, and Catastro, reprojects and joins everything on the 10-digit CUSEC census key, applies Min-Max normalisation, and writes the result to disk.
python etl/process_data.py
Output: etl/data/processed/galicia_scouting.geojsonThis GeoJSON contains one feature per Galician census section (~3,800 features) with the following columns:
ColumnTypeDescription
cusecstring10-digit census section code
renta_normfloat [0,1]Normalised mean net household income
densidad_normfloat [0,1]Normalised population density
jovenes_normfloat [0,1]Normalised share of population under 20
mayores_normfloat [0,1]Normalised share of population over 64
actividad_normfloat [0,1]Normalised POI density (log-scaled)
uso_comercial_normfloat [0,1]Normalised commercial/industrial building ratio
antiguedad_normfloat [0,1]Normalised mean building age (newer = higher)
renta_absfloatRaw mean net household income (€)
poblacion_absintRaw population count
actividad_absintRaw POI count
The script also writes etl/data/processed/last_update.json with a timestamp and data-vintage metadata displayed by the frontend.
3

Generate vector tiles (optional — needed for Docker stack only)

If you want to run the full Docker production stack or test tile serving locally, convert the GeoJSON to an MBTiles file with Tippecanoe:
bash etl/generate_tiles.sh
Output: tiles_data/galicia_scouting.mbtilesThe script calls Tippecanoe with zoom levels 6–14 and packages all features into a single layer named secciones. The resulting file is typically 15–40 MB. TileServer GL will serve this file as .pbf tiles under /data/galicia-scouting/{z}/{x}/{y}.pbf.Copy the generated GeoJSON into frontend/public/ so the dev server can serve it directly:
copy etl\data\processed\galicia_scouting.geojson frontend\public\
4

Start the application

Choose between the lightweight frontend dev server (no Docker needed) or the full two-container Docker stack.
cd frontend
npm install
npm run start
The Vite dev server starts at http://localhost:5173. It loads galicia_scouting.geojson directly from frontend/public/ — no tileserver process required.

​
Option B — Full Docker stack (production-equivalent)

Make sure you have built the frontend first (npm run build inside frontend/) and that tiles_data/galicia_scouting.mbtiles exists. Then:
docker compose up -d
This starts two containers:
ServiceURLDescription
urbanviable-tileshttp://localhost:8080TileServer GL — serves .pbf vector tiles
urbanviable-webhttp://localhost:3002Nginx — serves the React production build and proxies /tiles/ to TileServer GL
Windows shortcut: Running start.bat from the repository root automates the full local-development stack in one command. It checks for Docker, npm, and Python; requires tiles_data/galicia_scouting.mbtiles to already exist (generate it with bash etl/generate_tiles.sh first); starts a TileServer GL Docker container (urbanviable-tiles-local) on port 8080; waits for it to be healthy; starts a lightweight Python HTTP server on port 8081 to serve last_update.json; and finally runs npm run start inside frontend/ to launch the Vite dev server at http://localhost:5173. It does not run the ETL pipeline — you must generate the MBTiles file separately before invoking start.bat.

​
What you should see

After completing the steps above:
  • Frontend dev server — open http://localhost:5173 in your browser. The map of Galicia loads with all census sections rendered in grey (all slider weights default to their initial values from variables.js). Move any slider to see the heatmap update in real time.
  • TileServer GL (Docker only) — http://localhost:8080/data/galicia-scouting.json returns the tileset metadata JSON, confirming the .mbtiles file is loaded correctly.
  • Click a census section — a tooltip appears showing the section code (CUSEC), mean income, and population. The sidebar reflects the weighted score for that section.

​
Next steps

Architecture

Understand the two-container Docker setup and the full data flow from ETL output to GPU-rendered heatmap.

ETL Overview

Deep dive into every transformation step, the normalisation logic, and how to update data sources.

Build docs developers (and LLMs) love

Get started for freeTalk to us