Jeffrey Smith
3d4228f868
All checks were successful
Co-authored-by: Jeffrey Smith <jasafpro@gmail.com> Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>
95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# Package Registry
|
|
|
|
The package registry lets admins browse and install packages from an external
|
|
JSON index — a lightweight alternative to manually uploading `.pkg` files.
|
|
|
|
## Registry JSON Format
|
|
|
|
The registry is a static JSON file matching the `RegistryResponse` struct:
|
|
|
|
```json
|
|
{
|
|
"packages": [
|
|
{
|
|
"id": "notes",
|
|
"title": "Notes",
|
|
"version": "0.8.0",
|
|
"description": "Markdown notes with backlinks and graph view",
|
|
"author": "switchboard",
|
|
"type": "extension",
|
|
"tier": "core",
|
|
"download_url": "https://cdn.example.com/pkg/notes.pkg",
|
|
"size": 48200,
|
|
"updated_at": "2026-03-20T00:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Required Fields
|
|
|
|
| Field | Description |
|
|
|----------------|------------------------------------------------|
|
|
| `id` | Package identifier (matches `manifest.json`) |
|
|
| `title` | Display name |
|
|
| `version` | Semver version string |
|
|
| `description` | Short description |
|
|
| `download_url` | HTTPS URL to the `.pkg` file (must be HTTPS) |
|
|
|
|
### Optional Fields
|
|
|
|
| Field | Description |
|
|
|--------------|------------------------------------------|
|
|
| `author` | Package author |
|
|
| `type` | `extension` or `library` |
|
|
| `tier` | `core`, `official`, or `community` |
|
|
| `size` | File size in bytes |
|
|
| `updated_at` | ISO 8601 timestamp of last update |
|
|
|
|
## Configuring the Registry URL
|
|
|
|
### Via Admin UI
|
|
|
|
Navigate to **Admin > Settings > Package Registry** and enter the registry URL.
|
|
|
|
### Via API
|
|
|
|
```bash
|
|
curl -X PUT /api/v1/admin/settings/package_registry \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"value": {"url": "https://cdn.example.com/pkg/registry.json"}}'
|
|
```
|
|
|
|
## Generating a Registry
|
|
|
|
Use `scripts/generate-registry.sh` to build a `registry.json` from a
|
|
directory of `.pkg` files:
|
|
|
|
```bash
|
|
# Default: reads dist/, uses placeholder base URL
|
|
./scripts/generate-registry.sh
|
|
|
|
# Custom directory and base URL
|
|
./scripts/generate-registry.sh ./my-packages https://cdn.example.com/pkg > registry.json
|
|
```
|
|
|
|
Requirements: `jq`, `unzip`, and `stat` (GNU or BSD).
|
|
|
|
## Self-Hosting
|
|
|
|
Any HTTPS-capable file server works. Upload your `.pkg` files and the
|
|
generated `registry.json` to the same directory, then point the admin
|
|
setting to the `registry.json` URL.
|
|
|
|
Example with a static file server:
|
|
|
|
```
|
|
/var/www/packages/
|
|
registry.json
|
|
notes.pkg
|
|
chat.pkg
|
|
chat-core.pkg
|
|
```
|
|
|
|
The registry is fetched and cached for 5 minutes on each browse request.
|