(incubator-baremaps) branch main updated: Improve the documentation

[bc...@apache.org]

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.git


The following commit(s) were added to refs/heads/main by this push:
     new 36584f4a4 Improve the documentation
36584f4a4 is described below

commit 36584f4a4fbdc5d383ecca3e686f015587451d44
Author: Bertil Chapuis <bc...@gmail.com>
AuthorDate: Wed Oct 30 17:59:58 2024 +0100

    Improve the documentation
---
 README.md         | 28 ++++++----------------------
 basemap/README.md | 22 ++++++++++++++++++++--
 2 files changed, 26 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 41ffd4b22..d7799be2a 100644
--- a/README.md
+++ b/README.md
@@ -33,35 +33,19 @@ limitations under the License.
 
 ## 📖 How do I use Apache Baremaps?
 
-You can find the documentation on the project's [website](https://baremaps.apache.org/). The following pages showcase the main uses of Apache Baremaps.
-
-- The [OpenStreetMap](https://baremaps.apache.org/documentation/examples/import-osm-into-postgis) example is a good introduction to Baremaps, it shows how to produce high resolution vector tiles.
-- The [NaturalEarth](https://baremaps.apache.org/documentation/examples/import-naturalearth-into-postgis) example shows how to produce low resolution vector tiles.
-- The [Contour](https://baremaps.apache.org/documentation/examples/import-contour-into-postgis) example shows how to produce contour lines from a digital elevation model.
-- The [IP to location](https://baremaps.apache.org/documentation/examples/ip-to-location) example shows how to create and serve an IP to location service in a simple web application.
-- The [Geocoding](https://baremaps.apache.org/documentation/examples/geocoding) example shows how to create and serve a geocoding service in a simple web application.
+You can find a [getting started](https://baremaps.apache.org/documentation/getting-started/) and [additional examples] on the project's [website](https://baremaps.apache.org/).
 
 ## 👩‍💻 How do I contribute?
 
-There are many places where you can contribute to Apache Baremaps such as the code, the documentation, the website or the examples.
-
-The official documentation is located in a separate [repository](https://github.com/apache/incubator-baremaps-site).
-
-If you want to contribute to the code you can refer to the following developer guides available in the documentation.
-
-- [Project structure](https://baremaps.apache.org/documentation/developer-manual/project-structure)
-- [How to build with Maven](https://baremaps.apache.org/documentation/developer-manual/how-to-build-with-maven)
-- [Set up in IntelliJ IDEA](https://baremaps.apache.org/documentation/developer-manual/setup-in-intellij)
-- [Geocoder](https://baremaps.apache.org/documentation/developer-manual/geocoder)
-- [IP to location](https://baremaps.apache.org/documentation/developer-manual/ip-to-location)
-- [Basemap](https://baremaps.apache.org/documentation/developer-manual/basemap)
+There are many places where you can contribute to Apache Baremaps and your contributions are more than welcome.
 
-You can also contribute in the following ways.
+The [developer manual](https://baremaps.apache.org/documentation/additional-examples/) provides a good starting point on how to build and run the project from source.
 
+You can contribute in the following ways:
 - Improve the code: Report [a bug or submit a feature request](https://github.com/apache/incubator-baremaps/issues), or [submit a pull request](https://github.com/apache/incubator-baremaps/pulls) in the [incubator-baremaps](https://github.com/apache/incubator-baremaps/) repository.
 - Improve the documentation: Report [documentation issue](https://github.com/apache/incubator-baremaps-site/issues) or [submit a pull request](https://github.com/apache/incubator-baremaps-site/pulls) in the [incubator-baremaps-site](https://github.com/apache/incubator-baremaps-site/) repository.
-- [Join the mailing list](https://lists.apache.org/list.html?dev@baremaps.apache.org): Initiate or participate in project discussions on the mailing list
-- Write a post: Write a post to share your use cases and experiences with Apache Baremaps
+- [Join the mailing list](https://lists.apache.org/list.html?dev@baremaps.apache.org): Initiate or participate in project discussions on the mailing list.
+- Write a post: Write a post to share your use cases and experiences with Apache Baremaps.
 
 Finally, check out [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md).
 
diff --git a/basemap/README.md b/basemap/README.md
index 3f90a06a8..f89e3f4f0 100644
--- a/basemap/README.md
+++ b/basemap/README.md
@@ -34,9 +34,27 @@ A PostgreSQL database with the PostGIS extension should be accessible with the f
 jdbc:postgresql://localhost:5432/baremaps?user=baremaps&password=baremaps
 ```
 
+If you plan on importing the whole planet, you will need a powerful machine with a lot of storage. You may also want to modify the `postgresql.conf` file to increase some of the default settings.
+
+```
+work_mem = 4GB
+shared_buffers = 4GB
+maintenance_work_mem = 16GB
+autovacuum_work_mem = 4GB
+max_worker_processes = 16
+max_parallel_workers_per_gather = 8
+max_parallel_workers = 16
+wal_level = minimal
+checkpoint_timeout = 10min
+max_wal_size = 20GB
+min_wal_size = 80MB
+checkpoint_completion_target = 0.9
+max_wal_senders = 0
+```
+
 ## Importing the data
 
-Assuming that the necessary requirements have been installed, the database can be populated with the following command.
+Assuming that the necessary requirements have been installed, the database can be populated with the following command. The import workflow will download openstreetmap (osm.pbf) and other data sources into the database.
 
 ```
 baremaps workflow execute --file import.js
@@ -44,7 +62,7 @@ baremaps workflow execute --file import.js
 
 ## Updating the data
 
-The data can be updated with the following command. The update workflow will download the latest changes from the OpenStreetMap API and apply them to the database.
+The data can periodically be updated with the following command. The update workflow will download the latest changes from OpenStreetMap (osc.xml) and apply them to the database.
 
 ```
 baremaps workflow execute --file update.js