chore(wiki): add sync and analytics wiki page (#1177)

* Add sync and analytics wiki page

* Add a few more sections with chronicle quirks

* Add Docker setup guide

* Improve guide; Address comments

* More cleanup

* More fixes

* Add environment file preparation info, and more

* I cannot write

* Add JWT info

* Reorg docker docs

* Little more detail

* Add bit about env and fix docker compose

* Add blurb about .env file

* Add ENV defaults

* Update documentation/docs/reference/sync_and_analytics.md

Co-authored-by: /alex/ <alexander.schmidt@iota.org>

* Update documentation/docs/reference/sync_and_analytics.md

Co-authored-by: /alex/ <alexander.schmidt@iota.org>

---------

Co-authored-by: Alexander Schmidt <alexander.schmidt@iota.org>

docker/prepare_docker.sh → docker/create_dirs.sh

@@ -7,16 +7,15 @@ if [[ "$OSTYPE" != "darwin"* && "$EUID" -ne 0 ]]; then
   exit
 fi
 
-# Prepare Hornet's data directory.
-mkdir -p ${DIR}/data/hornet
+# Prepare data directory.
 mkdir -p ${DIR}/data/hornet/alphanet
 mkdir -p ${DIR}/data/hornet/testnet
 mkdir -p ${DIR}/data/hornet/shimmer
-mkdir -p ${DIR}/data/chronicle
 mkdir -p ${DIR}/data/chronicle/mongodb
 mkdir -p ${DIR}/data/chronicle/influxdb
 mkdir -p ${DIR}/data/grafana
 mkdir -p ${DIR}/data/prometheus
+
 if [[ "$OSTYPE" != "darwin"* ]]; then
   chown -R 65532:65532 ${DIR}/data
 fi

docker/docker-compose.yml

@@ -139,7 +139,7 @@ services:
     ports:
       - 9216:9261
     command:
-      - "--mongodb.uri=mongodb://root:root@mongo:27017"
+      - "--mongodb.uri=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongo:27017"
       - "--mongodb.direct-connect=true"
       - "--web.listen-address=:9216"
       - "--log.level=info"

documentation/docs/getting_started/docker.md

@@ -2,22 +2,78 @@
 keywords:
 - documentation
 - docker
+- guide
 ---
 
-# Docker
+# Run `INX Chronicle` using Docker
 
-## Usage
+This guide describes the necessary steps to set up and run `Chronicle` as an INX plugin of a `Hornet` node to persist Tangle data, gather time series analytics using `InfluxDB`, and display it in meaningful ways using `Grafana`.
 
-The easiest way to start Chronicle is by using our supplied Dockerfile.
+## Prerequisites
 
-First you need to setup the correct permissions for the node's database:
+1. A recent release of Docker enterprise or community edition. You can find installation instructions in the [official Docker documentation](https://docs.docker.com/engine/install/).
+2. [Docker Compose V2](https://docs.docker.com/compose/install/).
+
+## Preparation
+
+Create the necessary directories for all `Hornet` and `Chronicle` databases:
+
+```
+./docker/create_dirs.sh
+```
+
+## Configuration
+
+Configure the docker images via command-line arguments by editing the `docker-compose.yml` file. 
+
+Refer to the Chronicle CLI (run `inx-chronicle --help`) for details about configuring Chronicle via command-line arguments.
+
+See the [Hornet Wiki](https://wiki.iota.org/hornet/references/configuration/) for details about configuring `Hornet`.
+
+## Environment
+
+Chronicle's docker setup uses several environment variables. These must be configured in order to run the docker compose file as-is. These variables can be defined in a `.env` file and specified to docker using the `--env-file` flag.
+
+```ini
+MONGODB_USERNAME=root
+MONGODB_PASSWORD=root
+MONGODB_CONN_STR=mongodb://root:root@mongo:27017
+INFLUXDB_URL=http://influx:8086
+INFLUXDB_USERNAME=admin
+INFLUXDB_PASSWORD=password
+JWT_PASSWORD=password
+JWT_SALT=saltines
+```
 
 ```sh
-./docker/prepare_docker.sh
+docker compose -f docker/docker-compose.yml --env-file .env up
 ```
 
-After that, with Docker installed on your system, you can spin up Chronicle by running the following command from the root of the repository.
+For more information, see the [docker docs](https://docs.docker.com/compose/environment-variables).
+
+## Docker Image Build Variants
+
+Chronicle has two build variants, which can be selected using the corresponding YML override file.
+
+### Production
+
+```sh
+docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod.yml up
+```
+
+### Debug
+
 
 ```sh
-docker-compose -f docker/docker-compose.yml up --build
+docker compose -f docker/docker-compose.yml up
 ```
+
+## Analytics and Metrics
+
+To run the images needed to support the Metrics and Analytics dashboards, run `docker compose` using the `metrics` profile:
+
+```sh
+docker compose -f docker/docker-compose.yml --profile metrics up
+```
+
+Access the Grafana dashboard at `http://localhost:3000/`.

documentation/docs/reference/sync_and_analytics.md

@@ -0,0 +1,37 @@
+---
+keywords:
+- documentation
+- inx
+- reference
+- sync
+---
+
+# INX Syncing
+
+The primary function of Chronicle is to gather confirmed tangle data via an INX connection. This connection will most likely be to an IOTA Node, which should be on the same machine as the Chronicle instance.
+
+When running with the `inx` feature (default using the docker image), Chronicle will stream data from the `INX_URL` and store it in the configured `MongoDB` instance.
+
+## Singleton Writer
+
+Chronicle assumes that it is the only instance writing to the configured `MongoDB` database. Otherwise it will exit due to write conflicts.
+
+## Network Name Link
+
+When Chronicle starts for the first time, it stores the latest network protocol parameters. It uses these to check that the same network is used across the lifetime of the dataset. In particular, the network name must not change, or Chronicle will fail to start.
+
+## Ledger State
+
+When Chronicle starts syncing, it will get the current Ledger State from the INX source. Though Chronicle can sync back to the earliest data the INX connection can provide, the data may not be valid until it catches up to the ledger index of that initial state.
+
+## Analytics
+
+The starting index determines when Analytics can begin. Analytics are calculated incrementally per-milestone, but require an initial ledger state which is only valid once Chronicle has caught up to the starting index.
+
+# CLI Analytics
+
+Analytics can also be synced manually using the `fill-analytics` command-line tool. It should not be run until Chronicle reports that it is healthy (see the `/health` endpoint) or else the results may not be correct. However, if this happens, re-running the analytics when Chronicle is healthy will overwrite the previous values.
+
+The `--num-tasks` flag can be used to parallelize these processes, but be warned: There is currently no feature to resume halted analytics. If the process is canceled without completing, it may be very difficult to restart it without re-calculating analytics.
+
+For the list of supported analytics of each kind and more information, refer to the CLI documentation (via `chronicle --help`).

documentation/sidebars.js

@@ -38,6 +38,11 @@ module.exports = {
       label: "References",
       collapsed: false,
       items: [
+        {
+          type: "doc",
+          id: "reference/sync_and_analytics",
+          label: "Sync and Analytics",
+        },
         {
           type: "doc",
           id: "reference/authentication",