A self-hosted Trace.Space installation can host many organizations. System administration is the area above all of them, where a system admin creates organizations, sees their members, and configures the email server. On the hosted service this area is run by Trace.Space; this article is for teams who run their own installation.
Who is a system admin
A system admin is a user account with a flag that applies to the whole installation, not to one organization. System admins see a System administration entry in the settings menu at the top of the left sidebar, and can open /system-administration directly. Anyone else who opens that address sees an access denied page.
Being a system admin does not by itself make you an admin of any organization. Organization roles are still granted per organization; see Managing users.
How the first system admin is created
When the auth service starts and finds no system admin, it creates one from the SYSTEM_ADMIN_EMAIL environment variable:
If no user with that email exists yet, a user and a Default Organization are created, and the user becomes system admin and admin of that organization.
If the user already exists, they are granted system admin.
Set the variable before the first start. Afterwards, sign in with that email using any sign-in method your installation offers (a magic link works well because it needs no external identity provider, only a working email server) and grant further system admins from the UI as described below.
Organizations
System administration opens on the Organizations page: a table of every organization with its Name and Domain Name, and a Search box that matches either.
Creating an organization
Click Create organization.
Enter a Name (the display name) and a Domain Name, the unique identifier: lowercase letters, digits and underscores only, and not already in use.
Click Create.
The domain name is permanent. It names the organization's own database, appears in app URLs and is the value integrations pass in the Target-Organization header. You, the creating system admin, are added to the new organization as its org admin, so you can open it and invite the first members.
An organization created here starts empty. Sample data is optional: the create call on the auth API accepts withSampleData=true to seed the sample project instead, but the dialog does not offer it. Organizations that people create by signing up themselves always get the sample project. See Sample set.
Opening an organization
Click an organization's name, or ... > Open. The page shows the name and domain name, a Delete button, and a Members table with each member, when they joined (or Pending invite... / Suspended), their last login, and a System admin column.
Granting and revoking system admin
In the System admin column, click Grant next to a member to make them a system admin, or Revoke to remove it. The change applies immediately across the installation. Keep at least two system admins so that one leaving does not lock the area.
Deleting an organization
Click Delete, type the organization's name to confirm, then click Delete again. This removes the organization, drops its database with every item, trace, baseline and comment in it, and detaches all its members. It cannot be undone, and there is no export step built in, so export anything you need first.
Email server
Email server in the left sidebar configures the SMTP server that sends invitations, magic links and notification emails.
Fill in SMTP Host, Port, Username, Password, Sender email (the From address), Sender name and the Enable SSL/TLS switch, then click Save. The password is encrypted at rest; when you come back the field shows dots, and leaving it untouched keeps the stored password.
Once a host and port are saved, a Test section appears. Test connection checks that the server accepts a connection with the saved settings. Enter an address and click Send test email to check the whole path; a green Test email sent confirms it, and a failure shows the server's error message.
Templates, identity providers and integrations
The Templates page is a placeholder for sharing item type and picklist configurations across organizations; it does nothing yet. Two further pages, at /system-administration/identity-providers and /system-administration/system-integrations, are not in the sidebar. They state that Google, Microsoft and GitHub sign-in and the system-wide Jira and GitHub apps are configured through environment variables only.
Upgrades
Some releases change database projections and require a rebuild step after the new version is deployed. Those steps, with the exact endpoints to call, are listed in the release notes for operators under each version's deployment notes. Read them before every upgrade; the projection endpoints require a system admin token.