Skip to content

Commit 8b2874b

Browse files
phughkphughk
authored
Merge pull request #12 from rapidrecast/docs-update-0.2.0
Add some docs
2 parents 95d1139 + 5acabe2 commit 8b2874b

24 files changed

+516
-64
lines changed

‎content/docs/_index.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,5 @@ seo:
1414
noindex: false # false (default) or true
1515
---
1616

17-
Index of docs.
17+
Bear with me while I set up branding and then format this better.
18+

‎content/docs/guides/_index.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Guides"
3-
description: ""
3+
description: "Guides for how to achieve common tasks"
44
summary: ""
55
date: 2023-09-07T16:06:50+02:00
66
lastmod: 2023-09-07T16:06:50+02:00
@@ -14,4 +14,6 @@ seo:
1414
noindex: false # false (default) or true
1515
---
1616

17-
Index of the guides.
17+
Guides lead you through a specific task you want to accomplish.
18+
19+
If there is a guide you would like, please open a ticket on the [repository](https://github.com/rapidrecast/www.rapidrecast.io/issues/new).

‎content/docs/guides/example.md

-17
This file was deleted.

‎content/docs/guides/launching.md

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "Launching RapidRecast"
3+
description: "How you can launch RapidRecast and the options available."
4+
summary: ""
5+
date: 2023-09-07T16:04:48+02:00
6+
lastmod: 2023-09-07T16:04:48+02:00
7+
draft: false
8+
weight: 810
9+
toc: true
10+
seo:
11+
title: "" # custom title (optional)
12+
description: "" # custom description (recommended)
13+
canonical: "" # custom canonical URL (optional)
14+
noindex: false # false (default) or true
15+
---
16+
17+
# Downloading RapidRecast
18+
19+
Pick up the latest release from the [Releases Page](http://localhost:1313/releases/).
20+
21+
Download for the appropriate platform from the table at the bottom of the release page.
22+
23+
Unpack wherever is convenient for you, for example `~/local/bin`.
24+
25+
# Starting RapidRecast
26+
27+
Once you have downloaded and unpacked RapidRecast, you should be able to run it immediately with this command.
28+
29+
```bash
30+
# (Optional) configure logging
31+
export RUST_LOG=rapidrecast=trace,info
32+
# Start RapidRecast
33+
rapidrecast -p 0.0.0.0:0 -a 127.0.0.1:0
34+
```
35+
36+
The above command creates an HTTP protocol and an Admin API on any available port.
37+
The `0.0.0.0` binding means that it is accessible on any network interface (such as the internet, if the firewall allows it).
38+
We do not want the Admin API accessible from anyone outside our computer though - so we have set the bind to be `127.0.0.1`.
39+
Only you can access it from your computer that way.
40+
41+
Exposing the Admin API to the internet is considered safe, assuming the login credentials are secure.
42+
43+
# Protocols available
44+
45+
RapidRecast exposes protocols on CLI provided ports.
46+
47+
## Admin Protocol
48+
49+
RapidRecast provides a way to remotely configure its behaviour and state.
50+
51+
To make the Admin Protocol available, you provide the CLI with the `-a` or `--admin-bind` parameter.
52+
53+
For example `rapidrecast -a 127.0.0.1:8080` will make the admin protocol available on port 8080 on your computer only, but not to outside networks.
54+
55+
## Service Protocols
56+
57+
**Service Protocols** are the protocols that users of the service interact with.
58+
They are entirely programmable from the admin API and console.
59+
60+
In the current latest release the available protocols are:
61+
62+
| Protocol | CLI args | Example |
63+
|----------|--------------------------------------|------------------|
64+
| HTTP 1.1 | `-p <bind>` and `--http-bind <bind>` | `-p 127.0.0.1:0` |
65+
66+
67+
# Admin credentials
68+
69+
To access the admin API, you need to use admin credentials.
70+
71+
In the early days of RapidRecast, the admin credentials are hardcoded to `admin` and `admin-password`.
72+
73+
Once logged in as an admin, you can create users and roles fitting the permissions you would like to use.
74+
75+
To read more about Policies and Roles, see the [RBAC Guide]({{< ref "/docs/guides/rbac.md" >}}).

‎content/docs/guides/rbac.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: "Role-Based Access Control (RBAC)"
3+
description: "How the Authorization system works in RapidRecast."
4+
summary: ""
5+
date: 2023-09-07T16:04:48+02:00
6+
lastmod: 2023-09-07T16:04:48+02:00
7+
draft: false
8+
weight: 810
9+
toc: true
10+
seo:
11+
title: "" # custom title (optional)
12+
description: "" # custom description (recommended)
13+
canonical: "" # custom canonical URL (optional)
14+
noindex: false # false (default) or true
15+
---
16+
17+
# Role-Based Access Control (RBAC)
18+
19+
20+
Role-Based Access Control (RBAC) is a method of restricting what users can do on your system.
21+
22+
The general idea is that every time you do something, you are acting as a Subject (User or Role).
23+
When you are acting as a Subject, you are acting on some resource; this is the Object.
24+
Finally, there is a definition of what you are trying to do with the Object. This is the Action.
25+
26+
## What are Policies and Subject-Object-Action?
27+
28+
RBAC is a system of handling permissions where you define Policies.
29+
A Policy is a 3-tuple of Subject, Object, and Action.
30+
31+
As a _hypothetical_ example, this is how you would allow Hugh to Write to Topic1:
32+
33+
```
34+
Hugh, Topic1, Write
35+
```
36+
37+
The above is completely incorrect syntax, but it highlights the idea of the RBAC system in place.
38+
39+
To revoke permission, you would remove the Policy.
40+
A user is given permission if any single policy affecting them (or their roles) allows it.
41+
42+
## What are Roles?
43+
44+
A Role is a Subject, just like a User.
45+
46+
In the existing implementation of RapidRecast, there is no difference between Roles and Users.
47+
That means Users can belong to other Users and inherit the same permissions.
48+
Under such circumstances, if Users remain in the system after the parent User is deleted, the parent User effectively becomes a Role.
49+
The Role can be renamed.
50+
51+
### Pre-defined Roles in RapidRecast
52+
53+
There are 2 Users that are pre-defined in RapidRecast:
54+
- `admin`
55+
- `anon`
56+
57+
The password for `admin` is `admin-password`.
58+
59+
The `anon` account is not allowed to have a password.
60+
61+
### Existing Objects
62+
63+
The full Objects list can be found in the [RBAC Reference]({{< ref "/docs/reference/rbac/_index.md#objects" >}}).
64+
65+
### Existing Actions
66+
67+
The full Actions list can be found in the [RBAC Reference]({{< ref "/docs/reference/rbac/_index.md#actions" >}}).
68+
69+
### Defining a Policy
70+
71+
You can define a policy using the policy API.
72+
73+

‎content/docs/reference/_index.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: "Reference"
3-
description: ""
2+
title: "Product Reference"
3+
description: "The Product Reference is the primary documentation where you should find everything you want"
44
summary: ""
55
date: 2023-09-07T16:12:37+02:00
66
lastmod: 2023-09-07T16:12:37+02:00
@@ -12,6 +12,6 @@ sidebar:
1212
seo:
1313
title: "" # custom title (optional)
1414
description: "" # custom description (recommended)
15-
canonical: "" # custom canonical URL (optional)
15+
canonical: "ref" # custom canonical URL (optional)
1616
noindex: false # false (default) or true
1717
---

‎content/docs/reference/api/_index.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: "Admin API Reference"
3+
description: "The Admin API is used to configure and manage RapidRecast"
4+
summary: ""
5+
date: 2023-09-07T16:12:37+02:00
6+
lastmod: 2023-09-07T16:12:37+02:00
7+
draft: false
8+
weight: 900
9+
toc: true
10+
sidebar:
11+
collapsed: true
12+
seo:
13+
title: "" # custom title (optional)
14+
description: "" # custom description (recommended)
15+
canonical: "" # custom canonical URL (optional)
16+
noindex: false # false (default) or true
17+
---
18+
19+
The API endpoints are available on the admin protocol.
20+

‎content/docs/reference/api/auth.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Auth"
3+
description: "Auth endpoint handles"
4+
summary: ""
5+
date: 2023-09-07T16:12:37+02:00
6+
lastmod: 2023-09-07T16:12:37+02:00
7+
draft: false
8+
weight: 900
9+
toc: true
10+
sidebar:
11+
collapsed: true
12+
seo:
13+
title: "" # custom title (optional)
14+
description: "" # custom description (recommended)
15+
canonical: "" # custom canonical URL (optional)
16+
noindex: false # false (default) or true
17+
---
18+
19+
| Method | Path | Description | Body |
20+
| --- |---------------------|--------------------------------------------------|------|
21+
| `POST` | `/api/v1/auth` | Generate a JWT token from HTTP Basic Auth header | None |
22+
23+
{{< interactive/curl-auth interactive-id >}}

‎content/docs/reference/api/policy.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Policy"
3+
description: "Policy endpoint handles"
4+
summary: ""
5+
date: 2023-09-07T16:12:37+02:00
6+
lastmod: 2023-09-07T16:12:37+02:00
7+
draft: false
8+
weight: 900
9+
toc: true
10+
sidebar:
11+
collapsed: true
12+
seo:
13+
title: "" # custom title (optional)
14+
description: "" # custom description (recommended)
15+
canonical: "" # custom canonical URL (optional)
16+
noindex: false # false (default) or true
17+
---
18+
19+
| Method | Path | Description | Request Body | Response Body |
20+
|--------|------------------|--------------------------------------------------|---------------|----------------|
21+
| `POST` | `/api/v1/policy` | Generate a JWT token from HTTP Basic Auth header | PolicyRequest | PolicyResponse |
22+
23+

‎content/docs/reference/cli.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: "CLI Reference"
3+
description: "The Command Line Interface reference covers all things to do with the binary."
4+
summary: ""
5+
date: 2023-09-07T16:12:37+02:00
6+
lastmod: 2023-09-07T16:12:37+02:00
7+
draft: false
8+
weight: 900
9+
toc: true
10+
sidebar:
11+
collapsed: true
12+
seo:
13+
title: "" # custom title (optional)
14+
description: "" # custom description (recommended)
15+
canonical: "" # custom canonical URL (optional)
16+
noindex: false # false (default) or true
17+
---

‎content/docs/reference/console/_index.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: "Admin Console Reference"
3+
description: "The Admin Console is the user interface for managing RapidRecast"
4+
summary: ""
5+
date: 2023-09-07T16:12:37+02:00
6+
lastmod: 2023-09-07T16:12:37+02:00
7+
draft: false
8+
weight: 900
9+
toc: true
10+
sidebar:
11+
collapsed: true
12+
seo:
13+
title: "" # custom title (optional)
14+
description: "" # custom description (recommended)
15+
canonical: "" # custom canonical URL (optional)
16+
noindex: false # false (default) or true
17+
---
18+
19+
Admin Console text.
20+
21+
You can access the console with the credentials `admin` and `admin-password`.
22+
This is conveniently provided through [this link](http://admin:[email protected]).

‎content/docs/reference/example.md

-21
This file was deleted.

‎content/docs/reference/rbac/_index.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "RBAC Reference"
3+
description: "Role-Based Access Control (RBAC) covers all the concepts related to permissions within RapidRecast."
4+
summary: ""
5+
date: 2023-09-07T16:12:37+02:00
6+
lastmod: 2023-09-07T16:12:37+02:00
7+
draft: false
8+
weight: 900
9+
toc: true
10+
sidebar:
11+
collapsed: true
12+
seo:
13+
title: "" # custom title (optional)
14+
description: "" # custom description (recommended)
15+
canonical: "" # custom canonical URL (optional)
16+
noindex: false # false (default) or true
17+
---
18+
19+
See the [RBAC Guide]({{< ref "/docs/guides/rbac.md" >}}) for a more detailed explanation of RBAC in RapidRecast.
20+
21+
# Subjects
22+
23+
# Objects
24+
25+
The following Objects can be used in Policies:
26+
27+
| Object | Description |
28+
|----------------------------------------|-------------------------------------------------|
29+
| `topic-any:default-namespace` | Any topic that can be pushed and consumed from. |
30+
| `topic:default-namespace:<topic-name>` | A specific topic by name. |
31+
32+
# Actions
33+
34+
The following Actions can be used in Policies:
35+
- `Create`, whenever a resource is being created
36+
- `Update`, whenever a resource is being updated
37+
- `Delete`, whenever a resource is being deleted
38+
- `List`, whenever metadata about a resource is being listed
39+
- `Read`, whenever a resource is being read from
40+
- `Write`, whenever a resource is being written to

0 commit comments

Comments
 (0)