Skip to content

Refresh documentation for 0.7.0 release #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 22, 2023
Merged

Refresh documentation for 0.7.0 release #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4a81271
Starting to overhaul docs. Quite a few changes related to --replicati…
rustprooflabs Jan 21, 2023
0de0fb7
Suggest putting external connection details in private config file to…
rustprooflabs Jan 21, 2023
217a680
Cleanup
rustprooflabs Jan 21, 2023
b93bec2
Update routing doc for Docker image including cleanup for multilinest…
rustprooflabs Jan 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 43 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,28 @@ This project's approach is to do as much processing in the Lua styles
passed along to osm2pgsql, with post-processing steps creating indexes,
constraints and comments.

## Quick start

See the [Docker Usage](#docker-usage) section below for an explanation of
these commands.

```bash
mkdir ~/pgosm-data
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=mysecretpassword

docker run --name pgosm -d --rm \
-v ~/pgosm-data:/app/output \
-v /etc/localtime:/etc/localtime:ro \
-e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
-p 5433:5432 -d rustprooflabs/pgosm-flex

docker exec -it \
pgosm python3 docker/pgosm_flex.py \
--ram=8 \
--region=north-america/us \
--subregion=district-of-columbia
```


## Versions Supported
Expand Down Expand Up @@ -57,21 +79,24 @@ package used to determine the best osm2pgsql command assumes fast SSDs.

## PgOSM via Docker

The easiest way to use PgOSM-Flex is with the
[Docker image](https://hub.docker.com/r/rustprooflabs/pgosm-flex) hosted on
Docker Hub.
The image has all the pre-requisite software installed,
handles downloading an OSM region (or subregion)
from Geofabrik, and saves an output `.sql` file with the processed data
ready to load into your database(s).
The PBF/MD5 source files are archived by date on your local storage
with the ability to easily reload them at a later date.
The PgOSM Flex
[Docker image](https://hub.docker.com/r/rustprooflabs/pgosm-flex)
is hosted on Docker Hub.
The image includes all the pre-requisite software and handles all of the options,
logic, an post-processing steps required. Features include:

* Automatic data download from Geofabrik and validation against checksum
* Custom Flex layers built in Lua
* Mix and match layers using Layersets
* Loads to Docker-internal Postgres, or externally defined Postgres
* Supports `osm2pgsql-replication` and `osm2pgsql --append` mode
* Export processed data via `pg_dump` for loading into additional databases


### Docker usage

This section outlines a typical import using Docker to run PgOSM-Flex.
See [the full Docker instructions in docs/DOCKER-RUN.md](docs/DOCKER-RUN.md).
This section outlines a typical import using Docker to run PgOSM Flex.
See the full Docker instructions in [docs/DOCKER-RUN.md](docs/DOCKER-RUN.md).

Create directory for the `.osm.pbf` file, output `.sql` file, log output, and
the osm2pgsql command ran.
Expand All @@ -90,7 +115,7 @@ export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=mysecretpassword
```

Start the `pgosm` Docker container. At this point, PostgreSQL / PostGIS
Start the `pgosm` Docker container. At this point, Postgres / PostGIS
is available on port `5433`.

```bash
Expand All @@ -110,7 +135,6 @@ along with a region/subregion.
* Sub-region (`district-of-columbia`) (Optional)



```bash
docker exec -it \
pgosm python3 docker/pgosm_flex.py \
Expand All @@ -128,7 +152,6 @@ it takes to download the 17 MB PBF file + ~ 1 minute processing.

### After processing


The processed OpenStreetMap data is also available in the Docker container on port `5433`.
You can connect and query directly in the Docker container.

Expand All @@ -150,33 +173,20 @@ again in the future, either with the same version of PgOSM Flex or the latest ve
to load these historic files.


If the optional `--pg-dump` option is used, the output `.sql` is also saved in
If `--pg-dump` option is used the output `.sql` is also saved in
the `~/pgosm-data` directory.
This `.sql` file can be loaded into any other database with PostGIS and the proper
permissions.


```bash
ls -alh ~/pgosm-data/

-rw-r--r-- 1 root root 17M Nov 2 19:57 district-of-columbia-2021-11-03.osm.pbf
-rw-r--r-- 1 root root 70 Nov 2 19:59 district-of-columbia-2021-11-03.osm.pbf.md5
-rw-r--r-- 1 root root 156M Nov 3 19:10 pgosm-flex-north-america-us-district-of-columbia-default-2021-11-03.sql
-rw-r--r-- 1 root root 18M Jan 21 03:45 district-of-columbia-2023-01-21.osm.pbf
-rw-r--r-- 1 root root 70 Jan 21 04:39 district-of-columbia-2023-01-21.osm.pbf.md5
-rw-r--r-- 1 root root 163M Jan 21 16:14 north-america-us-district-of-columbia-default-2023-01-21.sql
```

This `.sql` file can be loaded into a PostGIS enabled database. The following example
creates an empty `myosm` database to load the processed OpenStreetMap data into.


```bash
psql -d postgres -c "CREATE DATABASE myosm;"
psql -d myosm -c "CREATE EXTENSION postgis;"

psql -d myosm \
-f ~/pgosm-data/pgosm-flex-north-america-us-district-of-columbia-default-2021-11-03.sql
```


> See [more in docs/DOCKER-RUN.md](docs/DOCKER-RUN.md) about other ways to customize how PgOSM Flex runs.


## Layer Sets

Expand Down
Loading