Include content from SotM-EU presentation (#57)

shortbread-website/content/copyright/_index.md

@@ -1,13 +1,14 @@
 +++
 title = "Copyright & License"
+weight = 1
 +++
 
 # Copyright
 
-Geofabrik takes the position that this schema is not creative enough to be a copyrightable
+We take the position that this schema is not creative enough to be a copyrightable
 work.
 
-For the sake of clarity, however, we are releasing it under the [CC-0 license.](./CC0-1.0-LICENSE.txt)
+For the sake of clarity, however, we are releasing it under the [CC-0 license](CC0-1.0-LICENSE.txt).
 For the avoidance of doubt, using this schema to create your vector tiles will not add any attribution
 requirements, but if you generate vector tiles from OpenStreetMap data, you will of course have
 to attribute OpenStreetMap.

shortbread-website/content/customizing/_index.md

@@ -0,0 +1,67 @@
++++
+title = "Customizing Shortbread"
+description = "How to create and display customized shortbread vector tiles"
+weight = 6
++++
+
+## Use cases
+
+* **Custom styles**: Hiding features in a map or highlighting specific features can be done with a custom style.
+Since styles are applied in the browser, you can use existing Shortbread tiles. See [Rendering Styles](/styles/).
+
+* **Additional POIs**: If some POIs are missing or specific attributes for styling are not included, then you
+have to create custom Shortbread tiles or an additional tileset. 
+
+* **Route relations**: If you want to highlight route relations (e.g. bus lines) in your map, then you
+have to create custom Shortbread tiles or an additional tileset. 
+
+* **More tags for special objects**: If you want to create specialized maps requiring additional tags, then you
+have to create custom Shortbread tiles or an additional tileset. 
+
+* **Additional tags for streets or buildings**: If you want to create specialized maps requiring additional tags for streets or buildings, then you
+have to create custom Shortbread tiles. 
+
+* **Other / more languages**: Currently Shortbread tiles include `name`, `name_en` and `name_de`. It is a goal for Shortbread to
+add support for other languages. In the meantime you have to create custom Shortbread tiles, if you need more languages.
+
+
+## Customizing Shortbread
+
+### Creating custom Shortbread tiles
+
+See [Creating Shortbread Vector Tiles](/make-vectortiles/) for workflows and tutorials to create custom Shortbread tiles.
+
+The main options for custom configurations are:
+* tilemaker config (JSON, Lua)
+* Planetiler config (YAML, Java)
+* osm2pgsl config (Lua)
+
+### Basic rules
+
+* Keep tile size small
+* Don't break base map styles
+* Discuss core extensions in [shortbread-docs repo](https://github.com/shortbread-tiles/shortbread-docs)
+
+## Using Shortbread with additional tilesets
+
+### Tileset combinations
+
+There are pros and cons for creating custom base map tiles or creating additional tilesets:
+
+* Extended base map tiles
+  * No additional tiles
+  * Can break base map styles
+  * Selfhosting required
+* Additional tilesets
+  * Additional tile source in style
+  * No easy relation to base map tiles
+  * Potential duplication of data
+
+### Server-side combination
+
+Mapbox vector tiles allow concatenating tiles on server-side.
+
+There are some drawbacks though:
+* Requires a service
+* Not supported by all tile servers
+* Caching more difficult

shortbread-website/content/download/_index.md

@@ -1,8 +1,9 @@
 +++
 title = "Downloading Shortbread Tiles"
 description = "How & where to download shortbread vector tiles"
+weight = 5
 +++
 
 As well as [making shortbread vector tiles yourself](/make-vectortiles/), you can download tiles from these providers.
 
-- [Geofabrik Download Service](https://download.geofabrik.de/). For every region in the Geofabrik Download service, there are [experiental, non-updated shortbread tiles downloads](https://blog.geofabrik.de/?p=589) available.
+- [Geofabrik Download Service](https://download.geofabrik.de/). For every region in the Geofabrik Download service, there are [experimental, non-updated shortbread tiles downloads](https://blog.geofabrik.de/?p=589) available.

shortbread-website/content/make-vectortiles/_index.md

@@ -1,89 +1,36 @@
 +++
 title = "Creating Shortbread Vector Tiles"
 description = "This page describes how to generate the vector tiles in the Shortbread schema"
+weight = 4
 +++
 
-Shortbread Tiles can be created with [Tilemaker](https://tilemaker.org/).
+## Tile creation workflows
 
-Creating Shortbread vetor tiles is very simple. Install Tilemaker & the shortbread-tilemaker settings, get the OSM & external data, and run tilemaker!
+### PBF → Vector tiles
 
-## Software required
+{{< figure src="pbf-mvt.png" width="70%" >}}
 
-### Tilemaker
+Software:
+* tilemaker ([Tutorial](tilemaker/))
+* Planetiler ([Tutorial](planetiler/))
 
-- Follow the [Tilemaker installation instructions](https://github.com/systemed/tilemaker/blob/master/docs/INSTALL.md).
+### PBF → DB → Vector tiles
 
-### Extra software
+{{< figure src="pbf-db-mvt.png" width="70%" >}}
 
-You need [`ogr2ogr`](https://gdal.org/programs/ogr2ogr.html).
+Software PBF → PostGIS:
+* osm2pgsql ([Tutorial](osm2pgsql/))
 
-| OS            | command                     |
-| ------------- | --------------------------- |
-| Debian/Ubuntu | `sudo apt install gdal-bin` |
-| _(Other OS)_  | _(command)_                 |
+Software PostGIS → Vector tiles:
+* BBOX ([Tutorial](bbox/))
+* Tilekiln ([Tutorial](tilekiln/))
 
-## Get Shortbread-Tilemaker settings
+## Tile storage
 
-Clone the Git repository of the vector tile schema from Github:
+There are multiple options to store vector tiles:
 
-```sh
-git clone https://github.com/shortbread-tiles/shortbread-tilemaker
-```
-
-## Get Data
-
-### OpenStreetMap data
-
-Tilemaker needs raw OpenStreetMap data as input. You can download it from:
-
-- regional extracts from [Geofabrik Download Service](https://download.geofabrik.de)
-- latest weekly planet PBF file from [planet.openstreetmap.org](https://planet.openstreetmap.org/) or any of its [mirrors](https://wiki.openstreetmap.org/wiki/Planet.osm#Planet.osm_mirrors)
-- regional extracts from [download.openstreetmap.fr](https://download.openstreetmap.fr/extracts/)
-
-Please try with a small extract first before you try to load the complete planet file.
-
-### Additional data
-
-In the shortbread-tilemaker directory:
-
-    ./get-shapefiles.sh
-
-It will download a few required additional files into the `data` directory.
-
-## Generate Tiles
-
-In the shortbread-tilemaker directory, run this command:
-
-    tilemaker --config config.json --process process.lua --bbox -180,-90,180,90 \
-    	--input OSM_FILE.osm.pbf --output shortbread-tiles.mbtiles
-
-The generated data is the `shortbread-tiles.mbtiles` file.
-
-### Output format
-
-Tilemaker supports a few [output formats](https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md#standard-usage). Here [mbtiles](https://wiki.openstreetmap.org/wiki/MBTiles) is used.
-
-#### BBox PBF files
-
-If the `.osm.pbf` file contains a bounding box entry in its header (this is not
-true for the planet), you can omit the `--bbox -180,-90,180,90` part of the
-tilemaker command. The generation process will be much faster for smaller
-areas, and the output data will contain less “ocean tiles”, [[and be a little
-bit smaller]]??
-
-The error message `Can't read shapefiles unless a bounding box is provided.`
-means you need to specify the `--bbox` option.
-
-#### Memory
-
-The above command uses the tilemaker default of storing things in memory. If you are running out of memory, you need the `--store` option, e.g. `--store tilemaker.store.d/`.
-
-Read more in the [tilemaker documentation about on-disk storage](https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md#using-on-disk-storage)
-
-## Statistics
-
-In February 2022, a server with a AMD EPYC 7452 32-Core Processor (2.35–3.35 GHz), 512 GB RAM,
-cache on NVMe and output to a loop-mounted hard disk drive (RAID 1) took 16:15 hours and needed up
-to 358 GB RAM to generate the whole planet.
-
-## Troubleshooting
+* Files / S3
+* [MBTiles](https://github.com/mapbox/mbtiles-spec) (requires tile service for serving)
+* [PMTiles](https://docs.protomaps.com/pmtiles/)
+* DB cache (requires tile service for serving)
+* No storage - live generated tiles

shortbread-website/content/make-vectortiles/bbox.md

@@ -0,0 +1,57 @@
++++
+title = "Using BBOX"
+description = "Generating vector tiles with BBOX"
+weight = 4
++++
+
+Shortbread Tiles can be created with [BBOX](https://www.bbox.earth/).
+
+## BBOX overview
+
+* Generate and serve vector tiles
+* Formats: PostGIS, MBTiles, PMTiles, S3
+* Successor of t-rex tile server
+
+### Serve shortbread tiles from PostGIS
+
+When importing OSM data into PostGIS with [osm2pgsql](/make-vectortiles/osm2pgsql/):
+* Set `local BBOX = true` in `osm2pgsql-themepark/config/shortbread_gen.lua`
+* Change `write_config('bbox-config.toml')` to `write_config('/data/bbox-config.toml')`
+  when running with Docker
+* Run `osm2pgsql`
+
+Run BBOX tile server:
+```bash
+BBOX_DATASOURCE_DB=postgres://osm:[email protected]/osm bbox-tile-server -c data/bbox-config.toml serve
+```
+
+Tiles are served on <http://localhost:8080/xyz/osm.style.json>
+
+Serve with style:
+```bash
+mkdir styles
+curl -L https://github.com/versatiles-org/versatiles-style/releases/latest/download/styles.tar.gz \
+  | tar xz -C styles colorful.json
+sed 's!https://tiles.versatiles.org/tiles/osm/{z}/{x}/{y}!http://localhost:8080/xyz/osm/{z}/{x}/{y}.pbf!g' styles/colorful.json > styles/colorful-local.json
+
+BBOX_DATASOURCE_DB=postgres://osm:[email protected]/osm BBOX_ASSETS__STATIC='[{dir="../styles",path="/styles"}]' bbox-tile-server -c data/bbox-config.toml serve
+```
+
+### Serve PMTiles or MBTiles with style
+
+```bash
+mkdir styles
+curl -L https://github.com/versatiles-org/versatiles-style/releases/latest/download/styles.tar.gz \
+  | tar xz -C styles colorful.json
+sed 's!https://tiles.versatiles.org/tiles/osm/{z}/{x}/{y}!http://localhost:8080/xyz/shortbread/{z}/{x}/{y}.pbf!g' \
+ styles/colorful.json > styles/colorful-local.json
+
+# Serve MBTiles
+BBOX_ASSETS__STATIC='[{dir="styles",path="/styles"}]' bbox-tile-server serve data/shortbread.mbtiles
+
+# Serve PMTiles
+BBOX_ASSETS__STATIC='[{dir="styles",path="/styles"}]' bbox-tile-server serve data/shortbread.pmtiles
+
+# Open in Maputnik
+xdg-open "https://maplibre.org/maputnik/?style=http://localhost:8080/styles/colorful-local.json#15/47.1377/9.5188"
+```

shortbread-website/content/make-vectortiles/osm2pgsql.md

@@ -0,0 +1,59 @@
++++
+title = "Using osm2pgsql"
+description = "Importing OSM data into PostGIS with osm2pgsql"
+weight = 3
++++
+
+[osm2pgsql](https://osm2pgsql.org/) can be used to import and update OSM data in a PostGIS database using the Shortbread schema.
+
+## osm2pgsql overview
+
+* Flex mode: configuration with Lua scripts
+* Osm2pgsql [Themepark](https://osm2pgsql.org/themepark/) with Shortbread config
+* `osm2pgsql-gen` for generalization in database
+* `osm2pgsql-replication` for incremental updates
+* Config generation for tile servers
+
+### Quickstart (Docker)
+
+```bash
+git clone https://github.com/osm2pgsql-dev/osm2pgsql-themepark.git
+
+# Start database
+docker run -d --name postgis -p 127.0.0.1:5432:5432 \
+  -e POSTGRES_DB=osm -e POSTGRES_USER=osm -e POSTGRES_PASSWORD=osm postgis/postgis
+
+# Download OSM extract
+mkdir data
+curl -sSfO --output-dir data https://download.geofabrik.de/europe/liechtenstein-latest.osm.pbf
+
+# Import OSM extract
+docker run --rm --network=host -v $PWD/osm2pgsql-themepark:/osm2pgsql-themepark:ro -v $PWD/data:/data \
+  -e LUA_PATH="/osm2pgsql-themepark/lua/?.lua;;" \
+  -e PGHOST=127.0.0.1 -e PGUSER=osm -e PGPASSWORD=osm iboates/osm2pgsql:1.11.0 \
+  osm2pgsql -d osm -S /osm2pgsql-themepark/config/shortbread_gen.lua -O flex --slim \
+            /data/liechtenstein-latest.osm.pbf
+```
+
+### osm2pgsql generalization
+
+```bash
+# Download and import additional data (water polygons, etc.). Requires ogr2ogr!
+PGHOST=127.0.0.1 PGUSER=osm PGPASSWORD=osm ./osm2pgsql-themepark/themes/external/download-and-import.sh \
+  data osm oceans ocean
+
+# Generalize
+docker run --rm --network=host -v $PWD/osm2pgsql-themepark:/osm2pgsql-themepark:ro \
+  -e LUA_PATH="/osm2pgsql-themepark/lua/?.lua;;" \
+  -e PGHOST=127.0.0.1 -e PGUSER=osm -e PGPASSWORD=osm iboates/osm2pgsql:1.11.0 \
+   osm2pgsql-gen -d osm -S /osm2pgsql-themepark/config/shortbread_gen.lua
+```
+
+### osm2pgsql updates
+
+```bash
+docker run --rm --network=host -v $PWD/osm2pgsql-themepark:/osm2pgsql-themepark:ro \
+  -e LUA_PATH="/osm2pgsql-themepark/lua/?.lua;;" \
+  -e PGHOST=127.0.0.1 -e PGUSER=osm -e PGPASSWORD=osm iboates/osm2pgsql:1.11.0 \
+  osm2pgsql-replication update -d osm
+```

shortbread-website/content/make-vectortiles/planetiler.md

@@ -0,0 +1,22 @@
++++
+title = "Using Planetiler"
+description = "Generating vector tiles with Planetiler"
+weight = 2
++++
+
+Shortbread Tiles can be created with [Planetiler](https://github.com/onthegomap/planetiler).
+
+## Planetiler overview
+
+* Configs for OpenMapTiles and Shortbread schema
+* YAML configuration or Java application
+* Output formats: MBTiles, PMTiles
+* No diff support
+* Extremely fast!
+
+### Quickstart (Docker)
+
+```bash
+docker run --rm --user=$UID -v $PWD/data:/data ghcr.io/onthegomap/planetiler shortbread.yml \
+  --download --area=liechtenstein --output=/data/shortbread.pmtiles
+```

shortbread-website/content/make-vectortiles/tilekiln.md

@@ -0,0 +1,17 @@
++++
+title = "Using Tilekiln"
+description = "Generating vector tiles with Tilekiln"
+weight = 5
++++
+
+Shortbread Tiles can be created with [Tilekiln](https://github.com/pnorman/tilekiln).
+
+## Tilekiln overview
+
+* Generate and serve vector tiles
+* Data source: PostGIS
+* Caching tiles in PostgreSQL
+
+## Usage
+
+* [Tilekiln Quickstart](https://github.com/pnorman/spirit/blob/main/INSTALL.md)