docs: improve documentation outline (#121)

txpipe · Oct 19, 2023 · 97b9f55 · 97b9f55
1 parent e5854f5
commit 97b9f55
Show file tree

Hide file tree

Showing 18 changed files with 111 additions and 49 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -6,7 +6,19 @@
   - [From Source](./installation/from_source.md)
   - [Docker](./installation/docker.md)
   - [Kubernetes](./installation/kubernetes.md)
-- [Usage](./usage/README.md)
-  - [Client Endpoint](./usage/client_endpoint.md)
+- [Configuration](./configuration/README.md)
+  - [Upstream](./configuration/upstream.md)
+  - [RollDB](./configuration/rolldb.md)
+  - [Serve](./configuration/serve.md)
+  - [Byron](./configuration/byron.md)
+  - [Logging](./configuration/logging.md)
+  - [Examples](./configuration/examples.md)
+- [Running](./running/README.md)
+  - [Sync](./running/sync.md)
+  - [Serve](./running/serve.md)
+  - [Daemon](./running/daemon.md)
+- [API](./api/README.md)
+  - [gRPC](./api/grpc.md)
+  - [Ouroboros](./api/ouroboros.md)
 - [Benchmarks](./benchmarks/README.md)
   - [Long-running operation](./benchmarks/long_running.md)
diff --git a/book/src/api/README.md b/book/src/api/README.md
@@ -0,0 +1 @@
+# API
diff --git a/book/src/usage/client_endpoint.md → book/src/api/grpc.md b/book/src/usage/client_endpoint.md → book/src/api/grpc.md
@@ -1,4 +1,5 @@
-# Client Endpoint
+# gRPC
+
 
 ## Introduction
 
@@ -7,30 +8,6 @@
 - The current implemented module is the `Sync` module that allows clients to sync with the state of the chain stored by Dolos
 - Dolos endpoint also supports gRPC-web, a variant of gRPC that can be used directly from browsers
 
-## Starting the server
-
-- There are 2 ways to start the server that provides access to the endpoints: the `serve` command and the `daemon` command
-
-### `serve` mode
-
-The `serve` command starts Dolos just with the purpose of exposing the client endpoint, no other functions are executed
-
-To start Dolos in `serve` mode run the following command from the terminal:
-
-```
-dolos serve
-```
-
-### `daemon` mode
-
-The `daemon` command starts Dolos with all of its main functions enabled (syncing from upstream, updating the ledger, etc) which includes the client endpoint server
-
-To start Dolos in `daemon` mode run the following command from the terminal:
-
-```
-dolos daemon
-```
-
 ## Connecting to the server
 
 - Once started, the server exposes TCP port

diff --git a/book/src/api/ouroboros.md b/book/src/api/ouroboros.md
@@ -0,0 +1 @@
+# Ouroboros
diff --git a/book/src/configuration/README.md b/book/src/configuration/README.md
@@ -0,0 +1,3 @@
+# Usage
+
+This section provides information on how to configure Dolos.
diff --git a/book/src/configuration/byron.md b/book/src/configuration/byron.md
@@ -0,0 +1,6 @@
+# Byron
+
+```toml
+[byron]
+path = "./byron.json"
+```
diff --git a/book/src/configuration/examples.md b/book/src/configuration/examples.md
@@ -0,0 +1,22 @@
+# Example Configuration
+
+## Preview Network
+
+```toml
+[upstream]
+peer_address = "preview-node.world.dev.cardano.org:30002"
+network_magic = 2
+
+[rolldb]
+path = "./data"
+k_param = 1000
+
+[serve.grpc]
+listen_address = "[::]:50051"
+
+[byron]
+path = "./byron.json"
+
+[logging]
+max_level = "debug"
+```
diff --git a/book/src/configuration/logging.md b/book/src/configuration/logging.md
@@ -0,0 +1,6 @@
+# Logging
+
+```toml
+[logging]
+max_level = "debug"
+```
diff --git a/book/src/configuration/rolldb.md b/book/src/configuration/rolldb.md
@@ -0,0 +1,7 @@
+# RollDB
+
+```toml
+[rolldb]
+path = "./data"
+k_param = 1000
+```
diff --git a/book/src/configuration/serve.md b/book/src/configuration/serve.md
@@ -0,0 +1,6 @@
+# Serve
+
+```toml
+[serve.grpc]
+listen_address = "[::]:50051"
+```
diff --git a/book/src/configuration/upstream.md b/book/src/configuration/upstream.md
@@ -0,0 +1,7 @@
+# Upstream
+
+```toml
+[upstream]
+peer_address = "preview-node.world.dev.cardano.org:30002"
+network_magic = 2
+```
diff --git a/book/src/installation/binary_release.md b/book/src/installation/binary_release.md
@@ -1,23 +1,10 @@
 # Binary Releases
 
-_Dolos_ can be run as a standalone executable. Follow the instructions for your particular OS / Platform to install a local copy from our Github pre-built releases.
+_Dolos_ can be run as a standalone executable. The [Github release](https://github.com/txpipe/dolos/releases/latest/) page includes the binaries for different OS and architectures. It's a self-contained, single-file binary that can be downloaded directly.
 
-## MacOS
-
-Use the following command to download and install _Dolos'_ binary release for MacOS:
+For simplicity, we also provide an install script that can be executed from your terminal to automate the installation process. This install script will only work for MacOS and Linux for either x86_64 and arm64 architecture. You can execute the install by running the following command from your terminal. You'll need curl and sudo access.
 
 ```sh
-curl --silent --location https://git.io/JD2iH | \
-    tar xz -C /tmp && mv /tmp/dolos /usr/local/bin
+curl -fsSL https://github.com/txpipe/dolos/raw/main/.github/public/install.sh -o get-dolos.sh
+sudo sh ./get-dolos.sh
 ```
-
-## GNU/Linux
-
-Use the following command to download and install _Dolos'_ binary release for GNU/Linux:
-
-```sh
-curl --silent --location https://git.io/JD2ix | \
-    tar xz -C /tmp && mv /tmp/dolos /usr/local/bin
-```
-
-Check the [latest release](https://github.com/txpipe/dolos/releases/latest) for more binary download options.
diff --git a/book/src/installation/docker.md b/book/src/installation/docker.md
@@ -34,8 +34,14 @@ docker run -d -v $(pwd)/daemon.toml:/etc/dolos/daemon.toml \
 
 Images are also tagged with the corresponding version number. It is highly recommended to use a fixed image version in production environments to avoid the effects of new features being included in each release (please remember dolos hasn't reached v1 stability guarantees).
 
-To use a versioned image, replace the `latest` tag by the desired version with the `v` prefix. For example, to use version `1.0.0`, use the following image:
+To use a versioned image, replace the `latest` tag by the desired version with the `v` prefix. For example, to use version `0.6.0`, use the following image:
 
 ```
-ghcr.io/txpipe/dolos:v1.0.0
+ghcr.io/txpipe/dolos:v0.6.0
 ```
+
+## Multiple Architectures
+
+_Dolos_ docker image is multi-arch, meaning that it can be used from different CPU architectures. We currently support `amd64` (aka `x86_64`) and `arm64`.
+
+The Docker daemon will detect your architecture and use the correct manifest to run the image. The usage procedures are the same regardless of the architecture.
diff --git a/book/src/running/README.md b/book/src/running/README.md
@@ -0,0 +1,5 @@
+# Usage
+
+This section provides information on how to use Dolos.
+
+- There are 2 ways to start the server that provides access to the endpoints: the `serve` command and the `daemon` command
diff --git a/book/src/running/daemon.md b/book/src/running/daemon.md
@@ -0,0 +1,9 @@
+# `daemon` mode
+
+The `daemon` command starts Dolos with all of its main functions enabled (syncing from upstream, updating the ledger, etc) which includes the client endpoint server
+
+To start Dolos in `daemon` mode run the following command from the terminal:
+
+```
+dolos daemon
+```
diff --git a/book/src/running/serve.md b/book/src/running/serve.md
@@ -0,0 +1,9 @@
+# `serve` mode
+
+The `serve` command starts Dolos just with the purpose of exposing the client endpoint, no other functions are executed
+
+To start Dolos in `serve` mode run the following command from the terminal:
+
+```
+dolos serve
+```
diff --git a/book/src/running/sync.md b/book/src/running/sync.md
@@ -0,0 +1 @@
+# Sync
diff --git a/book/src/usage/README.md b/book/src/usage/README.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Usage

		This section provides information on how to configure Dolos.