Skip to content

NOISSUE - Update documentation for Atom and plugin provisioning steps #41

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

Merged
rodneyosodo merged 3 commits into from
Jul 21, 2026
Merged

NOISSUE - Update documentation for Atom and plugin provisioning steps #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
506d3ad
docs: replace Magistrala with Atom and update related docs
rodneyosodo Jul 6, 2026
0e8ed3f
docs: use tenant/entity/api-key terminology and add plugin docs
rodneyosodo Jul 21, 2026
4c344b8
docs: add proxy provisioning steps, tweak examples and defaults
rodneyosodo Jul 21, 2026
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
11 changes: 9 additions & 2 deletions content/docs/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,16 @@ Proplet includes a built-in process monitoring subsystem for observing task and

The Proxy service handles downloading and distributing WebAssembly modules from OCI registries and distributes them to proplets.

### Atom
### Plugin System

Propeller includes two independent WebAssembly plugin systems that extend behaviour at runtime without recompiling core binaries:

- **Manager Plugins**: Written with [`propeller-plugin-sdk`](https://github.com/absmach/propeller/tree/main/crates/propeller-plugin-sdk) (Rust, compiled to `wasm32-wasip1`). Plugins intercept task operations (authorize, enrich, on_before_proplet_select, on_before_dispatch, on_task_start, on_task_complete) before they reach the scheduler.
- **Proplet Plugins**: Written with [`propeller-proplet-plugin-sdk`](https://github.com/absmach/propeller/tree/main/crates/propeller-proplet-plugin-sdk) (Rust, WIT component model). Plugins intercept tasks on the edge node just before execution.

[Atom](https://github.com/absmach/atom) is an open-source identity and authorization platform that provides entity management, tenant isolation, access policies, and API key management.
Both plugin types run inside a sandboxed Wasmtime instance with WASI. See the [Plugins](/plugins) documentation for details.

### Atom

It uses [FluxMQ](https://github.com/absmach/fluxmq) as its message broker and provides a GraphQL API for managing:

Expand Down
45 changes: 27 additions & 18 deletions content/docs/developer-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,23 @@ make addition

This compiles the example to WebAssembly format. The compiled `.wasm` file is located in the `build` directory.

### Building the Plugin SDK Crates

Propeller includes two Rust crate SDKs for extending behaviour via WebAssembly plugins:

- `crates/propeller-plugin-sdk` — SDK for writing Manager plugins
- `crates/propeller-proplet-plugin-sdk` — SDK for writing Proplet plugins

Build both with:

```bash
cargo build --release --workspace --manifest-path crates/Cargo.toml
```

For authoring plugins, see the [Plugins](/plugins) documentation and the [plugin-auth](https://github.com/absmach/propeller/tree/main/examples/plugin-auth) and [proplet-plugin-example](https://github.com/absmach/propeller/tree/main/examples/proplet-plugin-example) examples.

### Testing Examples

To test the compiled Wasm example locally with Wasmtime (requires Wasmtime installed):

```bash
Expand Down Expand Up @@ -336,24 +353,16 @@ Example output:

```bash
docker compose -f docker/compose.yaml --env-file docker/.env up -d
[+] Running 17/17
✔ Container atom-db Started 2.5s
✔ Container atom-redis Started 2.1s
✔ Container atom-jaeger Started 3.0s
✔ Container atom-http Started 5.1s
✔ Container atom-grpc Started 5.2s
✔ Container atom-domains-db Started 2.8s
✔ Container atom-domains Started 5.0s
✔ Container atom-policies-db Started 3.0s
✔ Container atom-policies Started 5.4s
✔ Container atom-tokens Started 5.3s
✔ Container atom-providers Started 5.6s
✔ Container fluxmq-node1 Started 5.9s
✔ Container fluxmq-node2 Started 6.1s
✔ Container fluxmq-node3 Started 6.0s
✔ Container fluxmq-auth Started 5.5s
✔ Container base-net Created 0.1s
✔ Container nginx Started 6.5s
[+] Running 9/9
✔ Network propeller-base-net Created 0.1s
✔ Volume propeller-atom-db-volume Created 0.1s
✔ Volume propeller-fluxmq-node1-volume Created 0.1s
✔ Container propeller-atom-db Started 2.5s
✔ Container propeller-atom Started 5.1s
✔ Container propeller-atom-ui Started 5.3s
✔ Container propeller-fluxmq-auth Started 5.5s
✔ Container propeller-fluxmq-node1 Started 5.9s
✔ Container propeller-nginx Started 6.5s
```

- Docker must be installed and running
Expand Down
33 changes: 24 additions & 9 deletions content/docs/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ This guide walks you through installing Propeller and running your first WASM wo

## Prerequisites

| Tool | Version | Purpose |
| ------------------------------------------ | ------- | ---------------------------- |
| [Go](https://go.dev/doc/install) | 1.26.0+ | Building Propeller binaries |
| [Rust](https://rustup.rs/) | Latest | Building the proplet runtime |
| [Docker](https://docs.docker.com/) | 20.10+ | Running base services (Atom, FluxMQ) |
| [Make](https://www.gnu.org/software/make/) | 3.81+ | Build automation |
| [Mosquitto Tools](https://mosquitto.org/) | Latest | MQTT CLI utilities |
| Tool | Version | Purpose |
| ------------------------------------------ | ------- | ------------------------------------ |
| [Go](https://go.dev/doc/install) | 1.26.0+ | Building Propeller binaries |
| [Rust](https://rustup.rs/) | Latest | Building the proplet runtime |
| [Docker](https://docs.docker.com/) | 20.10+ | Running base services (Atom, FluxMQ) |
| [Make](https://www.gnu.org/software/make/) | 3.81+ | Build automation |
| [Mosquitto Tools](https://mosquitto.org/) | Latest | MQTT CLI utilities |

These are only needed if you plan to build WASM modules locally:

Expand Down Expand Up @@ -200,8 +200,8 @@ channel_id = "8c6e1e6c-fc89-43b4-b00b-884a690c7419"

[proxy]
tenant_id = "182c0907-002c-4bfd-8bf3-e4f40c58dde6"
entity_id = "fa407362-9c5f-41b8-9a09-9d0c0b039287"
api_key = "991c4d03-2f2c-4ba5-97a6-45bead85457e"
entity_id = "a3d7e901-2345-6789-abcd-ef0123456789"
api_key = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
channel_id = "8c6e1e6c-fc89-43b4-b00b-884a690c7419"
```

Expand Down Expand Up @@ -531,6 +531,21 @@ make stop-propeller
make start-propeller
```

### Adding or Replacing a Proxy Entity

If your `config.toml` was created before the proxy was part of Propeller, or you need to regenerate the proxy credentials, use the `add-proxy` subcommand:

```bash
propeller-cli provision add-proxy
```

This command:

1. Reads your existing `config.toml` to extract `tenant_id` and `channel_id`
2. Creates a new Atom service entity with an API key for the proxy
3. Connects the entity to the existing channel
4. Updates the `[proxy]` section in your `config.toml`

## Postman Collection

A [Postman collection](../postman_collection.json) of all API calls is available for interacting with the Propeller system.
Expand Down
18 changes: 9 additions & 9 deletions content/docs/k8s/deploy-without-operator.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ kubectl create namespace propeller
```bash
kubectl create secret generic propeller-credentials \
--namespace propeller \
--from-literal=MANAGER_API_KEY=<manager-client-key> \
--from-literal=PROPLET_API_KEY=<proplet-client-key> \
--from-literal=PROXY_API_KEY=<proxy-client-key>
--from-literal=MANAGER_API_KEY=<manager-api-key> \
--from-literal=PROPLET_API_KEY=<proplet-api-key> \
--from-literal=PROXY_API_KEY=<proxy-api-key>
```

### 3. Apply Deployments
Expand Down Expand Up @@ -75,11 +75,11 @@ spec:
image: ghcr.io/absmach/propeller/manager:latest
env:
- name: MANAGER_TENANT_ID
value: "<domain-id>"
value: "<tenant-id>"
- name: MANAGER_CHANNEL_ID
value: "<channel-id>"
- name: MANAGER_ENTITY_ID
value: "<manager-client-id>"
value: "<manager-entity-id>"
- name: MANAGER_API_KEY
valueFrom:
secretKeyRef:
Expand Down Expand Up @@ -108,11 +108,11 @@ spec:
image: ghcr.io/absmach/propeller/proplet:latest
env:
- name: PROPLET_TENANT_ID
value: "<domain-id>"
value: "<tenant-id>"
- name: PROPLET_CHANNEL_ID
value: "<channel-id>"
- name: PROPLET_ENTITY_ID
value: "<proplet-client-id>"
value: "<proplet-entity-id>"
- name: PROPLET_API_KEY
valueFrom:
secretKeyRef:
Expand Down Expand Up @@ -141,11 +141,11 @@ spec:
image: ghcr.io/absmach/propeller/proxy:latest
env:
- name: PROXY_TENANT_ID
value: "<domain-id>"
value: "<tenant-id>"
- name: PROXY_CHANNEL_ID
value: "<channel-id>"
- name: PROXY_ENTITY_ID
value: "<proplet-client-id>"
value: "<proxy-entity-id>"
- name: PROXY_API_KEY
valueFrom:
secretKeyRef:
Expand Down
Loading