Merge pull request #1647 from emschwartz/main

docs: quickstart tweaks
tigerbeetle · Mar 5, 2024 · 1abf90b · 1abf90b
2 parents e3315ea + bb6ff3e
commit 1abf90b
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 63 deletions.
diff --git a/docs/intro.md b/docs/intro.md
@@ -10,14 +10,16 @@ for mission critical safety and performance.
 
 ## Quickstart
 
-First, get TigerBeetle running:
+First, let's get TigerBeetle running!
 
-- [Run a single-node cluster with a single binary](./quick-start/single-binary.md)
-- Or [run a three-node cluster with a single binary](./quick-start/single-binary-three.md)
-- Or [run a single-node cluster with Docker](./quick-start/with-docker.md)
-- Or [run a three-node cluster with docker-compose](./quick-start/with-docker-compose.md)
+* [Single-node cluster with a single binary](./quick-start/single-binary.md)
+* [Three-node cluster with a single binary](./quick-start/single-binary-three.md)
 
-Then, try creating accounts and transfers [using the TigerBeetle CLI](./quick-start/cli-repl.md).
+Or, you can run TigerBeetle with Docker:
+* [Single-node cluster with Docker](./quick-start/with-docker.md)
+* [Three-node cluster with Docker Compose](./quick-start/with-docker-compose.md)
+
+Then, let's [use the TigerBeetle CLI](./quick-start/cli-repl.md) to create accounts and transfers.
 
 ## Designing for TigerBeetle
 

diff --git a/docs/quick-start/README.md b/docs/quick-start/README.md
@@ -1,10 +1,12 @@
 # Quickstart
 
-First, get TigerBeetle running:
+First, let's get TigerBeetle running!
 
-* [Run a single-node cluster with a single binary](./single-binary.md)
-* Or [run a three-node cluster with a single binary](./single-binary-three.md)
-* Or [run a single-node cluster with Docker](./with-docker.md)
-* Or [run a three-node cluster with docker-compose](./with-docker-compose.md)
+* [Single-node cluster with a single binary](./single-binary.md)
+* [Three-node cluster with a single binary](./single-binary-three.md)
 
-Then, try creating accounts and transfers [using the TigerBeetle CLI](./cli-repl.md).
+Or, you can run TigerBeetle with Docker:
+* [Single-node cluster with Docker](./with-docker.md)
+* [Three-node cluster with Docker Compose](./with-docker-compose.md)
+
+Then, let's [use the TigerBeetle CLI](./cli-repl.md) to create accounts and transfers.
diff --git a/docs/quick-start/cli-repl.md b/docs/quick-start/cli-repl.md
@@ -1,18 +1,18 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
-# Creating accounts and transfers with the CLI repl
+# Use the CLI REPL to Create Accounts and Transfers
 
-Once you've got some TigerBeetle replicas running, let's connect to the
-replicas and do some accounting!
+Once you've got some TigerBeetle replicas running, let's connect to the replicas and do some
+accounting!
 
-First let's create two accounts. (Don't worry about the details, you
-can read about them later.)
+First let's create two accounts. (Don't worry about the details, you can read about them later.)
 
 ```console
 ./tigerbeetle repl --cluster=0 --addresses=3000
 ```
+
 ```
 TigerBeetle Client
   Hit enter after a semicolon to run a command.
@@ -24,10 +24,12 @@ Examples:
   lookup_accounts id=1;
   lookup_accounts id=1, id=2;
 ```
+
 ```console
 create_accounts id=1 code=10 ledger=700,
                 id=2 code=10 ledger=700;
 ```
+
 ```console
 info(message_bus): connected to replica 0
 ```
@@ -38,13 +40,13 @@ Now create a transfer of `10` (of some amount/currency) between the two accounts
 create_transfers id=1 debit_account_id=1 credit_account_id=2 amount=10 ledger=700 code=10;
 ```
 
-Now, the amount of `10` has been credited to account `2` and debited
-from account `1`. Let's query TigerBeetle for these two accounts to
-verify!
+Now, the amount of `10` has been credited to account `2` and debited from account `1`. Let's query
+TigerBeetle for these two accounts to verify!
 
 ```console
 lookup_accounts id=1, id=2;
 ```
+
 ```json
 {
   "id": "1",
@@ -70,6 +72,13 @@ lookup_accounts id=1, id=2;
 }
 ```
 
-And indeed you can see that account `1` has `debits_posted` as `10`
-and account `2` has `credits_posted` as `10`. The `10` amount is fully
-accounted for!
+And indeed you can see that account `1` has `debits_posted` as `10` and account `2` has
+`credits_posted` as `10`. The `10` amount is fully accounted for!
+
+You can take a look at the [`Accounts` reference](../reference/accounts.md) to understand all of the
+fields on the accounts.
+
+## Next: Designing for TigerBeetle
+
+Now that you've created some accounts and transfers, you may want to dig into the [data
+model](../design/data-modeling.md) to learn more about how to build with TigerBeetle.
diff --git a/docs/quick-start/single-binary-three.md b/docs/quick-start/single-binary-three.md
@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# Three-node cluster with a single binary
+# Three-Node Cluster
 
 First, download a prebuilt copy of TigerBeetle.
 
@@ -22,7 +22,7 @@ Want to build from source locally? Add `-build` as an argument to the bootstrap
 
 ## Running TigerBeetle
 
-Now create the TigerBeetle data file for each replica
+Now create the TigerBeetle [data file](../internals/data_file.md) for each replica:
 
 ```console
 ./tigerbeetle format --cluster=0 --replica=0 --replica-count=3 0_0.tigerbeetle
@@ -49,6 +49,5 @@ provided.
 
 ### Connect with the CLI
 
-Now you can connect to the running server with any client. For a quick
-start, try creating accounts and transfers [using the TigerBeetle CLI
-client](./cli-repl.md).
+Now you can connect to the running server with any client. For a quick start, try creating accounts
+and transfers [using the TigerBeetle CLI client](./cli-repl.md).
diff --git a/docs/quick-start/single-binary.md b/docs/quick-start/single-binary.md
@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# Single-node cluster with a single binary
+# Single-Node Cluster
 
 First, download a prebuilt copy of TigerBeetle.
 
@@ -22,28 +22,29 @@ Want to build from source locally? Add `-build` as an argument to the bootstrap
 
 ## Running TigerBeetle
 
-Now create the TigerBeetle data file.
+Now create the TigerBeetle [data file](../internals/data_file.md):
 
 ```console
 ./tigerbeetle format --cluster=0 --replica=0 --replica-count=1 0_0.tigerbeetle
 ```
+
 ```console
 info(io): creating "0_0.tigerbeetle"...
 info(io): allocating 660.140625MiB...
 ```
 
-And start the server.
+And start the server:
 
 ```console
 ./tigerbeetle start --addresses=3000 0_0.tigerbeetle
 ```
+
 ```console
 info(io): opening "0_0.tigerbeetle"...
 info(main): 0: cluster=0: listening on 127.0.0.1:3000
 ```
 
 ### Connect with the CLI
 
-Now you can connect to the running server with any client. For a quick
-start, try creating accounts and transfers [using the TigerBeetle CLI
-client](./cli-repl.md).
+Now you can connect to the running server with any client. For a quick start, try creating accounts
+and transfers [using the TigerBeetle CLI client](./cli-repl.md).
diff --git a/docs/quick-start/with-docker-compose.md b/docs/quick-start/with-docker-compose.md
@@ -2,9 +2,9 @@
 sidebar_position: 4
 ---
 
-# Three-node cluster with Docker Compose
+# Three-Node Cluster with Docker Compose
 
-First, provision the data file for each node:
+First, provision the [data file](../internals/data_file.md) for each node:
 
 ```console
 docker run -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster=0 --replica=0 --replica-count=3 /data/0_0.tigerbeetle
@@ -59,6 +59,7 @@ And run it:
 ```console
 docker-compose up
 ```
+
 ```console
 docker-compose up
 Starting tigerbeetle_0   ... done
@@ -86,14 +87,13 @@ tigerbeetle_1    | info(clock): 1: system time is 78ns ahead
 
 ### Connect with the CLI
 
-Now you can connect to the running server with any client. For a quick
-start, try creating accounts and transfers [using the TigerBeetle CLI
-client](./cli-repl.md).
+Now you can connect to the running server with any client. For a quick start, try creating accounts
+and transfers [using the TigerBeetle CLI client](./cli-repl.md).
 
 ## `error: SystemResources` on macOS
 
-If you get `error: SystemResources` when running TigerBeetle in Docker
-on macOS, you will need to add the `IPC_LOCK` capability.
+If you get `error: SystemResources` when running TigerBeetle in Docker on macOS, you will need to
+add the `IPC_LOCK` capability.
 
 ```yaml
 ... rest of docker-compose.yml ...
@@ -115,20 +115,17 @@ See https://github.com/tigerbeetle/tigerbeetle/issues/92 for discussion.
 
 ## `exited with code 137`
 
-If you see this error without any logs from TigerBeetle, it is likely
-that the Linux OOMKiller is killing the process. If you are running
-Docker inside a virtual machine (such as is required on Docker or
-Podman for macOS), try increasing the virtual machine memory limit.
+If you see this error without any logs from TigerBeetle, it is likely that the Linux OOMKiller is
+killing the process. If you are running Docker inside a virtual machine (such as is required on
+Docker or Podman for macOS), try increasing the virtual machine memory limit.
 
-Alternatively, in a development environment, you can lower the size of
-the cache so TigerBeetle uses less memory. For example, set
-`--cache-grid=512MB` when running `tigerbeetle start`.
+Alternatively, in a development environment, you can lower the size of the cache so TigerBeetle uses
+less memory. For example, set `--cache-grid=512MB` when running `tigerbeetle start`.
 
 ## Debugging panics
 
-If TigerBeetle panics and you can reproduce the panic, you can get a
-better stack trace by switching to a debug image (by using the `:debug`
-Docker image tag).
+If TigerBeetle panics and you can reproduce the panic, you can get a better stack trace by switching
+to a debug image (by using the `:debug` Docker image tag).
 
 ```bash
 ghcr.io/tigerbeetle/tigerbeetle:debug

diff --git a/docs/quick-start/with-docker.md b/docs/quick-start/with-docker.md
@@ -2,40 +2,41 @@
 sidebar_position: 3
 ---
 
-# Single-node cluster with Docker
+# Single-Node Cluster with Docker
 
-First provision TigerBeetle's data directory.
+First provision TigerBeetle's [data file](../internals/data_file.md):
 
 ```console
 docker run -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle \
     format --cluster=0 --replica=0 --replica-count=1 /data/0_0.tigerbeetle
 ```
+
 ```console
 info(io): creating "0_0.tigerbeetle"...
 info(io): allocating 660.140625MiB...
 ```
 
-Then run the server.
+Then run the server:
 
 ```console
 docker run -p 3000:3000 -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle \
     start --addresses=0.0.0.0:3000 /data/0_0.tigerbeetle
 ```
+
 ```console
 info(io): opening "0_0.tigerbeetle"...
 info(main): 0: cluster=0: listening on 0.0.0.0:3000
 ```
 
 ### Connect with the CLI
 
-Now you can connect to the running server with any client. For a quick
-start, try creating accounts and transfers [using the TigerBeetle CLI
-client](./cli-repl.md).
+Now you can connect to the running server with any client. For a quick start, try creating accounts
+and transfers [using the TigerBeetle CLI client](./cli-repl.md).
 
 ## `error: SystemResources` on macOS
 
-If you get `error: SystemResources` when running TigerBeetle in Docker
-on macOS, you will need to do one of the following:
+If you get `error: SystemResources` when running TigerBeetle in Docker on macOS, you will need to do
+one of the following:
 
 1. Run `docker run` with `--cap-add IPC_LOCK`
 2. Run `docker run` with `--ulimit memlock=-1:-1`
@@ -59,9 +60,8 @@ See https://github.com/tigerbeetle/tigerbeetle/issues/92 for discussion.
 
 ## Debugging panics
 
-If TigerBeetle panics and you can reproduce the panic, you can get a
-better stack trace by switching to a debug image (by using the `:debug`
-Docker image tag).
+If TigerBeetle panics and you can reproduce the panic, you can get a better stack trace by switching
+to a debug image (by using the `:debug` Docker image tag).
 
 ```console
 docker run -p 3000:3000 -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle:debug \