Improve the structure of the documentation

src/pages/documentation/_meta.json

@@ -1,7 +1,6 @@
 {
   "index": "Introduction",
-  "basemap": "Basemap",
   "getting-started": "Getting started",
-  "examples": "Examples",
+  "additional-examples": "Additional examples",
   "developer-manual": "Developer manual"
 }

src/pages/documentation/additional-examples.mdx

@@ -0,0 +1,34 @@
+---
+layout: default
+title: Examples
+---
+
+# Examples
+
+The examples will showcase the different uses of the Apache Baremaps toolkits. To run the examples you need to clone or [download](https://github.com/apache/incubator-baremaps/archive/refs/heads/main.zip) the main
+repository in order to have access to the [files](https://github.com/apache/incubator-baremaps/blob/main/additional-examples/) that have been prepared for the examples.
+
+```bash
+git clone [email protected]:apache/incubator-baremaps.git
+```
+
+You should have completed the [Installation Guide](/documentation/getting-started/installing-the-cli/) before running the examples.
+
+For the creation of custom vector tiles you can follow these guides:
+
+- The [OpenStreetMap](/documentation/additional-examples/import-osm-into-postgis/) example shows how to import OpenStreetMap data into postgis and create minimalistic vector tiles (see the [basemap](https://baremaps.apache.org/documentation/basemap/) for a more detailed shema and style).
+- The [NaturalEarth](/documentation/additional-examples/import-naturalearth-into-postgis/) example shows how to produce low resolution vector tiles.
+- The [Contour](/documentation/additional-examples/contour-lines-in-vector-tiles/) example shows how to produce contour lines from a digital elevation model.
+- The [Extrusion](/documentation/additional-examples/extrusion/) example shows how to import OpenStreetMap data into postgis and use the MVT specification to extrude the vectors into 3d.
+
+For the creation of an IP to location service follow this guide:
+
+- The [IP to location](/documentation/additional-examples/ip-to-location/) example shows how to create and serve an IP to location service in a simple web application.
+
+If you want to work on Geocoding there is this example:
+
+- The [Geocoding](/documentation/additional-examples/geocoding/) example shows how to create and serve a geocoding service in a simple web application.
+
+Developers who want to execute the code, should refer to the developer manual:
+
+- The [Developer Manual](/documentation/developer-manual/) aims at helping developers to execute the code, understand the structure and contribute to the project.

src/pages/documentation/examples/extrusion.mdx → src/pages/documentation/additional-examples/extrusion.mdx

@@ -5,7 +5,7 @@ title: Extrusion of vector tiles from OSM data
 
 # Extrusion of vector tiles from OSM data
 
-This example builds upon the [OpenStreetMap example](/documentation/examples/import-osm-into-postgis/) and shows how 3d
+This example builds upon the [OpenStreetMap example](/documentation/additional-examples/import-osm-into-postgis/) and shows how 3d
 buildings can be extruded with Maplibre. First, start by downloading the OSM data for London in the current directory.
 
 To import London data in the database.
@@ -15,7 +15,7 @@ cd examples/extrusion
 baremaps workflow execute --file workflow.json
 ```
 
-In the [tileset.json](https://raw.githubusercontent.com/apache/incubator-baremaps/main/examples/extrusion/tileset.json)
+In the [tileset.json](https://raw.githubusercontent.com/apache/incubator-baremaps/main/additional-examples/extrusion/tileset.json)
 file, notice the SQL query associated with the building layer. Here, the number of levels stored in OSM is multiplied by
 3, which roughly corresponds to the height of a level in meters.
 
@@ -31,7 +31,7 @@ WHERE tags ? 'building'
 ```
 
 This property is then used in
-the [style.json](https://raw.githubusercontent.com/apache/incubator-baremaps/main/examples/extrusion/style.json) file to
+the [style.json](https://raw.githubusercontent.com/apache/incubator-baremaps/main/additional-examples/extrusion/style.json) file to
 extrude the buildings.
 
 ```json

src/pages/documentation/examples/geocoding.mdx → src/pages/documentation/additional-examples/geocoding.mdx

@@ -13,7 +13,7 @@ The data we will be using comes from [Geonames](https://www.geonames.org).
 
 ## Generate the index
 
-The following [workflow](https://raw.githubusercontent.com/apache/incubator-baremaps/main/examples/geocoding/workflow.js) will download the Geonames data, decompress it, and finally build the index.
+The following [workflow](https://raw.githubusercontent.com/apache/incubator-baremaps/main/additional-examples/geocoding/workflow.js) will download the Geonames data, decompress it, and finally build the index.
 
 ```bash
 cd examples/geocoding

src/pages/documentation/examples/import-naturalearth-into-postgis.mdx → src/pages/documentation/additional-examples/import-naturalearth-into-postgis.mdx

@@ -24,5 +24,5 @@ baremaps workflow execute --file workflow.json
 
 In this tutorial, we learnt how to import Natural Earth data in PostGIS.
 
-Now that you have inserted the data into the PostGIS database, you can use follow the [Serve Vector Tiles from PostGIS](/documentation/examples/serve-and-export-vector-tiles/) example to serve
+Now that you have inserted the data into the PostGIS database, you can use follow the [Serve Vector Tiles from PostGIS](/documentation/additional-examples/serve-and-export-vector-tiles/) example to serve
 your PostGIS data directly as Vector Tiles in a web application with live reload capabilities.

src/pages/documentation/examples/import-osm-into-postgis.mdx → src/pages/documentation/additional-examples/import-osm-into-postgis.mdx

@@ -22,7 +22,7 @@ In this example we will use a tiny extract of OpenStreetMap for [Liechtenstein](
 ## Importing OpenStreetMap Data
 
 A workflow is a directed acyclic graph of steps executed by Baremaps.
-To download and import the sample OpenStreetMap data in Postgres, execute the following [workflow](https://raw.githubusercontent.com/apache/incubator-baremaps/main/examples/openstreetmap/workflow.json).
+To download and import the sample OpenStreetMap data in Postgres, execute the following [workflow](https://raw.githubusercontent.com/apache/incubator-baremaps/main/additional-examples/openstreetmap/workflow.json).
 
 ```bash
 cd examples/openstreetmap
@@ -76,5 +76,5 @@ The following Figure displays the schema of the PostGIS database created by Bare
 
 In this tutorial, we learnt how to import OpenStreetMap data in PostGIS.
 
-Now that you have inserted the OpenStreetMap data into the PostGIS database, you can use follow the [Serve Vector Tiles from PostGIS](/documentation/examples/serve-and-export-vector-tiles/) example to serve
+Now that you have inserted the OpenStreetMap data into the PostGIS database, you can use follow the [Serve Vector Tiles from PostGIS](/documentation/additional-examples/serve-and-export-vector-tiles/) example to serve
 your PostGIS data directly as Vector Tiles in a web application with live reload capabilities.

src/pages/documentation/examples/ip-to-location.mdx → src/pages/documentation/additional-examples/ip-to-location.mdx

@@ -23,7 +23,7 @@ baremaps workflow execute --file workflow.js
 The workflow executed in the above command does the following:
 
 - Download and decompress the data from the IRRs
-- Download and create a Geocoding index (see the [Geocoding](/documentation/examples/geocoding/) example)
+- Download and create a Geocoding index (see the [Geocoding](/documentation/additional-examples/geocoding/) example)
 - Iterate over every entry in the registries to extract the IP address ranges and the associated metadata to query the Geocoding index and extract a latitude and a longitude.
 
 ## Serve the data

src/pages/documentation/examples/serve-and-export-vector-tiles.mdx → src/pages/documentation/additional-examples/serve-and-export-vector-tiles.mdx

@@ -9,9 +9,9 @@ In this tutorial, we'll learn how to create vector tiles from the data imported
 
 If you have not yet inserted data into your PostGIS database, please follow one of these three guides:
 
-- [Import OpenStreetMap data into PostGIS](/documentation/examples/import-osm-into-postgis/)
-- [Import Natural Earth data into PostGIS](/documentation/examples/import-naturalearth-into-postgis/)
-- [Import Contour lines from the ASTER dataset into PostGIS](/documentation/examples/contour-lines-in-vector-tiles/)
+- [Import OpenStreetMap data into PostGIS](/documentation/additional-examples/import-osm-into-postgis/)
+- [Import Natural Earth data into PostGIS](/documentation/additional-examples/import-naturalearth-into-postgis/)
+- [Import Contour lines from the ASTER dataset into PostGIS](/documentation/additional-examples/contour-lines-in-vector-tiles/)
 
 If you are in a hurry, consider skipping the "Under the Hood" sections.
 
@@ -26,9 +26,9 @@ For convenience, we have prepared a `tileset.json` and a `style.json` that corre
 
 Each of these files are available in the main repository of Apache Baremaps inside the examples' folder.
 
-- [For OpenStreetMap data](https://github.com/apache/incubator-baremaps/blob/main/examples/openstreetmap/)
-- [For contour lines data](https://github.com/apache/incubator-baremaps/blob/main/examples/contour/)
-- [For Natural Earth data](https://github.com/apache/incubator-baremaps/blob/main/examples/naturalearth/)
+- [For OpenStreetMap data](https://github.com/apache/incubator-baremaps/blob/main/additional-examples/openstreetmap/)
+- [For contour lines data](https://github.com/apache/incubator-baremaps/blob/main/additional-examples/contour/)
+- [For Natural Earth data](https://github.com/apache/incubator-baremaps/blob/main/additional-examples/naturalearth/)
 
 First `cd` into one of the example directories that corresponds to the data you inserted inside your PostGIS database.
 Then let's preview and edit the map with the sample configuration files by executing the following command in a terminal.

src/pages/documentation/developer-manual/how-to-build-with-maven.mdx

@@ -51,8 +51,8 @@ Commands:
 
 From here, head into [Installing PostGIS](/documentation/getting-started/installing-postgis/) if you plan to work with vector tiles.
 
-If you want to work on [Geocoding](/documentation/examples/geocoding/) or
-[IP to location](/documentation/examples/ip-to-location/), head directly into the related examples.
+If you want to work on [Geocoding](/documentation/additional-examples/geocoding/) or
+[IP to location](/documentation/additional-examples/ip-to-location/), head directly into the related examples.
 
 ### Windows
 

src/pages/documentation/developer-manual/ip-to-location.mdx

@@ -37,7 +37,7 @@ The structure of the RIPE database should be applicable to all the RIRs.
 
 ## Generating the IP to location database
 
-A workflow is a directed acyclic graph of steps executed by Baremaps. To download and import the sample OSM data in Postgres, execute the following [workflow](https://raw.githubusercontent.com/apache/incubator-baremaps/main/examples/ip-to-location/workflow.js).
+A workflow is a directed acyclic graph of steps executed by Baremaps. To download and import the sample OSM data in Postgres, execute the following [workflow](https://raw.githubusercontent.com/apache/incubator-baremaps/main/additional-examples/ip-to-location/workflow.js).
 
 ```bash
 baremaps workflow execute --file examples/ip-to-location/workflow.js

src/pages/documentation/getting-started.mdx

@@ -0,0 +1,139 @@
+---
+layout: default
+title: Getting Started
+---
+
+# Getting started
+
+Apache Baremaps comes with a [default schema and style](https://baremaps.apache.org/documentation/basemap/) similar to [OpenStreetMap Carto](https://github.com/gravitystorm/openstreetmap-carto).
+This is a great starting point to get familiar with the project and to build your own basemap.
+
+We chose the [Apache License](https://github.com/apache/incubator-baremaps/blob/main/LICENSE) so that map vendors can create derived work without attributing the Apache Baremaps project on the map.
+The only requirement is to give proper credit to the wonderful contributors behind the data sources, such as [OpenStreetMap](https://www.openstreetmap.org/) or [Natural Earth](https://www.naturalearthdata.com/).
+Notice that this schema and style are now used by default to display vector maps on the [OpenStreetMap wiki](https://wiki.openstreetmap.org/wiki/Template:Vector_map).
+
+While the quality of the schema and style keeps improving, contributions, improvements, and feedback are welcome and encouraged.
+
+import Map from '@/components/map';
+
+<div style={{ marginTop: 20, height: 450 }}>
+  <Map />
+</div>
+
+## Installing PostGIS
+
+This step is not required if you plan to execute the Geocoding or IP to location examples.
+
+For the insertion and generation of Vector tiles, you need to set up a [PostGIS](https://postgis.net/) database.
+This database will host all the data required to generate the vector tiles.
+
+The following docker image will allow you to jump start this installation:
+
+```
+docker run \
+  --name baremaps \
+  --publish 5432:5432 \
+  -e POSTGRES_DB=baremaps \
+  -e POSTGRES_USER=baremaps \
+  -e POSTGRES_PASSWORD=baremaps \
+  -d postgis/postgis:latest
+```
+
+On a mac, you may prefer an image optimized for arm64:
+
+```
+docker run \
+  --name baremaps \
+  --publish 5432:5432 \
+  -e POSTGRES_DB=baremaps \
+  -e POSTGRES_USER=baremaps \
+  -e POSTGRES_PASSWORD=baremaps \
+  -d kartoza/postgis:16-3.4
+```
+
+You can then stop and start the container with the following commands:
+
+```
+docker stop baremaps
+docker start baremaps
+```
+
+## Installing the CLI
+
+In order to run Apache Baremaps, you first need to install Java 17 or a later version.
+[SDKMAN](https://sdkman.io/) provides a convenient Command Line Interface (CLI) to install and upgrade Java.
+
+To install Apache Baremaps, download and decompress the latest [binary distribution](https://dist.apache.org/repos/dist/release/incubator/baremaps/).
+Then, add the `/bin` directory of the decompressed distribution to your `PATH` environment variable:
+
+```
+tar -xzf baremaps-<version>-incubating-bin.tar.gz
+export PATH=$PATH:`pwd`/baremaps/bin
+```
+
+Calling the `baremaps` command should now result in an output similar to the following:
+
+```
+Usage: baremaps [-V] [COMMAND]
+A toolkit for producing vector tiles.
+  -V, --version   Print version info.
+Commands:
+  workflow  Manage a workflow.
+  database  Database commands.
+  map       Map commands.
+  geocoder  Geocoder commands (experimental).
+  iploc     IP to location commands (experimental).
+  ogcapi    OGC API server (experimental).
+```
+
+From here, heads to [Installing PostGIS](/documentation/getting-started/installing-postgis/) if you plan to work with vector tiles.
+
+If you want to work on [Geocoding](/documentation/additional-examples/geocoding/) or [IP to location](/documentation/additional-examples/ip-to-location/), head directly into the related examples.
+
+## Preparing the database
+
+In order to build the basemap locally, move to the `basemap` directory at root of the project and execute the following command:
+
+```bash
+baremaps workflow execute --file=import.js
+```
+
+If you are using Docker, you need to increase the storage allocated to Docker to at least 20GB.
+Depending on your machine and internet connection, the process can take up to 30 minutes.
+
+## Serving vector tiles (development mode)
+
+To start the server in development mode, run the following command:
+
+```bash
+baremaps map dev --tileset tileset.js --style style.js
+```
+
+In this mode, any changes to the style or the tileset will be automatically detected and the web page will be refreshed.
+
+## Serving vector tiles (production mode)
+
+To serve the basemap in production mode, run the following command:
+
+```bash
+baremaps map serve --tileset tileset.js --style style.js
+```
+
+In this mode, the server will not watch for changes in the style or the tileset
+and additional parameters can be passed to customize the behavior of the server.
+For instance:
+
+- The `cache` parameter specifies a [caffeine specification](https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/2.2.2/com/github/benmanes/caffeine/cache/CaffeineSpec.html) for the cache. For instance, `'maximumWeight=1073741824,expireAfterAccess=1h'` will limit the cache to 1GB and will expire the entries after 1 hour.
+- The `--assets` parameter specifies the directory where static assets, such as fonts, images, or icons, are stored.
+- Etc.
+
+## Pregenerating vector tiles
+
+It is often useful to pregenerate the vector tiles to avoid the overhead of generating them on the fly. Several formats are supported by baremaps,
+including simple export to the filesystem, MBTiles, and PMTiles, and more. To pregenerate the vector tiles, run the following command:
+
+```bash
+baremaps map export --tileset tileset.js --repository tiles.pmtiles --format pmtiles
+```
+
+It is important to note that this command will use the bounds and zoom levels defined in the tileset to generate the tiles.