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/getting-started/) 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,126 @@
+---
+layout: default
+title: Getting Started
+---
+
+# Getting Started
+
+Apache Baremaps comes with a [default schema and style](https://github.com/apache/incubator-baremaps/tree/main/basemap) similar to [OpenStreetMap Carto](https://github.com/gravitystorm/openstreetmap-carto). This serves as a great starting point to get familiar with the project and build your own basemap.
+
+We chose the [Apache License](https://github.com/apache/incubator-baremaps/blob/main/LICENSE) so that map vendors can create derivative works without attributing the Apache Baremaps project on the map. The only requirement is to give proper credit to the contributors behind the data sources, such as [OpenStreetMap](https://www.openstreetmap.org/) and [Natural Earth](https://www.naturalearthdata.com/). Please note 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 continues to improve, contributions, enhancements, and feedback are highly encouraged.
+
+import Map from '@/components/map';
+
+<div style={{ marginTop: 20, height: 450 }}>
+  <Map />
+</div>
+
+## Installing PostGIS
+
+This step is not required if you only plan to execute the Geocoding or IP-to-location examples.
+
+To insert and generate vector tiles, you need to set up a [PostGIS](https://postgis.net/) database, which will host all the data required to generate the vector tiles.
+
+The following Docker command will help you quickly set up the PostGIS database:
+
+```bash
+docker run \
+  --name baremaps \
+  --publish 5432:5432 \
+  -e POSTGRES_DB=baremaps \
+  -e POSTGRES_USER=baremaps \
+  -e POSTGRES_PASSWORD=baremaps \
+  -d postgis/postgis:latest
+```
+
+For macOS users with an arm64 architecture, you may prefer the following optimized image:
+
+```
+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 stop and start the container using the following commands:
+
+```
+docker stop baremaps
+docker start baremaps
+```
+
+## Installing the CLI
+
+To run Apache Baremaps, you must first install Java 17 or a later version. [SDKMAN](https://sdkman.io/) offers a convenient Command Line Interface (CLI) to install and manage Java versions.
+
+Next, download and decompress the latest binary [binary distribution](https://dist.apache.org/repos/dist/release/incubator/baremaps/) of Apache Baremaps, or [build](https://baremaps.apache.org/documentation/developer-manual/how-to-build-with-maven/) the project from source.
+Afterward, 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
+```
+
+Running the `baremaps` command should now produce an output like this:
+
+```
+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).
+```
+
+## Preparing the Database
+
+To build the basemap locally, navigate to the `basemap` directory at the root of the project and execute the following command:
+
+```bash
+baremaps workflow execute --file=import.js
+```
+
+If you're using Docker, ensure that at least 20GB of storage is allocated to Docker. Depending on your machine and internet connection, this process may take up to 30 minutes.
+
+## Developing vector tiles
+
+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 tileset will be automatically detected, and the web page will refresh accordingly.
+
+## Serving vector tiles
+
+To serve the basemap in production mode, run the following command:
+
+```bash
+baremaps map serve --tileset tileset.js --style style.js
+```
+
+In production mode, the server does not watch for changes in the style or tileset. You can also pass additional parameters to customize the server's behavior. For example:
+
+- The `--cache` parameter specifies a Caffeine specification for the cache. For instance, `'maximumWeight=1073741824,expireAfterAccess=1h'` limits the cache to 1GB and expires entries after 1 hour.
+- The `--assets` parameter specifies the directory where static assets like fonts, images, or icons are stored.
+- And more.
+
+## Pregenerating vector tiles
+
+To avoid generating vector tiles on the fly, you can pregenerate them. Apache Baremaps supports several formats, including filesystem exports, MBTiles, and PMTiles. To pregenerate the tiles, run the following command:
+
+```bash
+baremaps map export --tileset tileset.js --repository tiles.pmtiles --format pmtiles
+```
+
+Note that this command uses the bounds and zoom levels defined in the tileset to generate the tiles.