Who can use this

System Maintenance

The Maintenance tools let you reconfigure the running Grengin deployment without leaving the Control Hub. From here you can change the address (domain) your platform is served on and reissue its TLS certificate, and you can update the installed application to a new version. Both are powerful, host-level operations, so the page guides you through safety checks and asks you to confirm before anything runs.

Who can use this

You need the Maintain System permission, which is always granted organization-wide. To reach the page you also need the View Analytics permission, granted organization-wide.

Find it under Control Hub → System Metrics → Maintenance tab.

  • If you don’t have the Maintain System permission, the Maintenance tab doesn’t appear at all, and you’ll only see the metrics charts.
  • If your permission is removed while you’re on the tab, the screen automatically returns you to the Metrics view.

What you’ll see first

When you open the Maintenance tab, the platform runs a quick readiness check before showing you any controls.

  • While it checks, you’ll see a spinner and a “checking” message.
  • When it finishes, a banner at the top shows whether the host has the privileges needed to make changes, displayed as two status chips: whether the platform is running as root and whether sudo is available.
  • Use Recheck at any time to run the readiness check again.
  • Expand Advanced details in the banner to see a per-tool breakdown of what is and isn’t available, and why.

If the host has neither root nor sudo privileges, you’ll see a warning, and both maintenance cards below are shown greyed-out and disabled with a short note explaining why. The same happens for an individual card if its underlying tool isn’t installed. Once a change succeeds, the readiness check refreshes automatically so availability stays accurate.

Changing the domain and TLS certificate

Use the Domain & TLS card to change the address your platform is served on and to (re)issue its certificate.

To change the domain:

  1. In Domain, enter the hostname or fully-qualified domain name. Enter the bare host only, with no http:// or https:// prefix, no slashes, and no spaces.
  2. Choose an SSL mode:
    • Let’s Encrypt (the default) — requests a trusted certificate automatically.
    • Self-signed — generates your own certificate.
    • None — serves without TLS. You’ll see a warning; this is not recommended.
  3. Fill in the fields that appear for your chosen mode (see below).
  4. Click Apply.
  5. A confirmation dialog opens. To proceed, type the exact domain name you entered, then confirm. The action can’t be confirmed until the typed value matches.

Mode-specific fields:

  • Let’s Encrypt — Enter a contact Email, then acknowledge the three prerequisite checkboxes confirming your DNS, ports, and proxy are ready. Apply stays disabled until all three are checked.
  • Self-signed — Set the certificate validity in days (a whole number, 1 or more; defaults to 365).
  • None — No fields; just an informational warning.

After the domain change

Because changing the domain can restart the service and move you to a new address, the card shows an inline panel that checks whether the new address is reachable:

  • You’ll see a checking state while it probes, then a success or timeout result, plus a note that your current session may be affected.
  • On success, choose Go to new address to continue at the new origin.
  • On a timeout, choose Retry check, or Open anyway to navigate there manually.

Updating the application

Use the Application Updates card to pull and install new versions of the platform’s components.

To run an update:

  1. In Version, enter latest (the default) or a specific version tag such as v1.2.3.
  2. Choose which components to update using the toggles:
    • Update API (on by default)
    • Update webapp (on by default)
    • Update installer (off by default) At least one of these must be on before you can run the update.
  3. Leave Verify checksums on (recommended). Turning it off shows a warning.
  4. Adjust optional settings if you need to (see below).
  5. Click Update.
  6. A confirmation dialog opens. Type CONFIRM to proceed.

Optional settings:

  • Release base URL — Leave blank to use the host’s built-in release source. If you set it, it must be a valid https:// URL.
  • Architecture — Leave on auto-detect, or choose x86_64 or aarch64 explicitly.
  • API service name — Hidden behind an Advanced disclosure. Leave blank unless you’ve customized the service name.

After an update

  • If you updated the webapp, the app reloads itself to pick up the new version.
  • If you updated only the API, the panel waits and checks until the service comes back online (up to about two minutes). If it doesn’t respond in that window, the panel quietly returns to idle and you can re-check manually.
  • When the update finishes, the new version is shown.

Reviewing run output

Every maintenance run produces an output console showing whether it succeeded or failed, the platform’s status message, and any captured output. If nothing was produced, you’ll see a “no output captured” note.

  • Use Copy log to copy the output to your clipboard.
  • Expand Script details to see the underlying tool path.

A View audit logs link at the bottom of the tab takes you to the full audit trail.

Good to know

  • Both actions run synchronously and can briefly interrupt the service. Background metrics polling is paused during a run so it doesn’t interfere with a restart.
  • A dropped connection usually means it worked. A privileged restart can cut off the request in progress. When that happens, the platform treats the change as “probably applied” and moves you into the readiness/verify flow rather than reporting a failure.
  • A reported failure keeps your form open. If a run completes but reports that it didn’t succeed, the form stays open and the output console shows the details so you can investigate.
  • The confirm dialog locks while a run is in flight. You can’t dismiss it with Escape or by clicking the backdrop, and its fields are disabled until the run finishes.
  • Apply and Update enable differently from form validity. For Let’s Encrypt, Apply stays disabled until all three prerequisite checkboxes are acknowledged. Update stays disabled until at least one component target is selected.
  • Privilege gates the forms, not just the action. Without root or sudo on the host, both cards are disabled no matter what.