Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,19 @@ WEB_PORT=3000
# For the daily downloads digest: Sales and Trends -> Reports -> your vendor number.
# APPLE_VENDOR_NUMBER=

# ---- Updating Sylo ----
# Operators see "Update available" in the dashboard when a newer release is out: Sylo asks GitHub for
# its latest release (anonymously, at most every 6 hours). Set it to off to never ask.
# UPDATE_CHECK=off
# Optional: let Wise Wren (https://github.com/Ferdinand99/Wise-Wren) update Sylo from the dashboard
# ("Update now"). All three are needed. The token (a Wise Wren target token) is a secret; it only stays on
# this server.
# WISE_WREN_URL=http://wise-wren:3003
# WISE_WREN_TOKEN=
# WISE_WREN_TARGET_ID=
# Without a dashboard login (open mode) "Update now" is refused unless you set this to true.
# WISE_WREN_ALLOW_OPEN_MODE=false

# ---- Outbound URLs ----
# RSS feeds and welcome card backgrounds are fetched by the server, so addresses on your own
# network (127.0.0.1, 10.x, 192.168.x, 169.254.x ...) are refused. Allow them on a trusted LAN:
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,16 @@ off the ones you don't need with `INTENT_GUILD_MEMBERS=false` /
logging, push) is optional and listed in [`.env.example`](.env.example) and the
[environment variable table](docs/self-hosting.md#environment-variables).

### Updating Sylo

Update with `docker compose pull && docker compose up -d`. Operators (the accounts in `OWNER_IDS`)
see an **Update available** note in the dashboard when a newer release is out, with its release
notes and this command; set `UPDATE_CHECK=off` to turn the check off. With
[Wise Wren](https://github.com/Ferdinand99/Wise-Wren) set up (`WISE_WREN_URL`, `WISE_WREN_TOKEN`,
`WISE_WREN_TARGET_ID`) the same page has an **Update now** button, and Sylo never needs access to
the Docker socket. Details in
[docs/self-hosting.md](docs/self-hosting.md#update-notice-and-update-now).

### Backups and monitoring

Sylo snapshots its database to `<data>/backups` before every schema migration
Expand Down
75 changes: 74 additions & 1 deletion docs/mobile-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ reviewing it.
- [Permissions](#permissions)
- [Notifications](#notifications)
- [Health and the dev log (operators)](#health-and-the-dev-log-operators)
- [Update notice (operators)](#update-notice-operators)
- [Security notes](#security-notes)

---
Expand Down Expand Up @@ -317,7 +318,7 @@ in there:
| `login` | Whether sign-in is available (false in open mode) |
| `loginProviders` | The configured logins, for example `["discord", "fluxer"]`; empty when `login` is false |
| `platforms` | The platforms the bot runs on, for example `["discord"]` |
| `features` | What this version's app API supports, so the app can hide what an older Sylo lacks. Today: `app-login`, `live-access`, `changelog`, `collectibles`, `welcome-trigger`, `member-search`, `access-levels`, `health`, `app-connect`, `setup-wizard`, `config-history`, `inbox-search`, `config-import`, `duplicate`, `message-templates` and `message-move`, plus `push` and `push-pigeon` when this instance can send notifications. See the list below |
| `features` | What this version's app API supports, so the app can hide what an older Sylo lacks. Today: `app-login`, `live-access`, `changelog`, `collectibles`, `welcome-trigger`, `member-search`, `access-levels`, `health`, `app-connect`, `setup-wizard`, `config-history`, `inbox-search`, `config-import`, `duplicate`, `message-templates`, `message-move` and `update-notice`, plus `push` and `push-pigeon` when this instance can send notifications. See the list below |

The feature strings:

Expand All @@ -338,6 +339,7 @@ The feature strings:
- `duplicate`: the `duplicate` routes for reminders, embed messages, reaction-role sets, custom commands and shop items.
- `message-templates`: the built-in message templates and the raw message JSON import and export.
- `message-move`: when the channel of a posted **embed message**, the **Welcome channel** message or a **role panel** changes and is published, the server posts a fresh message in the new channel, stores it and then deletes the old one, so the app must not unpublish first. Other bot posts (verification, honeypot traps, applications and so on) are not covered. A publish that loses a race with another publish of the same embed message answers `409` with the current record.
- `update-notice`: the operators' [update notice](#update-notice-operators): `GET /api/v2/update`, and with Wise Wren set up `POST /api/v2/update/wren/approve` and `GET /api/v2/update/wren/runs/:id`. Operators only.
- `app-connect`: [adding the other login](#adding-the-other-login). Only where sign-in is on and both Discord and Fluxer logins are set up.
- `push`, `push-pigeon`: this instance can send notifications to signed-in apps.

Expand Down Expand Up @@ -646,6 +648,77 @@ its account is an operator.
| `GET /api/v2/roadmap/admin` and `POST /api/v2/roadmap/admin[/:id/approve, reject, status, edit, delete]` | Operators only | The roadmap review board |
| `GET /api/v2/account` | Bearer token or session | Includes `operator: true` for an operator |

## Update notice (operators)

Operators also get the update notice (feature `update-notice`): whether a newer Sylo release is out, what
is in it, and, when the instance runs [Wise Wren](https://github.com/Ferdinand99/Wise-Wren), an **Update
now** button. It is the same data as the dashboard's Health page. Everything is operator-only: a server
admin who is not an operator gets `403`, a request without a sign-in `401`. The routes are listed in the
table below. Writes are rate limited (5 approvals a minute, 6 re-checks a minute) and answer
`429 { error }` above that.

`GET /api/v2/update` answers (add `?refresh=1` to check GitHub again now):

```json
{
"enabled": true,
"current": "5.2.0",
"latest": "5.3.0",
"available": true,
"checkedAt": "2026-11-20T10:00:00.000Z",
"checkFailed": false,
"releaseUrl": "https://github.com/Ferdinand99/Sylo/releases/tag/v5.3.0",
"publishedAt": "2026-11-20T09:00:00Z",
"notes": { "version": "5.3.0", "date": "2026-11-20", "url": null, "sections": [
{ "title": "New", "kind": "features", "items": [{ "scope": "dashboard", "text": "Inline markdown, https links only", "refs": [{ "label": "#370", "url": "https://github.com/..." }] }] }
] },
"notesText": null,
"command": "docker compose pull && docker compose up -d",
"wren": null
}
```

- `enabled` is false when the instance runs with `UPDATE_CHECK=off`: there is nothing else to show then.
`available` is true when `latest` is newer than `current`. `checkFailed` is true when the last look at
GitHub failed (`latest` then still holds an earlier answer, if there was one).
- `notes` and `notesText` are only set while `available` is true. `notes` has the same sections as
`GET /api/v2/changelog` (`items[].text` is inline markdown with `https` links only, to render as text,
never as HTML). Release notes that are not in that format come as `notesText`, plain text.
- `wren` is `null` when Wise Wren is not set up. Otherwise it has `configured`, `error` (`null`, or
`{ code, message }` when Wise Wren could not be asked or does not accept Sylo's token), `openMode` (the
dashboard has no login, so Update now is off unless the operator allowed it), `target`
(`{ name, server, status, installedVersion, latestVersion, mode, lastCheckedAt }` or `null`),
`updateSeen` (Wise Wren sees an update), `canApprove`, `whyNot` (the reason when it cannot, in words), and
`latestRun` (the run Sylo last approved, as below, or `null`; Sylo remembers it across its own restart).
While `latestRun` is not `finished`, `canApprove` is false and the page or app should follow that run.
It never has Wise Wren's address, the token or the version key.

`POST /api/v2/update/wren/approve` (no body) asks Wise Wren to update Sylo now and answers
`{ runId, status, from }`, where `from` is the version it started from. It approves exactly the version Wise
Wren shows. Errors are `{ error, code }`: `404` (`wren_off`) when Wise Wren is not set up; `409` when there is
nothing to approve (`not_approvable`), when Wise Wren refuses (`wren_refused`, with Wise Wren's own message:
the version changed, a run is already going, the agent would refuse it), or in open mode (`open_mode`);
`429`; and `502` (`wren_unreachable`, `wren_unauthorized`, `wren_forbidden`, `wren_server`, `wren_invalid`)
when Wise Wren cannot be reached or does not accept Sylo's token. These are never `401` or `403`, which stay
for the operator's own sign-in.

`GET /api/v2/update/wren/runs/:id` answers `{ run }`, where `run` is
`{ id, status, finished, ok, detail, version, createdAt, startedAt, finishedAt, steps: [{ step, status, durationMs }] }`
(`status`: `queued`, `running`, `succeeded`, `rolled_back`, `failed`, `rollback_failed`, `refused`,
`cancelled`, `lapsed`; `finished` is true for all but the first two). A run that is not the Sylo target's
is refused (`404`, or `502` `wren_forbidden` from a token limited to one target). Poll it every few seconds, up to
60 requests a minute.

**Sylo restarts during an update**, so these requests fail for a while (a dropped connection, or `502`/`503`
from a reverse proxy, without a `code`). The app keeps polling; it is done when the run is `finished`, or
when `GET /api/v2/update` (or `GET /api/mobile/info`) reports a `current` / `version` other than `from`.

| Method and path | Auth | Answer |
| --- | --- | --- |
| `GET /api/v2/update[?refresh=1]` | Operators only | The update notice above |
| `POST /api/v2/update/wren/approve` | Operators only | `{ runId, status, from }` |
| `GET /api/v2/update/wren/runs/:id` | Operators only | `{ run }` |

---

## Security notes
Expand Down
44 changes: 44 additions & 0 deletions docs/self-hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,11 @@ At least one platform must be configured.
| `BACKUP_INTERVAL_HOURS` | `24` | Scheduled DB snapshot interval; `0` disables it (pre-migration + manual still run) |
| `BACKUP_RETENTION` | `14` | How many DB snapshots to keep in `<data>/backups` |
| `BACKUP_DIR` | `<db dir>/backups` | Where DB snapshots are written |
| `UPDATE_CHECK` | `on` | The [update notice](#update-notice-and-update-now) for operators: Sylo looks up its newest GitHub release (at most every 6 hours). `off` turns it off and nothing is requested |
| `WISE_WREN_URL` | — | Optional: address of your [Wise Wren](https://github.com/Ferdinand99/Wise-Wren), to update Sylo from the dashboard. Needs the next two as well. `https`, or `http` on your own network |
| `WISE_WREN_TOKEN` | — | A Wise Wren **target token** for Sylo's target (Wise Wren: Settings → Target tokens): it can read and approve only that target. A secret: never shown in the dashboard, never logged |
| `WISE_WREN_TARGET_ID` | — | The id of Sylo's target in Wise Wren (the number in the target page's address) |
| `WISE_WREN_ALLOW_OPEN_MODE` | `false` | Only matters when the dashboard has no login (open mode): then **Update now** is refused, because anyone who can reach the dashboard could use it. `true` allows it anyway |
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
| `LOG_FORMAT` | `text` | `text` or `json` (`LOG_JSON=1` = json) |
| `NODE_ENV` | `development` | Set to `production` in deployment |
Expand Down Expand Up @@ -425,6 +430,45 @@ dated) snapshot from `data/backups/` over `data/sylo.db`. A newer database can't
be opened by an older build — the schema check refuses it — so always roll the
database back together with the code.

### Update notice and "Update now"

The people who run the instance (the operators, `OWNER_IDS` / `FLUXER_OWNER_IDS`) see a small
**Update available** note in the dashboard's top bar when a newer Sylo release is out. It opens the
**Updates** section of the Health page: the new version, its release notes, and the command to copy,
`docker compose pull && docker compose up -d`. Server admins who are not operators see none of this,
and the Sylo app shows the same to operators (see [mobile-app.md](mobile-app.md#update-notice-operators)).

- **How it checks.** Sylo asks `api.github.com` for its latest release, anonymously, when an operator
opens the dashboard, and keeps the answer for 6 hours. Nothing about your instance is sent (GitHub sees your server's address, as for any request). A failed
check is quiet (one log line) and never delays startup. To turn it off completely, set
`UPDATE_CHECK=off`; Sylo then makes no request, and the Health page says the check is off.
- **Updating without the command line.** Sylo itself never gets access to the Docker socket (that would
be root on the host). If you run [Wise Wren](https://github.com/Ferdinand99/Wise-Wren), it can do the
update, and the dashboard gets an **Update now** button:

1. In Wise Wren, make sure Sylo shows up as a target and that the agent's `[updates]` allow list
includes it.
2. In Wise Wren, make a **target token** (Settings → Target tokens) for that target. It can read and
approve that one target and nothing else, so a leaked token cannot update anything else. Use the
token's `ww_…` value below.
3. Set `WISE_WREN_URL`, `WISE_WREN_TOKEN` and `WISE_WREN_TARGET_ID` (all three) and restart Sylo.

Sylo then shows what Wise Wren sees for the target. **Update now** (operators only, after a
confirmation) approves that exact version in Wise Wren, which stops Sylo, takes a snapshot, starts the
new version and rolls back if it does not come up healthy. The Health page follows the run and
reconnects by itself when Sylo restarts. Sylo remembers the run it approved (in its database), so
**Update now** stays off while that run is going, also after the restart. If Wise Wren refuses (the
version changed, a run is already going, the target only notifies), you see Wise Wren's own words.
The token stays on the server: it is never sent to the browser or the app, and never logged. Sylo only
calls three Wise Wren routes, all for the one target: `GET /api/v1/targets/<id>`,
`POST /api/v1/targets/<id>/approve` and `GET /api/v1/runs/<id>`. Without these settings only the notice
and the command are shown.
- **Open mode.** When the dashboard has no login (no `DISCORD_CLIENT_SECRET` or `FLUXER_CLIENT_SECRET`),
everyone who can reach it counts as an operator. **Update now** is refused there (the notice, the
command and what Wise Wren sees are still shown, and Sylo logs a warning at start), because it spends
Sylo's Wise Wren token on behalf of whoever sent the request. Set up a login, or set
`WISE_WREN_ALLOW_OPEN_MODE=true` if you accept that on a network you trust.

### Upgrading to 5.0

Sylo 5.0 removes the classic dashboard. There are no database steps: just upgrade as
Expand Down
22 changes: 22 additions & 0 deletions src/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { dirname, resolve } from 'node:path';
import { resolveSessionSecret } from './lib/sessionSecret.js';
import { normalisePrivateKey } from './lib/appStoreConnect.js';
import { checkPigeonUrl } from './lib/pigeonUrl.js';
import { readWrenSettings } from './lib/wiseWren.js';
import { commandPrefixError } from './lib/commandPrefix.js';

/**
Expand Down Expand Up @@ -242,6 +243,16 @@ if (optionalOrNull('PIGEON_URL')) {
console.error(`[config] PIGEON_URL is not usable (${err.message}); push through Pigeon is off.`);
}
}
// The operators' update notice: Sylo asks GitHub for its newest release (cached, no account, no
// data about this instance is sent). UPDATE_CHECK=off turns it off; nothing is requested then.
const updateCheck = !/^(0|false|no|off)$/i.test(process.env.UPDATE_CHECK?.trim() ?? '');
// Optional: Wise Wren (https://github.com/Ferdinand99/Wise-Wren) updates this instance from the
// dashboard's "Update now". All three settings are needed; the token is a secret.
const { settings: wiseWren, problem: wiseWrenProblem } = readWrenSettings(process.env);
if (wiseWrenProblem) console.error(`[config] ${wiseWrenProblem}`);
// Without a dashboard login nobody is signed in, so "Update now" would be open to everyone who can reach
// the dashboard. It is refused there unless this says it is wanted anyway.
const wiseWrenAllowOpenMode = optionalBool('WISE_WREN_ALLOW_OPEN_MODE', false);
const kickClientSecret = optionalOrNull('KICK_CLIENT_SECRET');
// Signs session cookies and short-lived tokens (e.g. verification links), so it
// must always exist. SESSION_SECRET wins; otherwise a generated secret is kept in
Expand Down Expand Up @@ -370,6 +381,10 @@ export const config = Object.freeze({
pushRelayUrl,
// Postal Pigeon (see above); null = off.
pigeonUrl,
// The update notice (see above), and Wise Wren's address, token and target id (null = off).
updateCheck,
wiseWren,
wiseWrenAllowOpenMode,
// URLs that server admins type in (RSS feeds, the welcome card background) are fetched by
// the server, so private, loopback and link-local addresses are refused (src/lib/safeFetch.js).
// A self-hosted instance that wants feeds from its own network can allow them.
Expand Down Expand Up @@ -408,3 +423,10 @@ export const config = Object.freeze({
// Misc
nodeEnv: optional('NODE_ENV', 'development'),
});

if (config.wiseWren && !config.authEnabled && !config.wiseWrenAllowOpenMode) {
console.error(
'[config] Wise Wren is set up, but the dashboard has no login (open mode), so "Update now" is off: ' +
'anyone who can reach the dashboard could use it. Set up a login, or set WISE_WREN_ALLOW_OPEN_MODE=true to allow it.'
);
}
Loading
Loading