mirror of
https://github.com/unraid/api.git
synced 2026-01-21 07:59:41 -06:00
118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
# @unraid/api
|
|
|
|
## Installation
|
|
|
|
Ensure you have the latest version of the unraid.net plugin.
|
|
This script should be run automatically on every boot.
|
|
```bash
|
|
/etc/rc.d/rc.unraid-api install
|
|
```
|
|
|
|
## CLI
|
|
|
|
If you're on a unraid v6.9.0 or later machine this should be avaliable by running `unraid-api` in any directory.
|
|
|
|
```bash
|
|
root@Devon:~# unraid-api
|
|
|
|
Unraid API
|
|
|
|
Thanks for using the official Unraid API
|
|
|
|
Usage:
|
|
|
|
$ unraid-api command <options>
|
|
|
|
Options:
|
|
|
|
-h, --help Prints this usage guide.
|
|
-d, --debug Enabled debug mode.
|
|
-p, --port string Set the graphql port.
|
|
--environment production/staging/development Set the working environment.
|
|
--log-level error/warn/info/debug/trace/silly Set the log level.
|
|
--log-transport console/syslog Set the log transport. (default=syslog)
|
|
-v, --version Show version.
|
|
|
|
Copyright © 2021 Lime Technology, Inc.
|
|
|
|
```
|
|
|
|
## Connecting
|
|
|
|
### HTTP
|
|
This can be accessed by default via `http://tower.local/graphql`. If the server is connected to my servers then it's likely to have a DNS hash address, something like `https://www.__HASH_HERE__.unraid.net/graphql`.
|
|
|
|
See https://graphql.org/learn/serving-over-http/#http-methods-headers-and-body
|
|
|
|
### WS
|
|
If you're using the ApolloClient please see https://github.com/apollographql/subscriptions-transport-ws#full-websocket-transport otherwise see https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md
|
|
|
|
## Logs
|
|
|
|
If installed on a unraid machine logs can be accessed via syslog.
|
|
|
|
Log levels can be changed on start using the `--log-level` flag like so `--log-level=info/debug/silly/trace`.
|
|
|
|
## Debug mode
|
|
|
|
Debug mode can be enabled with the `-d` or `--debug` flag.
|
|
This will enable debug logs and the playground.
|
|
|
|
|
|
## Playground
|
|
|
|
The playground can be access via `http://tower.local/graphql` while in debug mode.
|
|
To get your API key open a terminal on your server and run `cat /boot/config/plugins/dynamix.my.servers/myservers.cfg | grep apikey= | cut -d '"' -f2`. Add that API key in the "HTTP headers" panel of the playground.
|
|
|
|
```json
|
|
{
|
|
"x-api-key":"__REPLACE_ME_WITH_API_KEY__"
|
|
}
|
|
```
|
|
|
|
Next add the query you want to run and hit the play icon.
|
|
```gql
|
|
query welcome {
|
|
welcome {
|
|
message
|
|
}
|
|
}
|
|
```
|
|
|
|
You should get something like this back.
|
|
```json
|
|
{
|
|
"data": {
|
|
"welcome": {
|
|
"message": "Welcome root to this Unraid 6.9.0 server"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Click the "Schema" and "Docs" button on the right side of the playground to learn more.
|
|
For exploring the schema visually I'd suggest using [Voyager](https://apis.guru/graphql-voyager/).
|
|
|
|
# Development
|
|
|
|
## Running this locally
|
|
```bash
|
|
NCHAN=disable \ # Disable nchan polling
|
|
MOTHERSHIP_RELAY_WS_LINK=ws://localhost:8000 \ # Switch to local copy of mothership
|
|
PATHS_UNRAID_DATA=$(pwd)/dev/data \ # Where we store plugin data (e.g. permissions.json)
|
|
PATHS_STATES=$(pwd)/dev/states \ # Where .ini files live (e.g. vars.ini)
|
|
PATHS_DYNAMIX_BASE=$(pwd)/dev/dynamix \ # Dynamix's data directory
|
|
PATHS_DYNAMIX_CONFIG=$(pwd)/dev/dynamix/dynamix.cfg \ # Dynamix's config file
|
|
PATHS_MY_SERVERS_CONFIG=$(pwd)/dev/unraid.net/myservers.cfg \ # My servers config file
|
|
PORT=8500 \ # What port unraid-api should start on (e.g. /var/run/unraid-api.sock or 8000)
|
|
node dist/cli.js --debug # Enable debug logging
|
|
```
|
|
|
|
## Release
|
|
|
|
To create a new version run `npm run release`.
|
|
To create a new prerelease run `npm run release -- --prerelease alpha`.
|
|
|
|
## License
|
|
Copyright 2019-2021 Lime Technology Inc. All rights reserved.
|