docs: add operator quick start guide BM-775 (#3001)

#### Motivation To give people a better understanding on how easy it is to spin up a basemaps server, create a operator quick start guide to spin up a server and start using it. #### Modification Creates the structure for more quick start guides and creates a operator quick start guide.
linz · Nov 14, 2023 · 452cb98 · 452cb98
1 parent 400dfbd
commit 452cb98
Show file tree

Hide file tree

Showing 4 changed files with 120 additions and 2 deletions.
diff --git a/docs/index.css b/docs/index.css
@@ -1,4 +1,3 @@
 .md-header {
-    background: linear-gradient(70deg,#00425d 12%,#007198);
+  background: linear-gradient(70deg, #00425d 12%, #007198);
 }
-
diff --git a/docs/operator-guide/quick-start.md b/docs/operator-guide/quick-start.md
@@ -0,0 +1,106 @@
+# Running LINZ Basemaps - Quick Start
+
+There are three options for LINZ basemaps server deployment
+
+- Using docker and `@basemaps/server`
+- Running `@basemaps/server` manually
+- Deploying `@basemaps/server` as a AWS Lambda Function
+
+The easiest option for running linz/basemaps is using `docker` and [@basemaps/server](https://github.com/linz/basemaps/pkgs/container/basemaps%2Fserver) container
+
+As a base you will need some imagery, [docker](https://docs.docker.com/engine/install/) and the AWS Command line
+
+## Sample Imagery
+
+To use basemaps, we need some [Cloud optimised geotiffs](https://www.cogeo.org/) (COGs), and optionally their [STAC](https://stacspec.org/) metadata
+
+LINZ has a public bucket [`s3://nz-imagery`](https://github.com/linz/imagery) which contains COGs which work well with basemaps.
+
+Wānaka is a nice location so lets grab a combination of rural and urban imagery around Wānaka
+
+- [Queenstown-Lakes 2022-2023 0.1m](https://basemaps.linz.govt.nz/@-44.6966924,169.1330252,z14.74?i=queenstown-lakes-2022-2023-0.1m)
+- [Otago Rural 2017-2019 0.3m](https://basemaps.linz.govt.nz/@-44.6966924,169.1330252,z12.74?i=otago-rural-2017-2019-0.3m)
+
+Make a location to put the imagery
+
+```bash
+mkdir -p imagery/queenstown-lakes_2022-2023_0.1m/
+mkdir -p imagery/otago_2017-2019_0.3m/
+```
+
+First download the `collection.json` since this bucket is public, use `--no-sign-request` with the aws cli
+
+```bash
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/collection.json imagery/queenstown-lakes_2022-2023_0.1m/collection.json
+aws --no-sign-request s3 cp s3://nz-imagery/otago/otago_2017-2019_0.3m/rgb/2193/collection.json imagery/otago_2017-2019_0.3m/collection.json
+```
+
+Download the Rural imagery 0.3m resolution
+
+```bash
+aws --no-sign-request s3 cp s3://nz-imagery/otago/otago_2017-2019_0.3m/rgb/2193/CB12_5000_0107.tiff imagery/otago_2017-2019_0.3m/CB12_5000_0107.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/otago_2017-2019_0.3m/rgb/2193/CB12_5000_0108.tiff imagery/otago_2017-2019_0.3m/CB12_5000_0108.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/otago_2017-2019_0.3m/rgb/2193/CA12_5000_1007.tiff imagery/otago_2017-2019_0.3m/CA12_5000_1007.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/otago_2017-2019_0.3m/rgb/2193/CA12_5000_1008.tiff imagery/otago_2017-2019_0.3m/CA12_5000_1008.tiff
+```
+
+Download the Urban imagery 0.1m resolution
+
+```bash
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0434.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0434.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0435.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0435.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0435.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0435.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0436.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0436.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0437.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0437.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0438.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0438.tiff
+
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0534.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0534.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0535.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0535.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0536.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0536.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0536.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0536.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0537.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0537.tiff
+aws --no-sign-request s3 cp s3://nz-imagery/otago/queenstown-lakes_2022-2023_0.1m/rgb/2193/CB12_1000_0538.tiff imagery/queenstown-lakes_2022-2023_0.1m/CB12_1000_0538.tiff
+```
+
+## Running Basemaps in Docker
+
+Basemaps server can be run in two modes
+
+1. Directly from the tiff and stac folders
+2. With a configuration file
+
+Directly from the tiffs is easier and faster to setup but does not allow for a more custom setup.
+
+### Directly from the tiff files
+
+To start the server, mount the imagery into `/imagery` so the server has access to it
+
+```bash
+docker run --rm -v $PWD/imagery:$PWD/imagery -p 5000:5000 ghcr.io/linz/basemaps/server:latest $PWD/imagery/*
+```
+
+!!! note
+Basemaps logs into structured JSON log format it can be useful to run a prettier over it such as [pretty-json-log](https://www.npmjs.com/package/pretty-json-log)
+
+    ```bash
+    docker run --rm -v $PWD/imagery:$PWD/imagery ghcr.io/linz/basemaps/server:latest $PWD/imagery/* | pjl
+    ```
+
+The server should now be started and you should see the following log lines, informing you that two layers were loaded Otago and Queenstown in [NZTM2000Quad](https://github.com/linz/NZTM2000TileMatrixSet) tile matrix
+
+```
+INFO Imagery:Loaded imagery=/home/user/tmp/basemaps-quick-start/imagery/otago_2017-2019_0.3m title=otago_2017-2019_0.3m tileMatrix=NZTM2000Quad files=4
+INFO Imagery:Loaded imagery=/home/user/tmp/basemaps-quick-start/imagery/queenstown-lakes_2022-2023_0.1m title=queenstown-lakes_2022-2023_0.1m tileMatrix=NZTM2000Quad files=10
+```
+
+Then open a browser to `http://localhost:5000/layers` This will load a list of the layers that have been imported into the system, clicking on any of the layers will take you to the layer.
+
+![QuickStart Layers](./static/quick-start__layers.png)
+
+!!! note
+It is not recommended to run `:latest` for any prolonged period of time, all of the containers are published with the following tags
+
+    - `:latest` - Current master branch
+    - `:vX.Y.Z` - Specific release tag which does not move eg `:v0.0.0`
+    - `:vX.Y` - Moving tag for the latest major.minor release eg `:v7.0`
+    - `:vX` - Moving tag for the latest major release eg `:v7`
diff --git a/docs/operator-guide/static/quick-start__layers.png b/docs/operator-guide/static/quick-start__layers.png
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -0,0 +1,13 @@
+# Quick start guide
+
+This document is broken down into three user types: User, Operator and Developer.
+
+- **User** wants to use the basemaps service running on [https://basemaps.linz.govt.nz](https://basemaps.linz.govt.nz)
+- **Operator** wants to use `@basemaps/server` or `@linzjs/lambda-tiler` on their own imagery
+- **Developer** wants to modify the linz/basemaps source code to meet their needs.
+
+There are three separate quick start guides for these users.
+
+- [User Quick Start](./user-guide/quick-start.md)
+- [Operator Quick Start](./operator-guide/quick-start.md)
+- [Developer Quick Start](./developer-guide/quick-startm.md)