From c463617f0e40abd0568f30f52fb124f9e0bfa945 Mon Sep 17 00:00:00 2001 From: Bertil Chapuis Date: Wed, 16 Oct 2024 23:03:30 +0200 Subject: [PATCH] Improve the structure of the documentation --- src/pages/documentation/_meta.json | 3 +- .../documentation/additional-examples.mdx | 34 +++++ .../_meta.json | 0 .../_serving-vector-tiles.txt | 0 .../contour-lines-in-vector-tiles.mdx | 0 .../extrusion.mdx | 6 +- .../gdal-macos.mdx | 0 .../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 ---- .../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 | 126 ++++++++++++++++++ .../documentation/getting-started/_meta.json | 4 - .../getting-started/installing-postgis.mdx | 44 ------ .../getting-started/installing-the-cli.mdx | 36 ----- src/pages/documentation/index.mdx | 2 +- src/pages/index.mdx | 2 +- 24 files changed, 180 insertions(+), 180 deletions(-) create mode 100644 src/pages/documentation/additional-examples.mdx rename src/pages/documentation/{examples => additional-examples}/_meta.json (100%) rename src/pages/documentation/{examples => additional-examples}/_serving-vector-tiles.txt (100%) rename src/pages/documentation/{examples => additional-examples}/contour-lines-in-vector-tiles.mdx (100%) rename src/pages/documentation/{examples => additional-examples}/extrusion.mdx (91%) rename src/pages/documentation/{examples => additional-examples}/gdal-macos.mdx (100%) rename src/pages/documentation/{examples => additional-examples}/geoadmin.mdx (100%) rename src/pages/documentation/{examples => additional-examples}/geocoding.mdx (86%) rename src/pages/documentation/{examples => additional-examples}/import-naturalearth-into-postgis.mdx (92%) rename src/pages/documentation/{examples => additional-examples}/import-osm-into-postgis.mdx (96%) rename src/pages/documentation/{examples => additional-examples}/ip-to-location.mdx (96%) rename src/pages/documentation/{examples => additional-examples}/serve-and-export-vector-tiles.mdx (89%) delete mode 100644 src/pages/documentation/basemap.mdx delete mode 100644 src/pages/documentation/examples.mdx delete mode 100644 src/pages/documentation/getting-started.md create mode 100644 src/pages/documentation/getting-started.mdx delete mode 100644 src/pages/documentation/getting-started/_meta.json delete mode 100644 src/pages/documentation/getting-started/installing-postgis.mdx delete mode 100644 src/pages/documentation/getting-started/installing-the-cli.mdx diff --git a/src/pages/documentation/_meta.json b/src/pages/documentation/_meta.json index 646004b0..9ab92dfb 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 00000000..519a9cf0 --- /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 git@github.com: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. 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 fba0fa98..9a767485 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 07b3e04f..c06ce307 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 667cfac9..d7cf7d7d 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 98682671..6551a826 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 592d50f4..4d21928f 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 a03fa0a1..d6a79f52 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 6c8ba57c..00000000 --- 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'; - -
- -
- -## 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 21ddc695..e7092bf0 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 85ae04d7..ef13dffc 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 81c48371..00000000 --- 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 git@github.com: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 4438ea0f..00000000 --- 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 00000000..1dc798d0 --- /dev/null +++ b/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'; + +
+ +
+ +## 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--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. diff --git a/src/pages/documentation/getting-started/_meta.json b/src/pages/documentation/getting-started/_meta.json deleted file mode 100644 index 5788dec8..00000000 --- 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 f64dd93c..00000000 --- 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 1d071db5..00000000 --- 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--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/documentation/index.mdx b/src/pages/documentation/index.mdx index 9eac9074..c06269f1 100644 --- a/src/pages/documentation/index.mdx +++ b/src/pages/documentation/index.mdx @@ -3,5 +3,5 @@ Apache Baremaps is an [open source](https://github.com/apache/incubator-baremaps/blob/main/LICENSE) toolkit and a set of infrastructure components for creating, publishing, and operating online maps. It provides a data pipeline enabling developers to build maps with different data sources. It offers live reload capabilities that allow cartographers to rapidely customize the content and the style of a map. -It comes with a [default schema and style](https://baremaps.apache.org/documentation/basemap/) similar to [OpenStreetMap Carto](https://github.com/gravitystorm/openstreetmap-carto). +It comes with a [default schema and style](https://baremaps.apache.org/documentation/getting-started/) similar to [OpenStreetMap Carto](https://github.com/gravitystorm/openstreetmap-carto). Finally, it aims at providing a set of services commonly used in online maps, such as location search and IP to location. diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 356149a8..dae4c807 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" >