Restarting the Server

Some settings only take effect after the Athena server restarts — and a finished SQLite-to-PostgreSQL migration needs a restart to switch databases. Instead of opening a shell on the host, an administrator can click Restart server in the console or call one REST endpoint. Athena records who asked, stops cleanly, and the supervisor that runs it starts it again — on the virtual appliance, the appliance supervises Athena itself.

On the appliance you can also restart Athena from Settings → Appliance → Power (Restart Athena) or from the VM console menu, 7) Restart Athena services. Reboot and shutdown of the whole appliance are console items 11 and 12.

How a restart works#

Athena cannot relaunch itself. A restart is a graceful stop that the process supervising Athena turns into a fresh start:

1. The request is written to the audit log (who, when, and from which IP address) before anything stops.
2. The caller gets an answer straight away, and about 1.5 seconds later the server begins a normal, clean shutdown.
3. The supervisor sees the server exit and starts it again. Agents and browsers reconnect on their own when it is back.

Because of this, Athena only offers the restart when it can tell that something will start it again. Where it can't, the console tells you to restart the server manually instead (see Supported supervisors).

Restarting from the console#

The Restart server button appears in three places:

To restart:

1. Click Restart server.
2. A confirmation titled Restart the server? explains that the server stops for a few seconds and starts again, that agents and browsers reconnect automatically, and that anything running in the server is interrupted. Click Restart server to go ahead, or Cancel.
3. The button is replaced by “Restarting the server... this page reconnects when it is back.” While the server is down the page shows its usual reconnecting overlay, then picks up again once the server is back.

If you see the text “Restart the server manually to apply changes.” where the button would be, either your account does not have the settings.manage permission, or no supervisor was detected for this server.

Supported supervisors#

Athena checks for a supervisor once, when it starts. The first match wins:

When nothing matches — for example, the server was started by hand from a console window — the restart is not offered in the console and the REST endpoint answers 409 Conflict.

Overriding detection: Server:RestartSupported#

Use this setting when the automatic check gets it wrong. It works both ways:

• true — offer the restart even though no supervisor was detected. Use it when something Athena can't see restarts it, such as NSSM, a scheduled task, a PowerShell loop or your own watchdog.
• false — never offer the restart, even under a detected supervisor. Use it when, for example, the supervisor does not start the server again after a clean exit and a stop would leave the server down.
• Not set (the default) — use automatic detection.

Set it in appsettings.json / appsettings.local.json, or as an environment variable (double underscore for the colon). The setting is read at startup, so restart the server by hand once after changing it. See Configuration.

// appsettings.local.json
{
  "Server": {
    "RestartSupported": true
  }
}

# Environment variable
Server__RestartSupported=false

Restarting through the REST API#

Scripts and automation can call the same restart that the button uses. It needs a signed-in account with the settings.manage permission and takes no request body.

curl -k -X POST -H "Authorization: Bearer <token>" \
  https://athena.example.com:8443/api/system/restart

A successful call returns the supervisor that will start the server again:

{
  "success": true,
  "message": "Server is restarting",
  "data": { "restarting": true, "supervisor": "container" }
}

When no supervisor is detected, nothing is stopped and the call returns 409 with "success": false and the message: “This server cannot restart itself: no supervisor (container, systemd, Windows service) was detected. Restart the server manually, or set Server:RestartSupported=true if a supervisor does restart it.”

To wait for the server to come back, poll the anonymous GET /health endpoint until it answers again (see Server Health & Monitoring), then sign in again for a new token.

Audit trail#

Each restart leaves a sequence of events in the audit log:

A refused request (no supervisor) is not audited, because nothing happens. See the Audit Event Types Reference for every event type.