Skip to content

Commit b7ca3cb

Browse files
raphael-goetzraphael-goetz
committed
docs: updated docs to latest configuration file
1 parent 8f71224 commit b7ca3cb

2 files changed

Lines changed: 52 additions & 33 deletions

File tree

‎docs/dev.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,4 +124,4 @@ Aquila --> NATS
124124
```
125125

126126
> In static mode, flow data and service authorization are loaded from local
127-
files (for example `FLOW_FALLBACK_PATH` and `SERVICE_CONFIG_PATH`) before runtime execution starts.
127+
files (for example `static_config.flow_path` and `AQUILA_SERVICE_CONFIG_PATH`) before runtime execution starts.

‎docs/installation.mdx‎

Lines changed: 51 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,10 @@ Clone this repository to your local machine.
3535

3636
<Step>
3737

38-
#### **Set up environment variables**
38+
#### **Configure Aquila**
3939

40-
Configure `.env` in the project root with the required settings.
41-
You can use `.env-example` as a starting point.
40+
Configure `aquila.yml` in the project root. To keep the Sagittarius token out of the file, set
41+
`AQUILA_BACKEND_TOKEN` in the environment or a local `.env` file.
4242

4343
</Step>
4444

@@ -54,7 +54,7 @@ You can use `.env-example` as a starting point.
5454

5555
**Sagittarius**:
5656

57-
- Required for dynamic mode (`MODE=dynamic`)
57+
- Required for dynamic mode (`mode: dynamic`)
5858
- Ensure the configured endpoint is reachable
5959

6060
</Step>
@@ -74,57 +74,76 @@ cargo run
7474
</Steps>
7575
---
7676

77-
## Environment Variables
77+
## Configuration
7878

79-
Aquila configuration is split into shared variables and mode-specific variables.
79+
Aquila reads `aquila.yml` from the working directory. Built-in defaults are used when the file is
80+
absent. Configuration values are read from this file, except that `AQUILA_BACKEND_TOKEN` can
81+
override `dynamic_config.backend_token` so the token can be injected as a secret.
82+
83+
Select a different configuration file with `AQUILA_CONFIG_PATH`:
84+
85+
```bash
86+
AQUILA_CONFIG_PATH=/path/to/aquila.yml cargo run
87+
```
88+
89+
The `log_level` setting controls the default log level. The standard `RUST_LOG` variable can still
90+
provide a more specific runtime filter, for example `RUST_LOG=aquila::server=trace`.
8091

8192
### Common (Static + Dynamic)
8293

83-
| Name | Description | Default |
84-
|-----------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------|
85-
| `MODE` | Runtime mode. `static` loads local flows. `dynamic` enables dynamic synchronization with Sagittarius. | `static` |
86-
| `ENVIRONMENT` | Runtime environment (`development`, `staging`, `production`). | `development` |
87-
| `NATS_URL` | URL of the NATS instance Aquila connects to. | `nats://localhost:4222` |
88-
| `NATS_BUCKET` | Name of the NATS KV bucket used to store flows. | `flow_store` |
89-
| `GRPC_HOST` | Hostname for the Aquila gRPC server. | `127.0.0.1` |
90-
| `GRPC_PORT` | Port for the Aquila gRPC server. | `8081` |
91-
| `WITH_HEALTH_SERVICE` | Enables the gRPC health service when set to `true`. | `false` |
92-
| `SERVICE_CONFIG_PATH` | Path to the JSON service-configuration file used for runtime/action authorization and default action configs. | `./service.configuration.json` |
93-
| `RUNTIME_STATUS_NOT_RESPONDING_AFTER_SECS` | Seconds before a runtime service is marked as `not_responding` when no heartbeat was received. | `90s` |
94-
| `RUNTIME_STATUS_STOPPED_AFTER_NOT_RESPONDING_SECS` | Additional seconds before a non-responding runtime service is marked as `stopped`. | `180s` |
95-
| `RUNTIME_STATUS_MONITOR_INTERVAL_SECS` | Interval in which runtime service heartbeats are checked. | `30s` |
96-
| `SAGITTARIUS_UNARY_RPC_TIMEOUT_SECS` | Timeout in seconds for unary RPC calls from Aquila to Sagittarius. | `5s` |
94+
| YAML key | Description |
95+
|----------|-------------|
96+
| `mode` | `static` loads local flows; `dynamic` synchronizes with Sagittarius. |
97+
| `environment` | `development`, `staging`, or `production`. |
98+
| `log_level` | Default application log filter. |
99+
| `nats.url` | NATS server URL. |
100+
| `nats.bucket` | NATS KV bucket used to store flows. |
101+
| `grpc.host` | Aquila gRPC bind host. |
102+
| `grpc.port` | Aquila gRPC bind port. |
103+
| `grpc.health_service` | Enables the gRPC health service. |
104+
| `runtime_status.not_responding_after_secs` | Heartbeat timeout before `not_responding`. |
105+
| `runtime_status.stopped_after_not_responding_secs` | Additional timeout before `stopped`. |
106+
| `runtime_status.monitor_interval_secs` | Heartbeat monitor interval. |
97107

98108
### Static Mode
99109

100-
Set `MODE=static` to load flows from a local JSON file and insert them into the NATS KV store on startup.
110+
Set `mode: static` to load flows from a local JSON file and insert them into the NATS KV store on startup.
101111

102-
| Name | Description | Default |
103-
|----------------------|-----------------------------------------------|---------------------|
104-
| `FLOW_FALLBACK_PATH` | Path to the flow JSON file loaded at startup. | `./flowExport.json` |
112+
| YAML key | Description | Default |
113+
|----------|-------------|---------|
114+
| `static_config.flow_path` | Path to the flow JSON file loaded at startup. | `./flowExport.json` |
105115

106116
### Dynamic Mode
107117

108-
Set `MODE=dynamic` to keep flows synchronized from Sagittarius.
118+
Set `mode: dynamic` to keep flows synchronized from Sagittarius.
109119

110-
| Name | Description | Default |
111-
|-------------------|-----------------------------------------------------------------------------------|--------------------------|
112-
| `SAGITTARIUS_URL` | URL of the Sagittarius instance Aquila connects to for flow and action updates. | `http://localhost:50051` |
113-
| `RUNTIME_TOKEN` | Token used by Aquila to authenticate with Sagittarius. | `default_session_token` |
120+
| YAML key | Environment override | Description | Default |
121+
|----------|----------------------|-------------|---------|
122+
| `dynamic_config.backend_url` | — | URL of the Sagittarius instance Aquila connects to for flow and action updates. | `http://localhost:50051` |
123+
| `dynamic_config.backend_token` | `AQUILA_BACKEND_TOKEN` | Token used by Aquila to authenticate with Sagittarius. | `default_session_token` |
124+
| `dynamic_config.backend_unary_timeout_secs` | — | Timeout for unary Sagittarius RPCs. | `5` |
114125

115126
---
116127

117128
## Service Configuration File
118129

119-
To authorize services like `Taurus`, `Draco`, or an `Action`, they must be declared in Aquila's service configuration file.
130+
To authorize services like `Taurus`, `Draco`, or an `Action`, they must be declared in Aquila's
131+
separate service configuration file.
132+
133+
The service configuration is optional. Aquila starts with an empty service configuration when
134+
`AQUILA_SERVICE_CONFIG_PATH` is unset. Load one independently with:
135+
136+
```bash
137+
AQUILA_SERVICE_CONFIG_PATH=/path/to/service.configuration.json cargo run
138+
```
120139

121-
`SERVICE_CONFIG_PATH` points to a JSON file that defines:
140+
The file defines:
122141

123142
- Allowed runtime tokens
124143
- Allowed action tokens
125144
- Optional default action configurations
126145

127-
This file is loaded on startup. If the file is missing or invalid, Aquila starts with an empty service configuration.
146+
If the selected file is missing or invalid, Aquila starts with an empty service configuration.
128147

129148
Default:
130149

0 commit comments

Comments
 (0)