diff --git a/docs/docs/install/docker.mdx b/docs/docs/install/docker.mdx new file mode 100644 index 00000000..b6c5c880 --- /dev/null +++ b/docs/docs/install/docker.mdx @@ -0,0 +1,60 @@ +--- +sidebar_label: "Docker" +title: "Docker Installation" +--- + +Postcodes.io can be installed using two Docker containers: the postcodes.io application container and the postcodes.io database container. + +### Requirements + +- Local copy of [postcodes.io repository](https://github.com/ideal-postcodes/postcodes.io) +- [Docker](https://www.docker.com/) + +### Quickstart + +If you want to launch the postcodes.io HTTP interface and underlying database quickly, you may do so with `docker-compose`. + +Clone the project repository and run docker-compose: + +```bash +$ docker-compose up -d +``` + +Running the above command in your terminal will create and network the containers. The HTTP service will be available on port `8000`. + +### Application Container + +The Postcodes.io application, which provides the HTTP interface, is packaged as a Docker container identified on the Docker Hub as `idealpostcodes/postcodes.io`. + +Example usage: + +```bash +$ docker run -d -p 8000 idealpostcodes/postcodes.io +``` + +Configuration available via Environment Variables: + +- `POSTGRES_USER` +- `POSTGRES_PASSWORD` +- `POSTGRES_DATABASE` +- `POSTGRES_HOST` +- `POSTGRES_PORT` +- `PORT (HTTP Port to run on)` + +### Database Container + +`idealpostcodes/postcodes.io.db` points to a [PostgreSQL & PostGIS](https://hub.docker.com/r/mdillon/postgis/) base image and preloads the latest `pg_dump` in the initialization process. The database Docker image is updated with new releases of the ONSPD dataset. + +The database Docker image is updated with new releases of the ONSPD dataset. See the [Changelog](https://github.com/ideal-postcodes/postcodes.io/blob/master/CHANGELOG.md) for when a new dataset has been ingested. + +:::info +Upon starting a container for the first time, PostGIS will be enabled and the `pg_dump` will take 15-60s to restore depending on your system resources. +::: + +Example Usage: + +```bash +$ docker run -p 5432 -e POSTGRES_USER=postcodesio -e POSTGRES_DB=postcodesiodb -e POSTGRES_PASSWORD=password idealpostcodes/postcodes.io.db +``` + +As this contains the official PostreSQL base image, the available configuration environment variables are documented [here](https://hub.docker.com/_/postgres/) diff --git a/docs/docs/install/manual-installation.mdx b/docs/docs/install/manual-installation.mdx new file mode 100644 index 00000000..2de218af --- /dev/null +++ b/docs/docs/install/manual-installation.mdx @@ -0,0 +1,31 @@ +--- +sidebar_label: "Script" +title: "Script Installation" +--- + +The install scripts can be linked to your shell (or can be found in the `bin/` directory). To link, navigate to `postcodes.io/` and run `$ npm link` + +### ONS Postcode Directory + +Download the latest Office for National Statistics "Postcode Lookup Dataset". Unzip the data locally. Run the import script `$ postcodesio-onspd` passing the path to the CSV data. + +```bash +$ postcodesio-onspd /path/to/data/ONSPD/Data/data.csv +``` + +### Scottish Postcode Directory + +Download the latest National Records Scotland "Scottish Postcode Directory". Unzip the data locally. Run the import script `$ postcodesio-scotpd` passing the path CSV data directory. + +```bash +$ postcodesio-scotpd /path/to/data +``` + +### OS Open Names + +Download the latest Ordnance Survey Open Names dataset. Unzip the data locally. Run the import script `$ postcodesio-oson` passing the path that contains the CSV data files. + +```bash +$ postcodesio-oson /path/to/data/opname_csv_gb/Data/ + +``` diff --git a/docs/docs/install/pg-dump.mdx b/docs/docs/install/pg-dump.mdx new file mode 100644 index 00000000..9d03af7c --- /dev/null +++ b/docs/docs/install/pg-dump.mdx @@ -0,0 +1,14 @@ +--- +sidebar_label: "pg_dump" +title: "Manual Installation `pg_dump`" +--- + +You can download a `pg_dump` of the database. This is the same dump used by the install script. The link to the latest dump can be found in our [repository](https://github.com/ideal-postcodes/postcodes.io/blob/master/latest). + +To set up the database from our `pg_dump` download, `gunzip` and use either `psql` or `pg_restore` to import the data into PostgreSQL. + +For example, + +```bash +$ cat postcodeiodb.sql | psql postcodesiodb +``` diff --git a/docs/docs/install/script.mdx b/docs/docs/install/script.mdx new file mode 100644 index 00000000..229c9431 --- /dev/null +++ b/docs/docs/install/script.mdx @@ -0,0 +1,29 @@ +--- +sidebar_label: "Script" +title: "Script Installation" +--- + +## Requirements + +- Local copy of [postcodes.io repository](https://github.com/ideal-postcodes/postcodes.io) +- [Node.js](https://nodejs.org/en) +- [PostgreSQL and PostGIS](https://postgis.net/documentation/getting_started/) + +### Operating System Compatibility + +Currently, the install process targets Linux and macOS systems. Please let us know if you have issues on those or any other operating systems. + +## Installation Steps + +Postcodes.io is packaged with a script to provision PostgreSQL and download a dump of the dataset. The script will perform the following tasks: + +- Prompt you for your PostgreSQL superuser credentials (most of the setup steps require this level of privilege) +- Create a new database +- Create a new readonly user for the new database +- Download, unzip and stream the `pg_dump` into the new database + +To run, + +```bash +$ npm run setup +``` diff --git a/docs/sidebars.ts b/docs/sidebars.ts index c7b3846e..741ae76a 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -18,6 +18,17 @@ const sidebars: SidebarsConfig = { tutorialSidebar: [ "overview", + { + type: "category", + label: "How to Install", + collapsed: false, + items: [ + "install/docker", + "install/script", + "install/pg-dump", + "install/manual-installation", + ], + }, { type: "category", label: "Available Data Fields",