Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: quickstart tweaks #1647

Merged
merged 6 commits into from Mar 5, 2024
Merged

docs: quickstart tweaks #1647

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ce9f1f8
docs: tidy up quickstart links
emschwartz Mar 4, 2024
0536025
docs: point users to data modeling after repl quickstart
emschwartz Mar 4, 2024
ded2d03
docs: link to internals doc about data file
emschwartz Mar 4, 2024
36c1e33
docs: wrap lines to 100 characters
emschwartz Mar 5, 2024
c0d2388
docs: fix broken links
emschwartz Mar 5, 2024
bb6ff3e
docs: actually fix broken links
emschwartz Mar 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
14 changes: 8 additions & 6 deletions docs/intro.md
View file
Open in desktop
Expand Up @@ -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

Expand Down
14 changes: 8 additions & 6 deletions docs/quick-start/README.md
View file
Open in desktop
@@ -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.
33 changes: 21 additions & 12 deletions docs/quick-start/cli-repl.md
View file
Open in desktop
@@ -1,18 +1,18 @@
---
sidebar_position: 4
emschwartz marked this conversation as resolved.
Show resolved Hide resolved
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.
Expand All @@ -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
```
Expand All @@ -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",
Expand All @@ -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.
9 changes: 4 additions & 5 deletions docs/quick-start/single-binary-three.md
View file
Open in desktop
Expand Up @@ -2,7 +2,7 @@
sidebar_position: 2
---

# Three-node cluster with a single binary
# Three-Node Cluster

First, download a prebuilt copy of TigerBeetle.

Expand All @@ -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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure whether we should be linking internal docs from public docs --- they aren't really written for normal users to understand.

I think it's fine to do that, but we need to make sure that any internal doc that we link in this way starts with the disclaimer that "you don't need to read this to use TB".

I guess the first-best solution would be to create some kind of glossary entry for the "data file" in the public docs, and, from that entry, to link to internals.

No need to do anything for this PR though, I think linking is better that not linking at all!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of linking like this, we could have an extra sentence that says "(If you are curious, you can learn more about the contents of the data file in the internals doc)"


```console
./tigerbeetle format --cluster=0 --replica=0 --replica-count=3 0_0.tigerbeetle
Expand All @@ -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).
13 changes: 7 additions & 6 deletions docs/quick-start/single-binary.md
View file
Open in desktop
Expand Up @@ -2,7 +2,7 @@
sidebar_position: 1
---

# Single-node cluster with a single binary
# Single-Node Cluster

First, download a prebuilt copy of TigerBeetle.

Expand All @@ -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).
31 changes: 14 additions & 17 deletions docs/quick-start/with-docker-compose.md
View file
Open in desktop
Expand Up @@ -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
Expand Down Expand Up @@ -59,6 +59,7 @@ And run it:
```console
docker-compose up
```

```console
docker-compose up
Starting tigerbeetle_0 ... done
Expand Down Expand Up @@ -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 ...
Expand All @@ -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
Expand Down
22 changes: 11 additions & 11 deletions docs/quick-start/with-docker.md
View file
Open in desktop
Expand Up @@ -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:
emschwartz marked this conversation as resolved.
Show resolved Hide resolved

```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`
Expand All @@ -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 \
Expand Down