docs: add --assets usage documentation (wip)

docs/developer-guide/cli-methods/bundle-the-basemaps-assets-archive.md

@@ -0,0 +1,82 @@
+# Bundle the `basemaps` assets archive
+
+This guide explains how to generate the `basemaps` bundled assets archive using the **basemaps/cli** package.
+
+## Get started
+
+Clone the [**linz/basemaps-config**][bm_config_repo] repository to your machine.
+
+=== "HTTPS"
+
+    ```bash
+    git clone https://github.com/linz/basemaps-config.git
+    ```
+
+=== "SSH"
+
+    ```bash
+    git clone git@github.com:linz/basemaps-config.git
+    ```
+
+=== "GitHub CLI"
+
+    ```bash
+    gh repo clone linz/basemaps-config
+    ```
+
+!!! abstract "Paths"
+
+    This guide uses variables as shorthand to reference key directories and files. On your machine, note the following paths:
+
+    === "`BM_CONFIG_REPO`"
+
+        The path to the **basemaps-config** repository folder on your machine.
+
+        ```bash
+        $BM_CONFIG_REPO = {path_to}/basemaps-config
+        ```
+
+    === "`BM_CLI_BUILD`"
+
+        The **basemaps/cli** package provides a **bundle-assets** function we can use to generate a bundled assets archive.
+
+        The path to the **build** folder of the **basemaps/cli** package.
+
+        ```bash
+        $BM_CLI_BUILD = $BM_REPO/packages/cli/build/cli
+        ```
+
+    === "`BM_SPRITES_BIN`"
+
+        The **basemaps/sprites** package provides a default function we can use to generate sprite sheets from a collection of sprite images.
+
+        The path to the **bin** folder of the **basemaps/sprites** package.
+
+        ```bash
+        $BM_SPRITES_BIN = $BM_REPO/packages/sprites/bin
+        ```
+## Run the `basemaps/cli` package
+
+### Command
+
+Use the following command to bundle the `basemaps` assets archive:
+
+```bash
+node $BM_CLI_BUILD/bin.js bundle-assets \
+    --assets $BM_CONFIG_REPO/assets \
+    --output assets.bundle.tar.co \
+```
+
+### Parameters
+
+=== "`--assets`"
+
+    Specifies the location of the assets folder to use. This folder refers to that of which is within the `basemaps-config` repository.
+
+=== "`--output`"
+
+    Specifies where to save the bundled assets archive, relative to the location from which you execute the command. You can specify a location and filename of your choice.
+
+<!-- external links -->
+
+[bm_config_repo]: https://github.com/linz/basemaps-config

docs/developer-guide/server-methods/serve-basemaps-with-bundled-config-file.md

@@ -4,43 +4,81 @@ This guide shows you how to configure and run the **basemaps/server** package us
 
 ## Configure the `basemaps/server` package
 
-The **basemaps/server** package requires a config file to serve the **basemaps** system.
+=== "Config file"
 
-You have two options. The first is to use the pre-generated config file stored in the **LINZ AWS S3** bucket. The second is to generate the config file yourself using the **basemaps/cli** package.
+    The **basemaps/server** package requires a config file to serve the **basemaps** system.
 
-=== "Using the pre-generated config file"
+    === "Using the pre-generated config file"
 
-    !!! abstract "Path"
+        !!! abstract "Path"
 
-        To use the exisiting config file stored in the **LINZ AWS S3** bucket, note of the following path:
+            To use the exisiting config file stored in the **LINZ AWS S3** bucket, note the following path:
 
-        === "`CONFIG_FILE`"
+            === "`CONFIG_FILE`"
 
-            The absolute path to the latest config file stored in the **LINZ AWS S3** bucket.
-            
-            ```bash
-            $CONFIG_FILE = s3://linz-basemaps/config/config-latest.json.gz
-            ```
+                The absolute path to the latest config file stored in the **LINZ AWS S3** bucket.
 
-=== "Generating the config file yourself"
+                ```bash
+                $CONFIG_FILE = s3://linz-basemaps/config/config-latest.json.gz
+                ```
 
-    To generate the config file yourself, follow the [**Bundle the `basemaps` config file**][bundle-the-basemaps-config-file] guide. Then, return to this section.
+    === "Generating the config file yourself"
 
-    !!! abstract "Path"
+        To generate the config file yourself, follow the [**Bundle the `basemaps` config file**][bundle-the-basemaps-config-file] guide. Then, return to this section.
 
-        Once you have generated the config file, make a note of the file's location:
+        !!! abstract "Path"
 
-        === "`CONFIG_FILE`"
+            Once you have generated the config file, make a note of the file's location:
 
-            The path to the generated config file on your machine.
-            
-            ```bash
-            $CONFIG_FILE = {path_to}/config.bundle.json
-            ```
+            === "`CONFIG_FILE`"
+
+                The path to the generated config file on your machine.
+
+                ```bash
+                $CONFIG_FILE = {path_to}/config.bundle.json
+                ```
+
+=== "Assets archive"
+
+    The **basemaps/server** package also allows you to specify the location of assets (e.g. fonts and sprites) to use when serving the **basemaps** system.
+
+    !!! tip "Note"
+
+        Specifying this location is not required to serve raster imagery. If you wish to serve vector imagery or view the labels overlay, you will need to specify this location. Otherwise, assets referenced by such layers will not load.
+
+    === "Using the pre-generated assets archive"
+
+        !!! abstract "Path"
+
+            To use the exisiting assets archive stored in the **LINZ AWS S3** bucket, note the following path:
+
+            === "`ASSETS_ARCHIVE`"
+
+                The absolute path to the latest assets archive stored in the **LINZ AWS S3** bucket.
+
+                ```bash
+                $ASSETS_ARCHIVE = s3://linz-basemaps/assets/assets-latest.tar.co
+                ```
+
+    === "Generating the assets archive yourself"
+
+        To generate the assets archive yourself, follow the [**Bundle the `basemaps` assets archive**][bundle-the-basemaps-assets-archive] guide. Then, return to this section.
+
+        !!! abstract "Path"
+
+            Once you have generated the assets archive, make a note of the archive's location:
+
+            === "`ASSETS_ARCHIVE`"
+
+                The path to the generated assets archive on your machine.
+
+                ```bash
+                $ASSETS_ARCHIVE = {path_to}/assets.bundle.tar.co
+                ```
 
 ## Run the `basemaps/server` package
 
-At this stage, you should have a path to a config file. Either, to that which you are sourcing from the **LINZ AWS S3** bucket, or, have generated using the **basemaps/cli** package.
+At this stage, you should have a path to a config file. You may also have a path to an assets archive. Either of which you are sourcing from the **LINZ AWS S3** bucket, or, have generated using the **basemaps/cli** package.
 
 !!! abstract "Path"
 
@@ -56,18 +94,31 @@ At this stage, you should have a path to a config file. Either, to that which yo
 
 ### Command
 
-Use the following command to run the **basemaps** system:
+Use one of the following commands to run the **basemaps** system:
+
+=== "Without assets"
 
-```bash
+    ```bash
     node $BM_SERVER_BUILD/bin.js --config $CONFIG_FILE
-```
+    ```
+
+=== "With assets"
+
+    ```bash
+    node $BM_SERVER_BUILD/bin.js --config $CONFIG_FILE --assets $ASSETS_ARCHIVE
+    ```
 
 ### Parameters
 
 === "`--config`"
 
     Specifies the location of the bundled config file to use.
 
+=== "`--assets`"
+
+    Specifies the location of the bundled assets archive to use.
+
 <!-- internal links -->
 
-[bundle-the-basemaps-config-file]: ../cli-methods/bundle-the-basemaps-config-file.md
+[bundle-the-basemaps-config-file]: ../cli-methods/bundle-the-basemaps-config-file.md
+[bundle-the-basemaps-assets-archive]: ../cli-methods/bundle-the-basemaps-assets-archive.md