From 97b9f5541dd13eca246e21bf17f42999e31822e5 Mon Sep 17 00:00:00 2001 From: Santiago Carmuega Date: Thu, 19 Oct 2023 17:18:24 -0300 Subject: [PATCH] docs: improve documentation outline (#121) --- book/src/SUMMARY.md | 16 +++++++++-- book/src/api/README.md | 1 + .../{usage/client_endpoint.md => api/grpc.md} | 27 ++----------------- book/src/api/ouroboros.md | 1 + book/src/configuration/README.md | 3 +++ book/src/configuration/byron.md | 6 +++++ book/src/configuration/examples.md | 22 +++++++++++++++ book/src/configuration/logging.md | 6 +++++ book/src/configuration/rolldb.md | 7 +++++ book/src/configuration/serve.md | 6 +++++ book/src/configuration/upstream.md | 7 +++++ book/src/installation/binary_release.md | 21 +++------------ book/src/installation/docker.md | 10 +++++-- book/src/running/README.md | 5 ++++ book/src/running/daemon.md | 9 +++++++ book/src/running/serve.md | 9 +++++++ book/src/running/sync.md | 1 + book/src/usage/README.md | 3 --- 18 files changed, 111 insertions(+), 49 deletions(-) create mode 100644 book/src/api/README.md rename book/src/{usage/client_endpoint.md => api/grpc.md} (62%) create mode 100644 book/src/api/ouroboros.md create mode 100644 book/src/configuration/README.md create mode 100644 book/src/configuration/byron.md create mode 100644 book/src/configuration/examples.md create mode 100644 book/src/configuration/logging.md create mode 100644 book/src/configuration/rolldb.md create mode 100644 book/src/configuration/serve.md create mode 100644 book/src/configuration/upstream.md create mode 100644 book/src/running/README.md create mode 100644 book/src/running/daemon.md create mode 100644 book/src/running/serve.md create mode 100644 book/src/running/sync.md delete mode 100644 book/src/usage/README.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 4d879085..2f83718a 100644 --- 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) \ No newline at end of file diff --git a/book/src/api/README.md b/book/src/api/README.md new file mode 100644 index 00000000..59327929 --- /dev/null +++ b/book/src/api/README.md @@ -0,0 +1 @@ +# API diff --git a/book/src/usage/client_endpoint.md b/book/src/api/grpc.md similarity index 62% rename from book/src/usage/client_endpoint.md rename to book/src/api/grpc.md index 838a13a6..b88a9f06 100644 --- a/book/src/usage/client_endpoint.md +++ b/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 new file mode 100644 index 00000000..ac589b60 --- /dev/null +++ b/book/src/api/ouroboros.md @@ -0,0 +1 @@ +# Ouroboros diff --git a/book/src/configuration/README.md b/book/src/configuration/README.md new file mode 100644 index 00000000..4ca65de9 --- /dev/null +++ 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 new file mode 100644 index 00000000..034f15b5 --- /dev/null +++ b/book/src/configuration/byron.md @@ -0,0 +1,6 @@ +# Byron + +```toml +[byron] +path = "./byron.json" +``` \ No newline at end of file diff --git a/book/src/configuration/examples.md b/book/src/configuration/examples.md new file mode 100644 index 00000000..1a589db3 --- /dev/null +++ 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" +``` \ No newline at end of file diff --git a/book/src/configuration/logging.md b/book/src/configuration/logging.md new file mode 100644 index 00000000..51ce23a9 --- /dev/null +++ b/book/src/configuration/logging.md @@ -0,0 +1,6 @@ +# Logging + +```toml +[logging] +max_level = "debug" +``` \ No newline at end of file diff --git a/book/src/configuration/rolldb.md b/book/src/configuration/rolldb.md new file mode 100644 index 00000000..2a0a90bd --- /dev/null +++ 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 new file mode 100644 index 00000000..2e4d56c6 --- /dev/null +++ b/book/src/configuration/serve.md @@ -0,0 +1,6 @@ +# Serve + +```toml +[serve.grpc] +listen_address = "[::]:50051" +``` \ No newline at end of file diff --git a/book/src/configuration/upstream.md b/book/src/configuration/upstream.md new file mode 100644 index 00000000..7d89cba7 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/book/src/installation/binary_release.md b/book/src/installation/binary_release.md index 651846a6..8c177a7a 100644 --- 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 index ebe94ef5..5bbefed0 100644 --- 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. \ No newline at end of file diff --git a/book/src/running/README.md b/book/src/running/README.md new file mode 100644 index 00000000..ec22ed04 --- /dev/null +++ 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 new file mode 100644 index 00000000..f6228745 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/book/src/running/serve.md b/book/src/running/serve.md new file mode 100644 index 00000000..23af11cf --- /dev/null +++ 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 new file mode 100644 index 00000000..bc4491e8 --- /dev/null +++ b/book/src/running/sync.md @@ -0,0 +1 @@ +# Sync diff --git a/book/src/usage/README.md b/book/src/usage/README.md deleted file mode 100644 index c33a5040..00000000 --- a/book/src/usage/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Usage - -This section provides information on how to use Dolos. \ No newline at end of file