how to install

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/)

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/
+
+```

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
+```

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
+```

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",