Skip to content

Commit 1147e76

Browse files
elibosleycoderabbitai[bot]
elibosley
and
coderabbitai[bot]
authored
feat: auto-docusaurus-prs (#1127)
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Expanded the Unraid API guides with comprehensive CLI command details for managing services, logs, configuration, and authentication. - Updated the API usage instructions to include steps for enabling a GraphQL sandbox, example queries, error handling, and best practices. - Added an implementation overview detailing component capabilities and a release roadmap outlining upcoming improvements across core infrastructure, security, and user interface. - **Chores** - Introduced automation that streamlines the updating of API documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent fd3b1fb commit 1147e76

File tree

5 files changed

+623
-0
lines changed

5 files changed

+623
-0
lines changed

‎.github/workflows/create-docusaurus-pr.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Update API Documentation
2+
3+
name: Update API Documentation
4+
on:
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- 'api/docs/**'
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.ref }}
12+
cancel-in-progress: true
13+
14+
# Add permissions for GITHUB_TOKEN
15+
permissions:
16+
contents: write
17+
pull-requests: write
18+
jobs:
19+
create-docs-pr:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout source repository
23+
uses: actions/checkout@v4
24+
with:
25+
path: source-repo
26+
27+
- name: Checkout docs repository
28+
uses: actions/checkout@v4
29+
with:
30+
repository: unraid/docs
31+
path: docs-repo
32+
token: ${{ github.token }}
33+
34+
- name: Copy updated docs
35+
run: |
36+
if [ ! -d "source-repo/api/docs" ]; then
37+
echo "Source directory does not exist!"
38+
exit 1
39+
fi
40+
mkdir -p docs-repo/docs/api
41+
cp -r source-repo/api/docs/* docs-repo/docs/api/
42+
- name: Create Pull Request
43+
uses: peter-evans/create-pull-request@v6
44+
with:
45+
token: ${{ github.token }}
46+
path: docs-repo
47+
commit-message: 'docs: update API documentation'
48+
title: 'Update API Documentation'
49+
body: |
50+
This PR updates the API documentation based on changes from the main repository.
51+
52+
Changes were automatically generated from api/docs/* directory.
53+
branch: update-api-docs
54+
base: main
55+
delete-branch: true

‎api/docs/cli.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# CLI Commands
2+
3+
### Start
4+
5+
```bash
6+
unraid-api start [--log-level <level>]
7+
```
8+
9+
Starts the Unraid API service.
10+
11+
- `--log-level`: Optional. Set logging level (trace|debug|info|warn|error)
12+
13+
### Stop
14+
15+
```bash
16+
unraid-api stop [--delete]
17+
```
18+
19+
Stops the Unraid API service.
20+
21+
- `--delete`: Optional. Delete the PM2 home directory
22+
23+
### Restart
24+
25+
```bash
26+
unraid-api restart
27+
```
28+
29+
Restarts the Unraid API service.
30+
31+
### Logs
32+
33+
```bash
34+
unraid-api logs [-l <lines>]
35+
```
36+
37+
View the API logs.
38+
39+
- `-l, --lines`: Optional. Number of lines to tail (default: 100)
40+
41+
## Configuration Commands
42+
43+
### Config
44+
45+
```bash
46+
unraid-api config
47+
```
48+
49+
Displays current configuration values.
50+
51+
### Switch Environment
52+
53+
```bash
54+
unraid-api switch-env [-e <environment>]
55+
```
56+
57+
Switch between production and staging environments.
58+
59+
- `-e, --environment`: Optional. Target environment (production|staging)
60+
61+
### Developer Mode
62+
63+
```bash
64+
unraid-api developer
65+
```
66+
67+
Configure developer features for the API (e.g., GraphQL sandbox).
68+
69+
## API Key Management
70+
71+
### API Key Commands
72+
73+
```bash
74+
unraid-api apikey [options]
75+
```
76+
77+
Create and manage API keys.
78+
79+
Options:
80+
81+
- `--name <name>`: Name of the key
82+
- `--create`: Create a new key
83+
- `-r, --roles <roles>`: Comma-separated list of roles
84+
- `-p, --permissions <permissions>`: Comma-separated list of permissions
85+
- `-d, --description <description>`: Description for the key
86+
87+
## SSO (Single Sign-On) Management
88+
89+
### SSO Base Command
90+
91+
```bash
92+
unraid-api sso
93+
```
94+
95+
#### Add SSO User
96+
97+
```bash
98+
unraid-api sso add-user
99+
# or
100+
unraid-api sso add
101+
# or
102+
unraid-api sso a
103+
```
104+
105+
Add a new user for SSO authentication.
106+
107+
#### Remove SSO User
108+
109+
```bash
110+
unraid-api sso remove-user
111+
# or
112+
unraid-api sso remove
113+
# or
114+
unraid-api sso r
115+
```
116+
117+
Remove a user (or all users) from SSO.
118+
119+
#### List SSO Users
120+
121+
```bash
122+
unraid-api sso list-users
123+
# or
124+
unraid-api sso list
125+
# or
126+
unraid-api sso l
127+
```
128+
129+
List all configured SSO users.
130+
131+
#### Validate SSO Token
132+
133+
```bash
134+
unraid-api sso validate-token <token>
135+
# or
136+
unraid-api sso validate
137+
# or
138+
unraid-api sso v
139+
```
140+
141+
Validates an SSO token and returns its status.
142+
143+
## Report Generation
144+
145+
### Generate Report
146+
147+
```bash
148+
unraid-api report [-r] [-j]
149+
```
150+
151+
Generate a system report.
152+
153+
- `-r, --raw`: Display raw command output
154+
- `-j, --json`: Display output in JSON format
155+
156+
## Notes
157+
158+
1. Most commands that modify the system state will require appropriate permissions.
159+
2. Some commands may require the API to be running or stopped depending on their function.
160+
3. When using API keys, ensure you store them securely as they provide access to your system.
161+
4. SSO configuration changes may require a service restart to take effect.

‎api/docs/feature-implementation.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Unraid API Project Status
2+
3+
This document outlines the current implementation status of various Unraid components in the API.
4+
5+
## Implementation Status Legend
6+
7+
- ✅ Fully Implemented
8+
- 🟡 Partially Implemented
9+
- ❌ Not Implemented
10+
- 🔒 Requires Authentication
11+
12+
## Core Components
13+
14+
| Component | Read | Write | Update | Notes |
15+
|-----------|------|-------|--------|-------|
16+
| Array | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Full array management including start/stop/status |
17+
| Parity | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Check/pause/resume functionality |
18+
| Disks | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Comprehensive disk management |
19+
| Docker | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Container and network management |
20+
21+
## System Information
22+
23+
| Component | Read | Write | Notes |
24+
|-----------|------|-------|-------|
25+
| CPU | ✅ | ❌ | Detailed CPU information including cores, cache, flags |
26+
| Memory | ✅ | ❌ | RAM and swap information |
27+
| OS | ✅ | ❌ | System version and kernel details |
28+
| Hardware | ✅ | ❌ | Baseboard and system information |
29+
| Network | ✅ | 🟡 | Basic network interface information |
30+
31+
## Configuration & Management
32+
33+
| Component | Read | Write | Update | Notes |
34+
|-----------|------|-------|--------|-------|
35+
| API Keys | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Full CRUD operations |
36+
| SSO | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Complete SSO integration |
37+
| Remote Access | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Dynamic and static access configuration |
38+
| Display Settings | ✅ 🔒 | 🟡 | 🟡 | Basic display configuration |
39+
40+
## Device Management
41+
42+
| Component | Read | Write | Notes |
43+
|-----------|------|-------|-------|
44+
| GPU | ✅ | ❌ | Basic GPU information |
45+
| USB Devices | ✅ | ❌ | Basic USB device enumeration |
46+
| PCI Devices | ✅ | ❌ | PCI device information |
47+
| Storage Devices | ✅ | 🟡 | Comprehensive storage information |
48+
49+
## Security & Authentication
50+
51+
| Feature | Status | Notes |
52+
|---------|--------|-------|
53+
| Role-Based Access | ✅ | Implemented roles: admin, connect, guest |
54+
| API Key Authentication | ✅ | Full implementation with key management |
55+
| Permission System | ✅ | Granular resource-based permissions |
56+
| Rate Limiting | ✅ | Implemented with configurable limits |
57+
58+
## Available Resources
59+
60+
The following resources are available for API access:
61+
62+
```typescript
63+
enum Resource {
64+
api_key
65+
array
66+
cloud
67+
config
68+
connect
69+
connect__remote_access
70+
customizations
71+
dashboard
72+
disk
73+
display
74+
docker
75+
flash
76+
info
77+
logs
78+
me
79+
network
80+
notifications
81+
online
82+
os
83+
owner
84+
permission
85+
registration
86+
servers
87+
services
88+
share
89+
vars
90+
vms
91+
welcome
92+
}
93+
```
94+
95+
## Authentication Methods
96+
97+
1. API Key Authentication
98+
- Header-based authentication
99+
- Role-based access control
100+
- Granular permissions
101+
102+
2. Session-based Authentication
103+
- Cookie-based authentication
104+
- CSRF protection
105+
- Integration with Unraid's existing auth system
106+
107+
## Rate Limiting
108+
109+
Current implementation:
110+
- 100 requests per 10 seconds per IP
111+
- Configurable through ThrottlerModule
112+
113+
## Development Features
114+
115+
| Feature | Status | Notes |
116+
|---------|--------|-------|
117+
| GraphQL Sandbox | ✅ | Available in developer mode |
118+
| CLI Tools | ✅ | Comprehensive command line interface |
119+
| Error Handling | ✅ | Standardized error responses |
120+
| Logging | ✅ | Configurable log levels |
121+
122+
## Notes
123+
124+
1. All authenticated endpoints require either:
125+
- Valid API key in X-API-Key header
126+
- Valid session cookie with CSRF token
127+
128+
2. Resource access is controlled by:
129+
- User roles
130+
- Individual permissions
131+
- Resource-specific policies
132+
133+
3. The API implements standard GraphQL features:
134+
- Queries for reading data
135+
- Mutations for writing/updating data
136+
- Subscriptions for real-time updates

0 commit comments

Comments
 (0)