Skip to content

Commit d44f547

Browse files
frristfrrist
committed
final touch, include telemetry details
1 parent aa7360f commit d44f547

File tree

15 files changed

+519
-51
lines changed

15 files changed

+519
-51
lines changed

‎docs/content/cli/client/admin/config/get.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# get
22

3-
Get a specific dynamic configuration value.
3+
Get the current runtime value of a dynamic configuration key.
4+
5+
This is the value Piri is using right now, which may differ from the config file if a runtime override has been applied via `set`.
46

57
## Usage
68

‎docs/content/cli/client/admin/config/index.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,60 @@
22

33
Manage dynamic configuration values at runtime.
44

5+
## How It Works
6+
7+
The config file is the source of truth. Runtime changes are ephemeral by default—they override behavior without touching the file. A reload restores the file's authority. The `--persist` flag exists for operators who mean it: change the behavior and update the file so the two agree.
8+
9+
This prevents the most common configuration surprise: a system whose running state has silently diverged from its config file, discovered during a restart nobody planned for.
10+
11+
**Example workflow:**
12+
13+
A Piri node starts with this config file:
14+
15+
```toml
16+
[pdp.aggregation.manager]
17+
poll_interval = "30s"
18+
```
19+
20+
The node uses a poll interval of 30 seconds.
21+
22+
**Runtime override (ephemeral):**
23+
24+
```
25+
piri client admin config set pdp.aggregation.manager.poll_interval 5m
26+
```
27+
28+
The node now uses 5 minutes. The config file is unchanged.
29+
30+
**Reload from file:**
31+
32+
```
33+
piri client admin config reload
34+
```
35+
36+
The node returns to 30 seconds. The file wins; runtime overrides do not survive a reload.
37+
38+
**Edit the file, then reload:**
39+
40+
```toml
41+
[pdp.aggregation.manager]
42+
poll_interval = "5m"
43+
```
44+
45+
```
46+
piri client admin config reload
47+
```
48+
49+
The node uses 5 minutes. The file still wins—it just agrees with you now.
50+
51+
**Runtime override with `--persist`:**
52+
53+
```
54+
piri client admin config set pdp.aggregation.manager.poll_interval 10m --persist
55+
```
56+
57+
The node uses 10 minutes and the config file is updated to match. Future reloads will preserve the change.
58+
559
## Usage
660

761
```

‎docs/content/cli/client/admin/config/list.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# list
22

3-
List all dynamic configuration values.
3+
List the current runtime values of all dynamic configuration keys.
4+
5+
These are the values Piri is using right now. They may differ from the config file if runtime overrides have been applied via `set`.
46

57
## Usage
68

‎docs/content/concepts/database.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Database
2+
3+
Piri uses databases to manage operational state, job queues, and task scheduling. This page explains the database architecture and helps you choose the right backend for your deployment.
4+
5+
## Logical Databases
6+
7+
Piri maintains four logical databases, each serving a distinct purpose:
8+
9+
| Database | Purpose |
10+
|----------|---------|
11+
| **Scheduler** | Task engine state and PDP proof scheduling |
12+
| **Replicator** | Data replication job tracking |
13+
| **Aggregator** | CommP hash aggregation job queue |
14+
| **Egress Tracker** | Data egress operation tracking |
15+
16+
## SQLite Mode (Default)
17+
18+
SQLite is the default database backend, requiring no additional configuration.
19+
20+
### File Locations
21+
22+
When using SQLite, Piri creates separate database files under your configured `data_dir`:
23+
24+
```
25+
{data_dir}/
26+
├── replicator/
27+
│ └── replicator.db
28+
├── pdp/
29+
│ └── state/
30+
│ └── state.db
31+
├── aggregator/
32+
│ └── jobqueue/
33+
│ └── jobqueue.db
34+
└── egress_tracker/
35+
└── jobqueue/
36+
└── jobqueue.db
37+
```
38+
39+
### Characteristics
40+
41+
- **Write-Ahead Logging (WAL)**: Enables concurrent read access while writing
42+
- **Single Writer**: SQLite only supports one writer at a time (1 connection per database)
43+
- **Zero Configuration**: Works out of the box with just `data_dir` set
44+
45+
## PostgreSQL Mode
46+
47+
PostgreSQL mode uses a single database instance with separate schemas for each logical database.
48+
49+
### Schema Layout
50+
51+
All four logical databases share one PostgreSQL database, isolated by schema:
52+
53+
- `replicator` schema
54+
- `scheduler` schema
55+
- `aggregator` schema
56+
- `egress_tracker` schema
57+
58+
### Characteristics
59+
60+
- **Connection Pooling**: Configurable max connections and idle pool size
61+
- **Concurrent Writers**: Supports multiple simultaneous writers
62+
- **External Management**: Database runs separately from Piri
63+
64+
### Configuration
65+
66+
See [Database Configuration](../configuration/repo/database.md) for PostgreSQL setup.
67+
68+
## Choosing a Backend
69+
70+
| Consideration | SQLite | PostgreSQL |
71+
|---------------|--------|------------|
72+
| Setup complexity | None | Requires external database |
73+
| Concurrent writers | Single | Multiple |
74+
| Scaling | Single node | Multiple Piri instances |
75+
| Operational overhead | Low | Higher |
76+
| Backup strategy | File copy | Database dumps |
77+
78+
**Recommended:**
79+
80+
- **SQLite**: Development, testing, single-node deployments
81+
- **PostgreSQL**: Production environments, high availability requirements, multiple Piri instances sharing state
82+
83+
## Backend Switching
84+
85+
> **Warning**: You cannot switch database backends after initial setup. There is no migration path between SQLite and PostgreSQL.
86+
87+
Choose your database backend before storing any data. If you need to switch backends later, you must start with a fresh Piri installation.

‎docs/content/concepts/index.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Concepts
2+
3+
Understanding how Piri works internally.
4+
5+
This section covers the architectural concepts and design decisions behind Piri's components.
6+
7+
## Topics
8+
9+
### [Database](database.md)
10+
11+
How Piri uses databases for operational state, the difference between SQLite and PostgreSQL backends, and guidance on choosing the right backend for your deployment.
12+
13+
### [Networks](networks.md)
14+
15+
Storacha networks that Piri operates on, including service endpoints, smart contract addresses, and chain configuration.
16+
17+
### [Telemetry](telemetry.md)
18+
19+
OpenTelemetry-based observability: metrics and traces emitted by Piri, and how to integrate with your monitoring infrastructure.

‎docs/content/concepts/networks.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Networks
2+
3+
Piri operates on Storacha networks, which define the services and smart contracts it communicates with.
4+
5+
## forge-prod
6+
7+
Production network on Filecoin Mainnet.
8+
9+
**Chain ID:** 314
10+
11+
### Services
12+
13+
| Service | URL | DID |
14+
|----------------|--------------------------------------------|-------------------------------------------|
15+
| Upload | `https://up.forge.storacha.network` | `did:web:up.forge.storacha.network` |
16+
| Indexing | `https://indexer.forge.storacha.network` | `did:web:indexer.forge.storacha.network` |
17+
| Egress Tracker | `https://etracker.forge.storacha.network` | `did:web:etracker.forge.storacha.network` |
18+
| Signing | `https://signer.forge.storacha.network` | `did:web:signer.forge.storacha.network` |
19+
| Registrar | `https://registrar.forge.storacha.network` | - |
20+
| IPNI | `https://ipni.forge.storacha.network` | - |
21+
22+
### Smart Contracts
23+
24+
| Contract | Address |
25+
|-------------------|------------------------------------------------------------------------------------------------------------------------------------|
26+
| PDP Verifier | [`0xBADd0B92C1c71d02E7d520f64c0876538fa2557F`](https://filecoin.blockscout.com/address/0xBADd0B92C1c71d02E7d520f64c0876538fa2557F) |
27+
| Provider Registry | [`0xf55dDbf63F1b55c3F1D4FA7e339a68AB7b64A5eB`](https://filecoin.blockscout.com/address/0xf55dDbf63F1b55c3F1D4FA7e339a68AB7b64A5eB) |
28+
| PDP Service | [`0x56e53c5e7F27504b810494cc3b88b2aa0645a839`](https://filecoin.blockscout.com/address/0x56e53c5e7F27504b810494cc3b88b2aa0645a839) |
29+
| PDP Service View | [`0x778Bbb8F50d759e2AA03ab6FAEF830Ca329AFF9D`](https://filecoin.blockscout.com/address/0x778Bbb8F50d759e2AA03ab6FAEF830Ca329AFF9D) |
30+
| Payments | [`0x23b1e018F08BB982348b15a86ee926eEBf7F4DAa`](https://filecoin.blockscout.com/address/0x23b1e018F08BB982348b15a86ee926eEBf7F4DAa) |
31+
| USDFC Token | [`0x80B98d3aa09ffff255c3ba4A241111Ff1262F045`](https://filecoin.blockscout.com/address/0x80B98d3aa09ffff255c3ba4A241111Ff1262F045) |
32+
33+
**Payer Address (Storacha) :** [`0x3c1ae7a70a2b51458fcb7927fd77aae408a1b857`](https://filecoin.blockscout.com/address/0x3c1ae7a70a2b51458fcb7927fd77aae408a1b857)
34+
35+
## warm-staging
36+
37+
Staging network on Filecoin Calibration testnet. Use this for testing before deploying to production.
38+
39+
**Chain ID:** 314159
40+
41+
### Services
42+
43+
| Service | URL | DID |
44+
|----------------|---------------------------------------------------|--------------------------------------------------|
45+
| Upload | `https://staging.up.warm.storacha.network` | `did:web:staging.up.warm.storacha.network` |
46+
| Indexing | `https://staging.indexer.warm.storacha.network` | `did:web:staging.indexer.warm.storacha.network` |
47+
| Egress Tracker | `https://staging.etracker.warm.storacha.network` | `did:web:staging.etracker.warm.storacha.network` |
48+
| Signing | `https://staging.signer.warm.storacha.network` | `did:web:staging.signer.warm.storacha.network` |
49+
| Registrar | `https://staging.registrar.warm.storacha.network` | - |
50+
| IPNI | `https://staging.ipni.warm.storacha.network` | - |
51+
52+
### Smart Contracts
53+
54+
| Contract | Address |
55+
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
56+
| PDP Verifier | [`0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C`](https://filecoin-testnet.blockscout.com/address/0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C) |
57+
| Provider Registry | [`0x6A96aaB210B75ee733f0A291B5D8d4A053643979`](https://filecoin-testnet.blockscout.com/address/0x6A96aaB210B75ee733f0A291B5D8d4A053643979) |
58+
| PDP Service | [`0x0c6875983B20901a7C3c86871f43FdEE77946424`](https://filecoin-testnet.blockscout.com/address/0x0c6875983B20901a7C3c86871f43FdEE77946424) |
59+
| PDP Service View | [`0xEAD67d775f36D1d2894854D20e042C77A3CC20a5`](https://filecoin-testnet.blockscout.com/address/0xEAD67d775f36D1d2894854D20e042C77A3CC20a5) |
60+
| Payments | [`0x09a0fDc2723fAd1A7b8e3e00eE5DF73841df55a0`](https://filecoin-testnet.blockscout.com/address/0x09a0fDc2723fAd1A7b8e3e00eE5DF73841df55a0) |
61+
| USDFC Token | [`0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0`](https://filecoin-testnet.blockscout.com/address/0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0) |
62+
63+
**Payer Address (Storacha):** [`0x8d3d7cE4F43607C9d0ac01f695c7A9caC135f9AD`](https://filecoin-testnet.blockscout.com/address/0x8d3d7cE4F43607C9d0ac01f695c7A9caC135f9AD)
64+

0 commit comments

Comments
 (0)