Skip to content

Commit e998189

Browse files
jhuckabyjhuckaby
committed
API Doc: Add docs on internal satellite install/upgrade/config endpoints.
1 parent 34290b7 commit e998189

1 file changed

Lines changed: 155 additions & 0 deletions

File tree

‎docs/api.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5735,6 +5735,161 @@ Example response:
57355735
{ "code": 0 }
57365736
```
57375737

5738+
5739+
5740+
## xyOps Satellite
5741+
5742+
These APIs handle xySat bootstrap, install, upgrade, and release discovery. Unlike most xyOps APIs, the `satellite` endpoint family serves plain-text scripts, tarballs, and JSON config files rather than the standard JSON response envelope on success.
5743+
5744+
### get_satellite_token
5745+
5746+
```
5747+
POST /api/app/get_satellite_token/v1
5748+
```
5749+
5750+
Generate a short-lived satellite bootstrap token for use with the [satellite](#satellite) API family. Requires a valid user session or API Key with the [add_servers](privileges.md#add_servers) privilege.
5751+
5752+
Parameters:
5753+
5754+
| Property Name | Type | Description |
5755+
|---------------|------|-------------|
5756+
| `expires` | Number | Optional. Token lifetime in seconds. Defaults to `86400` (24 hours). |
5757+
| `title` | String | Optional. Initial title / label to assign to the server on first connect. |
5758+
| `enabled` | Boolean | Optional. Initial enabled state for the server record. |
5759+
| `icon` | String | Optional. Initial icon for the server record. |
5760+
| `groups` | Array(String) | Optional. Initial server groups. Empty arrays are ignored. |
5761+
| (Other) | Various | Optional. Additional initial server metadata to embed in the bootstrap token. |
5762+
5763+
Example request:
5764+
5765+
```json
5766+
{
5767+
"title": "Build Worker 01",
5768+
"enabled": 1,
5769+
"icon": "server",
5770+
"groups": ["build", "linux"],
5771+
"expires": 3600
5772+
}
5773+
```
5774+
5775+
Example response:
5776+
5777+
```json
5778+
{
5779+
"code": 0,
5780+
"token": "tme4wxyz9ab",
5781+
"base_url": "https://xyops01.example.com",
5782+
"image": "ghcr.io/pixlcore/xysat",
5783+
"version": "latest"
5784+
}
5785+
```
5786+
5787+
In addition to the [Standard Response Format](#standard-response-format), this returns:
5788+
5789+
- `token`: The generated time-based bootstrap token.
5790+
- `base_url`: Base URL to use for the bootstrap request.
5791+
- `image`: The configured xySat container image name.
5792+
- `version`: The configured xySat release tag to install.
5793+
5794+
Notes:
5795+
5796+
- The returned token authenticates satellite bootstrap requests via the `t` query parameter.
5797+
- `base_url`, `image`, and `version` come from the conductor's [satellite](config.md#satellite) configuration.
5798+
- The bootstrap token carries the initial server metadata, which is later written into the generated satellite config as `initial`.
5799+
5800+
### get_satellite_releases
5801+
5802+
```
5803+
GET /api/app/get_satellite_releases/v1
5804+
```
5805+
5806+
Fetch the list of official xySat release tags from the origin configured in [satellite](config.md#satellite) (usually GitHub). Requires a valid user session or API Key with the [add_servers](privileges.md#add_servers) privilege.
5807+
5808+
No input parameters.
5809+
5810+
Example response:
5811+
5812+
```json
5813+
{
5814+
"code": 0,
5815+
"releases": ["latest", "v0.9.50", "v0.9.49"]
5816+
}
5817+
```
5818+
5819+
In addition to the [Standard Response Format](#standard-response-format), this returns a `releases` array. The first element is always `latest`, followed by the discovered release tags.
5820+
5821+
Notes:
5822+
5823+
- This uses the configured release metadata URL, typically GitHub, from the [satellite](config.md#satellite) settings.
5824+
- Air-gap rules are honored. If air-gap mode is enabled and a satellite bucket is configured, the API returns `["airgap"]` instead of querying upstream.
5825+
5826+
### satellite
5827+
5828+
```
5829+
GET /api/app/satellite/install?t=...
5830+
GET /api/app/satellite/upgrade?s=...&t=...
5831+
GET /api/app/satellite/core?t=...&os=...&arch=...
5832+
GET /api/app/satellite/config?t=...
5833+
```
5834+
5835+
Bootstrap or upgrade xySat on remote systems. This endpoint family is used internally by the "Add Server" flow, the worker upgrade system, Docker bootstrap, and xySat self-upgrade.
5836+
5837+
Authentication:
5838+
5839+
- Bootstrap token: Pass a time-based token from [get_satellite_token](#get_satellite_token) in the `t` query parameter.
5840+
- Server token: Pass the server's permanent auth token in `t` and the server ID in `s`. This is used for self-upgrade and is accepted only for active or recently active servers.
5841+
- API Key: Pass an API Key with the [add_servers](privileges.md#add_servers) privilege in `t`. This is primarily for automated deployments and ephemeral infrastructure.
5842+
5843+
Common query parameters:
5844+
5845+
| Property Name | Type | Description |
5846+
|---------------|------|-------------|
5847+
| `t` | String | **(Required)** Authentication token. This may be a bootstrap token, server auth token, or API Key. |
5848+
| `s` | String | Required for `/upgrade`, and also when authenticating via a server auth token. This is the Server ID. |
5849+
| `os` | String | Optional for `/install` to select the Windows PowerShell script. Required for `/core` to select the correct package, e.g. `linux`, `darwin`, or `windows`. |
5850+
| `arch` | String | Required for `/core` to select the correct package architecture, e.g. `x64` or `arm64`. |
5851+
5852+
Sub-methods:
5853+
5854+
- `/api/app/satellite/install`: Returns a plain-text bootstrap script (`text/plain`). Use `os=windows` to fetch the PowerShell installer; otherwise a POSIX shell script is returned. When authenticated with a bootstrap token, any extra query parameters other than `t` and `os` are merged into the initial server metadata before the config is generated.
5855+
- `/api/app/satellite/upgrade`: Returns a plain-text upgrade script (`text/plain`). Requires `s` plus `t`. Use `os=windows` to fetch the PowerShell upgrade script; otherwise a POSIX shell script is returned.
5856+
- `/api/app/satellite/core`: Returns the xySat tarball (`application/gzip`) with a download filename like `satellite-OS-ARCH.tar.gz`. If a satellite bucket is configured, the file is served from there. Otherwise xyOps uses its local cache and fetches from the configured upstream release base URL as needed.
5857+
- `/api/app/satellite/config`: Returns a generated `config.json` file (`application/json`). This includes the conductor's `satellite.config`, air-gap settings if not already present, the current master host and port, a newly generated `server_id`, a derived `auth_token`, and any initial bootstrap metadata under `initial`.
5858+
5859+
Example bootstrap commands:
5860+
5861+
```sh
5862+
curl -s "https://xyops01.example.com/api/app/satellite/install?t=TOKEN_HERE" | sudo sh
5863+
```
5864+
5865+
```powershell
5866+
powershell -Command "IEX (Invoke-WebRequest -UseBasicParsing -Uri 'https://xyops01.example.com/api/app/satellite/install?t=TOKEN_HERE&os=windows').Content"
5867+
```
5868+
5869+
Example `config` response:
5870+
5871+
```json
5872+
{
5873+
"port": 5522,
5874+
"secure": false,
5875+
"hosts": ["xyops01.example.com"],
5876+
"server_id": "sabc123def",
5877+
"auth_token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
5878+
"initial": {
5879+
"title": "Build Worker 01",
5880+
"groups": ["build", "linux"]
5881+
}
5882+
}
5883+
```
5884+
5885+
Notes:
5886+
5887+
- Successful responses are streamed files or plain text, depending on the sub-method. On errors, the standard JSON API error format is returned.
5888+
- `/config` generates a fresh `server_id` and `auth_token` on every request, which is why the same API Key based bootstrap URL can be reused for provisioning ephemeral workers.
5889+
- `/core` and release metadata requests honor air-gap settings.
5890+
5891+
5892+
57385893
## Miscellaneous
57395894

57405895
### ping

0 commit comments

Comments
 (0)