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.

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

Added docs folder at the project root. Added build_docs and publish_d… #105

Merged
merged 8 commits into from
Sep 10, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -74,4 +74,46 @@ jobs:
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true

build_docs:
name: Build docusaurus documentation
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: pnpm/action-setup@v4
name: Install pnpm
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 18
cache: pnpm
cache-dependency-path: ./docs/pnpm-lock.yaml
- name: Install dependencies
run: pnpm --prefix docs install
- name: Build website
run: pnpm --prefix docs run build
- name: Upload Build Artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/build

publish_docs:
name: Publish docusaurus docs to GitHub pages
needs: build_docs
permissions:
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source
environment:
# Deploy to the github-pages environment
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4


30 changes: 30 additions & 0 deletions .github/workflows/test-deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Test deployment

on:
pull_request:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
test_docs_deploy:
name: Test docusaurus documentation deployment
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: pnpm/action-setup@v4
name: Install pnpm
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 18
cache: pnpm
cache-dependency-path: docs/pnpm-lock.yaml
- name: Install dependencies
run: pnpm --prefix docs install
- name: Test build website
run: pnpm --prefix docs run build
21 changes: 21 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader
.next

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
1 change: 1 addition & 0 deletions docs/CNAME
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
echovault.io
3 changes: 3 additions & 0 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
5 changes: 5 additions & 0 deletions docs/blog/authors.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
kelvinmwinuka:
name: Kelvin Clement Mwinuka
title: EchoVault Maintainer
url: https://kelvinmwinuka.com
image_url: https://github.com/kelvinmwinuka.png
199 changes: 199 additions & 0 deletions docs/docs/acl.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
---
sidebar_position: 7
---

# Access Control List

Access Control Lists enable you to add a layer of security to the EchoVault server or cluster. You can create users with associated rules and require clients to authorize before executing commands on the server.

EchoVault creates a default user upon startup. You can see this user by executing the following command:

```
> ACL LIST
1) "default on +@all +all %RW~* +&*"
```

The default user is enabled, and has access to all categories, commands, keys and pub/sub channels. Connections are associated with user by default.

You can configure the default user to require a passwords by using the following configuration options:

- `--require-pass` forces the EchoVault server to require a user to authenticate itself using a password and/or username.

- `--password` attaches the provided password to the default user.

## Authorization

The TCP client can authenticate itself using the `AUTH` command:

`AUTH <username> <password>` tries to authenticate the TCP connection with the provided username and password.

`AUTH <password>` tries to authenticate the TCP connection with the default user and the provided passsword.

Authorization is not supported in embedded mode. When an EchoVault instance is embedded, it autimatically has access to all the commands exposed by the API.

## Configuration files

You can configure ACL Rules by passing the path to the config file to the `--acl-config=<path/to/config/file>` flag. The configuration file can be either a YAML or JSON file.

### YAML Config example

```yaml
- Username: "user1"
Enabled: true
NoPassword: false
NoKeys: false
Passwords:
- PasswordType: "plaintext"
PasswordValue: "password1"
- PasswordType: "SHA256"
PasswordValue: "6cf615d5bcaac778352a8f1f3360d23f02f34ec182e259897fd6ce485d7870d4"
IncludedCategories: ["*"]
ExcludedCategories: []
IncludedReadKeys: ["*"]
IncludedWriteKeys: ["*"]
IncludedPubSubChannels: ["*"]
ExcludedPubSubChannels: []

- Username: "user2"
Enabled: true
NoPassword: false
NoKeys: false
Passwords:
- PasswordType: "plaintext"
PasswordValue: "password4"
- PasswordType: "SHA256"
PasswordValue: "8b2c86ea9cf2ea4eb517fd1e06b74f399e7fec0fef92e3b482a6cf2e2b092023"
IncludedCategories: ["hash", "set", "sortedset", "list", "generic"]
ExcludedCategories: []
IncludedReadKeys: ["*"]
IncludedWriteKeys: ["*"]
IncludedPubSubChannels: ["user:channel:*"]
ExcludedPubSubChannels: ["admin:channel:*"]
```

### JSON Config example

```json
[
{
"Username": "user1",
"Enabled": true,
"NoPassword": false,
"NoKeys": false,
"Passwords": [
{
"PasswordType": "plaintext",
"PasswordValue": "password1"
},
{
"PasswordType": "SHA256",
"PasswordValue": "6cf615d5bcaac778352a8f1f3360d23f02f34ec182e259897fd6ce485d7870d4"
}
],
"IncludedCategories": ["*"],
"ExcludedCategories": [],
"IncludedReadKeys": ["*"],
"IncludedWriteKeys": ["*"],
"IncludedPubSubChannels": ["*"],
"ExcludedPubSubChannels": []
},
{
"Username": "user2",
"Enabled": true,
"NoPassword": false,
"NoKeys": false,
"Passwords": [
{
"PasswordType": "plaintext",
"PasswordValue": "password4"
},
{
"PasswordType": "SHA256",
"PasswordValue": "8b2c86ea9cf2ea4eb517fd1e06b74f399e7fec0fef92e3b482a6cf2e2b092023"
}
],
"IncludedCategories": ["hash", "set", "sortedset", "list", "generic"],
"ExcludedCategories": [],
"IncludedReadKeys": ["*"],
"IncludedWriteKeys": ["*"],
"IncludedPubSubChannels": ["user:channel:*"],
"ExcludedPubSubChannels": ["admin:channel:*"]
}
]
```

## ACL rules

ACL rules allow you to add new user profiles and set fine-grained rules that determine what clients can do on the server.

The default user's rules are very permissive so if you want to restrict access, you will have to explicitly configure ACL rules. The default user can be configured too.

### Enable and disable users

- `on` - Enable this user. A TCP connection can authenticate as this user.
- `off` - Disable this user. It's impossible to authenticate as thsi user.

### Allow and disallow categories

- `+@all` - Allow this user to access all categories (aliased by `allCategories` and `+@*`). This overrides all other category access rules.
- `-@all` - Block this user from accessing any categories (aliased by `-@*`, and `nocommands`). This overrides all other category access rules.
- `+@<category>` - Allow this user to access the specified category. If updating an existing user, then this category will be added to the list of categories they are allowed to access.
- `-@<category>` - Block the user from accessing this specific category. If updating an existing user, then this category is removed from the list of categories the user is allowed to access.

If both `+@all` and `-@all` are specified, whichever one is specified last will take effect.

The `nocommands` flag will apply the `-@all` rule.

### Allow and disallow commands

- `+all` - Allow this user to execute all commands (aliased by `allCommands`). This overrides all other command access rules.
- `-all` - Block this user from executing any commands. This overrides all other command access rules.
- `+<command>` - Allow the user to access the specified command. In order to allow the user to access only a specific subcommand, you can use `+<command>|<subcommand>`.
- `-<command>` - Block this user from executing any commands. In order to allow the user to access only a specific subscommand, you can user `-<command>|<subcommand>`.

If both `+all` and `-all` are specified, whichever one is specified last will take effect.

The `nocommands` flag will apply the `-all` rule.

### Allow and disallow access to keys

By default, EchoVault allows each user to read and write to all keys. If you'd like to control what keys users have access to and what they can do with those keys, you can make use of the following options:

- `%RW~*` - Allow this user to read and write all keys on the EchoVault isntance (aliased by `allKeys`).
- `%RW~<key>` - Allow this user to read and write to the specified key. This option accepts a glob pattern for the key which allows you to restrict certain key patterns.
- `%W~*` - Allow the user to write to all keys.
- `%W~<key>` - Block the user from writing to any keys except the one specified. A glob pattern can be used in place of the key.
- `%R~*` - Allow the user to read from all the keys.
- `%R~<key>` - Block the user from reading any keys except the one specified. A glob pattern can be used in place of the key.

### Allow and disallow Pub/Sub channels

- `+&*` - Allow this user to access all pub/sub channels (aliased by `allChannels`).
- `-&*` - Block this user from accessing any of the pub/sub channels.
- `+&<channel>` - Allow this user to access the specied channel. This rule accepts a glob pattern (e.g. "channel\*").
- `-&<channel>` - Block this user from accessing the specied channel. This rule accepts a glob pattern (e.g. "channel\*").

If both `+&*` and `-&*` are specified, the one specified last will take effect.

### Add and remove passwords

By default users have no password and require no password to authenticate against them except when the `--require-pass` configuration is `true`. You can add and remove passwords associated with a user using the following options:

- `><password>` - Adds the plaintext password to the list of passwords associated with the user.
- `<<password>` - Removes the plaintext password from the list of passwords associated with the user.
- `#<hash>` - Adds the hash to the list of passwords associated with the user. The hash must be a SHA256 hash. When the user is being authenticated, they provide a plaintext passwords and the passwords will be compared with the user's plaintext passwords. If no match is found, the password's SHA256 hash is compared with the list of password hashes associated with the user.
- `!<hash>` - Removes the SHA256 hash from the list of passwords hashes associated with the user.

### Reset the user

You can pass certain flags to make sweeping updates to a user's ACL rules. These flags often reset the granular rules specified above.

- `nopass` - Deletes all the user's associated passwords. Future TCP connections will not need to provide a password to authenticate against this user.
- `resetpass` - Deletes all the user's associated passwords, but does not set the `nopass` flag to true.
- `nocommands` - Blocks the user from executing any commands.
- `resetkeys` - Blocks the user from accesssing any keys for both reads and writes (aliased by `nokeys`).
- `resetchannels` - Allows the user to access all pub/sub channels.

## Examples

For examples on how to create and update ACL users and their rules, checkout out the `ACL SETUSER` command documentation.
11 changes: 11 additions & 0 deletions docs/docs/architecture/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
sidebar_position: 6
---

# Architecture

EchoVault can be run in the following modes:

- Standalone mode - Where only one instance runs in isolation.
- Replication cluster - Strongly consistent RAFT cluster.
- Sharding - To be implemented.
59 changes: 59 additions & 0 deletions docs/docs/commands/acl/acl_cat.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# ACL CAT

### Syntax
```
ACL CAT [category]
```

### Module
<span className="acl-category">acl</span>

### Categories
<span className="acl-category">slow</span>

### Description
Lists all the categories. If the optional category is provided, lists all the commands in the category.

### Examples

<Tabs
defaultValue="go"
values={[
{ label: 'Go (Embedded)', value: 'go', },
{ label: 'CLI', value: 'cli', },
]}
>
<TabItem value="go">
List all categories:
```go
vault, err := echovault.NewEchoVault()
if err != nil {
log.Fatal(err)
}
categories, err := vault.ACLCat()
```

List all commands/subcommands in pubsub module:
```go
vault, err := echovault.NewEchoVault()
if err != nil {
log.Fatal(err)
}
commands, err := vault.ACLCat("pubsub")
```
</TabItem>
<TabItem value="cli">
List all categories:
```
> ACL CAT
```

List all commands/subcommands in pubsub module:
```
> ACL CAT pubsub
```
</TabItem>
</Tabs>
Loading