This is an automated email from the ASF dual-hosted git repository.
bchapuis pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-baremaps-site.git
The following commit(s) were added to refs/heads/main by this push:
new 6d2f1b9 Improve the structure of the documentation
6d2f1b9 is described below
commit 6d2f1b99aa3384d81d0c81c9f46aaec845c18bc1
Author: Bertil Chapuis <[email protected]>
AuthorDate: Wed Oct 16 23:03:30 2024 +0200
Improve the structure of the documentation
---
src/pages/documentation/_meta.json | 3 +-
src/pages/documentation/additional-examples.mdx | 34 +++++
.../{examples => additional-examples}/_meta.json | 0
.../_serving-vector-tiles.txt | 0
.../contour-lines-in-vector-tiles.mdx | 0
.../extrusion.mdx | 6 +-
.../gdal-macos.mdx | 0
.../{examples => additional-examples}/geoadmin.mdx | 0
.../geocoding.mdx | 2 +-
.../import-naturalearth-into-postgis.mdx | 2 +-
.../import-osm-into-postgis.mdx | 4 +-
.../ip-to-location.mdx | 2 +-
.../serve-and-export-vector-tiles.mdx | 12 +-
src/pages/documentation/basemap.mdx | 27 ----
.../developer-manual/how-to-build-with-maven.mdx | 4 +-
.../developer-manual/ip-to-location.mdx | 2 +-
src/pages/documentation/examples.mdx | 34 -----
src/pages/documentation/getting-started.md | 14 ---
src/pages/documentation/getting-started.mdx | 139 +++++++++++++++++++++
src/pages/documentation/getting-started/_meta.json | 4 -
.../getting-started/installing-postgis.mdx | 44 -------
.../getting-started/installing-the-cli.mdx | 36 ------
src/pages/index.mdx | 2 +-
23 files changed, 192 insertions(+), 179 deletions(-)
diff --git a/src/pages/documentation/_meta.json
b/src/pages/documentation/_meta.json
index 646004b..9ab92df 100644
--- a/src/pages/documentation/_meta.json
+++ b/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"
}
diff --git a/src/pages/documentation/additional-examples.mdx
b/src/pages/documentation/additional-examples.mdx
new file mode 100644
index 0000000..ebb29c7
--- /dev/null
+++ b/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.
diff --git a/src/pages/documentation/examples/_meta.json
b/src/pages/documentation/additional-examples/_meta.json
similarity index 100%
rename from src/pages/documentation/examples/_meta.json
rename to src/pages/documentation/additional-examples/_meta.json
diff --git a/src/pages/documentation/examples/_serving-vector-tiles.txt
b/src/pages/documentation/additional-examples/_serving-vector-tiles.txt
similarity index 100%
rename from src/pages/documentation/examples/_serving-vector-tiles.txt
rename to src/pages/documentation/additional-examples/_serving-vector-tiles.txt
diff --git a/src/pages/documentation/examples/contour-lines-in-vector-tiles.mdx
b/src/pages/documentation/additional-examples/contour-lines-in-vector-tiles.mdx
similarity index 100%
rename from src/pages/documentation/examples/contour-lines-in-vector-tiles.mdx
rename to
src/pages/documentation/additional-examples/contour-lines-in-vector-tiles.mdx
diff --git a/src/pages/documentation/examples/extrusion.mdx
b/src/pages/documentation/additional-examples/extrusion.mdx
similarity index 91%
rename from src/pages/documentation/examples/extrusion.mdx
rename to src/pages/documentation/additional-examples/extrusion.mdx
index fba0fa9..9a76748 100644
--- a/src/pages/documentation/examples/extrusion.mdx
+++ b/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
diff --git a/src/pages/documentation/examples/gdal-macos.mdx
b/src/pages/documentation/additional-examples/gdal-macos.mdx
similarity index 100%
rename from src/pages/documentation/examples/gdal-macos.mdx
rename to src/pages/documentation/additional-examples/gdal-macos.mdx
diff --git a/src/pages/documentation/examples/geoadmin.mdx
b/src/pages/documentation/additional-examples/geoadmin.mdx
similarity index 100%
rename from src/pages/documentation/examples/geoadmin.mdx
rename to src/pages/documentation/additional-examples/geoadmin.mdx
diff --git a/src/pages/documentation/examples/geocoding.mdx
b/src/pages/documentation/additional-examples/geocoding.mdx
similarity index 86%
rename from src/pages/documentation/examples/geocoding.mdx
rename to src/pages/documentation/additional-examples/geocoding.mdx
index 07b3e04..c06ce30 100644
--- a/src/pages/documentation/examples/geocoding.mdx
+++ b/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
diff --git
a/src/pages/documentation/examples/import-naturalearth-into-postgis.mdx
b/src/pages/documentation/additional-examples/import-naturalearth-into-postgis.mdx
similarity index 92%
rename from
src/pages/documentation/examples/import-naturalearth-into-postgis.mdx
rename to
src/pages/documentation/additional-examples/import-naturalearth-into-postgis.mdx
index 667cfac..d7cf7d7 100644
--- a/src/pages/documentation/examples/import-naturalearth-into-postgis.mdx
+++
b/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.
diff --git a/src/pages/documentation/examples/import-osm-into-postgis.mdx
b/src/pages/documentation/additional-examples/import-osm-into-postgis.mdx
similarity index 96%
rename from src/pages/documentation/examples/import-osm-into-postgis.mdx
rename to
src/pages/documentation/additional-examples/import-osm-into-postgis.mdx
index 9868267..6551a82 100644
--- a/src/pages/documentation/examples/import-osm-into-postgis.mdx
+++ b/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.
diff --git a/src/pages/documentation/examples/ip-to-location.mdx
b/src/pages/documentation/additional-examples/ip-to-location.mdx
similarity index 96%
rename from src/pages/documentation/examples/ip-to-location.mdx
rename to src/pages/documentation/additional-examples/ip-to-location.mdx
index 592d50f..4d21928 100644
--- a/src/pages/documentation/examples/ip-to-location.mdx
+++ b/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
diff --git a/src/pages/documentation/examples/serve-and-export-vector-tiles.mdx
b/src/pages/documentation/additional-examples/serve-and-export-vector-tiles.mdx
similarity index 89%
rename from src/pages/documentation/examples/serve-and-export-vector-tiles.mdx
rename to
src/pages/documentation/additional-examples/serve-and-export-vector-tiles.mdx
index a03fa0a..d6a79f5 100644
--- a/src/pages/documentation/examples/serve-and-export-vector-tiles.mdx
+++
b/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.
diff --git a/src/pages/documentation/basemap.mdx
b/src/pages/documentation/basemap.mdx
deleted file mode 100644
index 6c8ba57..0000000
--- a/src/pages/documentation/basemap.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
-# Basemap
-
-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).
-
-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>
-
-## Build the basemap
-
-In order to build the basemap locally, move to the `/basemap` directory and
run the following workflow:
-
-```bash
-baremaps workflow execute --file=import.js
-```
-
-> Note: 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.
diff --git
a/src/pages/documentation/developer-manual/how-to-build-with-maven.mdx
b/src/pages/documentation/developer-manual/how-to-build-with-maven.mdx
index 21ddc69..e7092bf 100644
--- a/src/pages/documentation/developer-manual/how-to-build-with-maven.mdx
+++ b/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
diff --git a/src/pages/documentation/developer-manual/ip-to-location.mdx
b/src/pages/documentation/developer-manual/ip-to-location.mdx
index 85ae04d..ef13dff 100644
--- a/src/pages/documentation/developer-manual/ip-to-location.mdx
+++ b/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
diff --git a/src/pages/documentation/examples.mdx
b/src/pages/documentation/examples.mdx
deleted file mode 100644
index 81c4837..0000000
--- a/src/pages/documentation/examples.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
----
-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/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/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/examples/import-naturalearth-into-postgis/)
example shows how to produce low resolution vector tiles.
-- The [Contour](/documentation/examples/contour-lines-in-vector-tiles/)
example shows how to produce contour lines from a digital elevation model.
-- The [Extrusion](/documentation/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/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/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.
diff --git a/src/pages/documentation/getting-started.md
b/src/pages/documentation/getting-started.md
deleted file mode 100644
index 4438ea0..0000000
--- a/src/pages/documentation/getting-started.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-layout: default
-title: Getting Started
----
-
-# Getting Started
-
-This section will get you started with the setup of Apache Baremaps to execute
the examples. If you plan on running the
-code directly, or using Apache Baremaps as a library, you should refer to the
[Developer Manual](/documentation/developer-manual/).
-
-After installing the necessary components, the
[Examples](/documentation/examples/) explain how to use Apache Baremaps to
create a vector tileset from an OpenStreetMap extract, create an IP to location
web service, and much more.
-
-Now head into [Installing the
CLI](/documentation/getting-started/installing-the-cli/) to see how to set up
the Apache Baremaps command line interface on your
-own machine to execute the examples.
diff --git a/src/pages/documentation/getting-started.mdx
b/src/pages/documentation/getting-started.mdx
new file mode 100644
index 0000000..7944b82
--- /dev/null
+++ b/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.
diff --git a/src/pages/documentation/getting-started/_meta.json
b/src/pages/documentation/getting-started/_meta.json
deleted file mode 100644
index 5788dec..0000000
--- a/src/pages/documentation/getting-started/_meta.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "installing-the-cli": "Installing the CLI",
- "installing-postgis": "Installing PostGIS"
-}
diff --git a/src/pages/documentation/getting-started/installing-postgis.mdx
b/src/pages/documentation/getting-started/installing-postgis.mdx
deleted file mode 100644
index f64dd93..0000000
--- a/src/pages/documentation/getting-started/installing-postgis.mdx
+++ /dev/null
@@ -1,44 +0,0 @@
----
-layout: default
-title: Installing PostGIS
----
-
-# 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
-```
-
-From there you can go to the [Examples](/documentation/examples) section. The
[Import OpenStreetMap data into
PostGIS](/documentation/examples/import-osm-into-postgis) example is the first
step to produce custom high resolution vector tiles.
diff --git a/src/pages/documentation/getting-started/installing-the-cli.mdx
b/src/pages/documentation/getting-started/installing-the-cli.mdx
deleted file mode 100644
index 1d071db..0000000
--- a/src/pages/documentation/getting-started/installing-the-cli.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
----
-layout: default
-title: Installing the CLI
----
-
-# 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/examples/geocoding/) or [IP
to location](/documentation/examples/ip-to-location/), head directly into the
related examples.
diff --git a/src/pages/index.mdx b/src/pages/index.mdx
index 356149a..dae4c80 100644
--- a/src/pages/index.mdx
+++ b/src/pages/index.mdx
@@ -129,7 +129,7 @@ export function OSMCopyright() {
index={6}
large
style={{ height: 450 }}
- href="/documentation/examples/geocoding"
+ href="/documentation/additional-examples/geocoding"
>
<OSMCopyright />
<Image
