Configuration reference

Squareone is configured at runtime through a YAML configuration file. The path for this configuration file is set by the SQUAREONE_CONFIG_PATH environment variable in production, and defaults to squareone.config.yaml in development. This page documents the schema of that configuration file.

Defaults from service discovery

siteName, environmentName, and baseUrl are optional. When one is omitted (or set to an empty string), Squareone fills it in at request time from Repertoire service discovery, so these keys no longer need to be set for each Phalanx environment. An explicitly configured value always takes precedence.

Key	Default from service discovery	Fallback
siteName	environment.title (for example, US Rubin Science Platform)	Rubin Science Platform
environmentName	environment.label, the Phalanx environment name (for example, idfprod)	unknown
baseUrl	services.ui.squareone.url, with the trailing slash removed (for example, https://data.lsst.cloud)	The origin of the request, from its X-Forwarded-Proto (default http), X-Forwarded-Host, and Host headers

Service discovery is only consulted when repertoireUrl is set and at least one of these keys is omitted. The fallback applies when repertoireUrl is unset, when the Repertoire API is unavailable (Squareone logs a warning but still serves pages), or when the Repertoire release predates 3.0.0 and so does not provide the environment metadata or the squareone UI service.

The resolved values are used everywhere the keys are: page titles, the Sentry environment and base URL (shown on the /admin/sentry page), and absolute URLs such as notification permalinks.

Server-side Sentry follows the same environmentName resolution, so events from the server and the browser carry the same Sentry environment. The server resolves it once at startup, before it serves any requests: it waits at most a few seconds for service discovery, and if the Repertoire API doesn’t respond in time it logs a warning and uses the unknown fallback. The server no longer reads the SQUAREONE_ENVIRONMENT_NAME environment variable.

Apps menu

Setting enableAppsMenu to true adds an Apps menu to the header. Its items are derived from Repertoire service discovery and the user’s scopes, so they don’t need to be listed for each Phalanx environment:

1. Times Square (/times-square/), when the times-square application is enabled.

2. Each of the following UI services that discovery lists and that the user can access, labelled by the service’s discovery title (or its name, if it has no title), in this order:

   Service	Associated scopes
   argocd	exec:admin
   chronograf	exec:admin
   kafdrop	exec:internal-tools
   webdav	write:files

   A service’s required_scopes from discovery (Repertoire 3.0.0 and later) decide who can access it. When discovery declares none, as for Argo CD and Chronograf, which have their own logins, the user needs the associated scopes above instead, so that these tools are not advertised to every user. These items appear only once the user’s scopes are known: anonymous visitors don’t see them.

3. The configured appLinks.

appLinks are additive extras for apps that service discovery does not describe (for example, a deployment-specific tool). They are shown to every user, regardless of scopes. A link whose href repeats an earlier item is dropped; relative hrefs are resolved against the site’s origin (the squareone UI service URL from discovery, or else the resolved baseUrl) and trailing slashes are ignored when comparing, so an appLinks entry of /argo-cd/ does not duplicate the discovered Argo CD item. Links for services now derived from discovery can be removed from appLinks, though an entry that stays is still shown to users who can’t see the discovered item.

The menu is hidden when it has no items. When repertoireUrl is not set, the menu lists only the appLinks.

Deprecated keys

coManageRegistryUrl

The COmanage registry URL is available from Repertoire service discovery as the services.ui.comanage UI service, so Squareone no longer reads this key. It is still accepted so that existing configurations continue to validate, and can be removed from them.

semaphoreUrl

The Semaphore URL is resolved from Repertoire service discovery through repertoireUrl, so Squareone no longer reads this key. It is still accepted so that existing configurations continue to validate, and can be removed from them.

Schema

Squareone Configuration

Publicly-viewable configuration for a Squareone instance.

squareone.config.schema.json
type	object
properties
siteName	Site name
	Used as the basis of the HTML title tag and the homepage hero. Optional: when omitted, defaults to the environment title from Repertoire service discovery (environment.title), or to Rubin Science Platform when discovery is unavailable or predates Repertoire 3.0.
	type	string
siteDescription	Site description
	Used as the default site description in the HTML meta..
	type	string
	default	Welcome to the Rubin Science Platform
baseUrl	Base URL for the public ingress
	Used for computing absolute URLs. Does not end in /. Optional: when omitted, defaults to the Squareone UI service URL from Repertoire service discovery (services.ui.squareone.url, trailing slash removed), or else to the origin of each request, derived from its X-Forwarded-Proto, X-Forwarded-Host, and Host headers.
	type	string
environmentName	Phalanx environment name
	Used in telemetry (the Sentry environment). Optional: when omitted, defaults to the Phalanx environment label from Repertoire service discovery (environment.label, such as idfprod), or to unknown when discovery is unavailable or predates Repertoire 3.0.
	type	string
docsBaseUrl	Base URL for the user documentation site.
	Used for computing URLs for user documentation pages for this RSP instance. The default is for the public RSP. For USDF, use https://rsp.lsst.io/v/usdfprod. Does not end in /.
	type	string
	default	https://rsp.lsst.io
semaphoreUrl	Semaphore URL
	Deprecated: use Repertoire service discovery instead. The Semaphore URL is now resolved via repertoireUrl, so this field is no longer read by the app. It is retained only for backwards compatibility so existing Phalanx configurations that still set it continue to validate. Does not end in /.
	type	string
repertoireUrl	Repertoire API URL
	URL prefix of the Repertoire service discovery API. Does not end in /. Omit or set as null to disable service discovery.
	type	string
timesSquareUrl	Times Square API URL
	URL prefix of the Times Square API service. Does not end in /. Omit or set as null to disable the /times-square/ pages.
	type	string
coManageRegistryUrl	COmanage registry URL
	Deprecated: the COmanage registry URL (e.g. https://id.lsst.cloud) is available from Repertoire service discovery as services.ui.comanage, so this field is no longer read by the app. It is retained only for backwards compatibility so existing Phalanx configurations that still set it continue to validate.
	type	string
plausibleDomain	Plausible tracking domain
	Domain (e.g. data.lsst.cloud) for Plausible tracking. Omit to disable Plausible.
	type	string
mdxDir	MDX content directory
	Directory path where MDX content files are located. Can be relative (development) or absolute (production with ConfigMap).
	type	string
	default	src/content/pages
footerMdxPath	Footer MDX content path
	Path to MDX file for footer content, relative to mdxDir. If not provided, uses default hardcoded footer content.
	type	string
	default	footer.mdx
sentryTracesSampleRate	Sentry traces sample rate
	The percentage of traces to send to sentry. A number between 0 and 1 inclusive, where zero means don’t send any traces, and 1 means send all traces.
	type	number
sentryReplaysSessionSampleRate	Sentry replay session sample rate
	The percentage of replay sessions to send to Sentry. A number between 0 and 1 inclusive, where zero means don’t send any sessions, and 1 means send all sessions.
	type	number
	default	0.0
sentryReplaysOnErrorSampleRate	Sentry error replay session sample rate
	The percentage of replay sessions to send to Sentry when an error occurs. A number between 0 and 1 inclusive, where zero means don’t send any sessions, and 1 means send all sessions.
	type	number
	default	1.0
sentryDebug	Sentry debug
	Setting this option to true will print useful information to the console while you’re setting up Sentry.
	type	boolean
	default	False
sentryOrg	Sentry organization slug
	Sentry organization slug used to build the Sentry dashboard link on the admin page. The dashboard link is shown only when both sentryOrg and sentryProject are set.
	type	string
	default	rubin-observatory
sentryProject	Sentry project slug
	Sentry project slug used to build the Sentry dashboard link on the admin page. The dashboard link is shown only when both sentryOrg and sentryProject are set.
	type	string
	default	squareone
enableAppsMenu	Enable the Apps menu
	Setting this option to true enables the Apps menu in the header. The menu lists Times Square (when the times-square application is enabled in Repertoire service discovery), the Argo CD, Chronograf, Kafdrop, and WebDAV UI services from service discovery that the user’s scopes allow, and then any appLinks. The menu is hidden when it has no items.
	type	boolean
	default	False
appLinks	Application links
	Additional links appended to the Apps menu after the items derived from Repertoire service discovery, for apps that discovery does not describe. A link whose href repeats an earlier item is dropped. These links are shown to every user, regardless of scopes. Without service discovery (no repertoireUrl), the Apps menu lists only these links.
	type	array
	default
	items	type	object
		properties
		label	Display label for the link
			type	string
		href	URL or path for the link
			type	string
		internal	Whether this is an internal route or external URL
			type	boolean
showPreview	Show preview badge
	Whether to show the preview badge on the homepage hero
	type	boolean
	default	False
previewLink	Preview badge link URL
	URL for the preview badge link
	type	string
	default	https://rsp.lsst.io/roadmap.html
enableUserNotifications	Enable user notifications
	Setting this option to true enables the user-facing notifications UI: the unread badge in the header user menu and the /notifications inbox and detail pages. Defaults to false so the feature stays hidden until it is released.
	type	boolean
	default	False
userNotificationsPollIntervalSeconds	User notifications poll interval (seconds)
	Background polling cadence, in seconds, for the unread notification count shown in the header user menu. Consumed by the useUnreadNotificationCount hook (converted to milliseconds for TanStack Query’s refetchInterval). Only relevant when enableUserNotifications is true.
	type	integer
	minimum	30
	default	300
adminPageScopes	Admin page scopes
	Maps each admin page to the Gafaelfawr scopes that grant access to it. A user may use a page when they hold any of the scopes listed for it; configuring an empty list hides the page from everyone. Page ids are fixed by the application, so an unrecognized id is a configuration error. Omit this key — or any individual page within it — to use the defaults shown below, which match Gafaelfawr’s out-of-the-box admin scopes. This mapping controls the admin sidebar navigation, the page each user lands on from /admin, and the in-page authorization gate; it does not change the order of the navigation or which admin pages exist.
	type	object
	default	notifications	admin:notifications
		serviceTokens	admin:token
		oidcClients	admin:oidc
		sentry	exec:admin
	properties
	notifications	Scopes for the user-notifications admin page
		Scopes granting access to /admin/notifications, which sends user notifications through Semaphore.
		type	array
		default	admin:notifications
		items	type	string
	serviceTokens	Scopes for the service-tokens admin page
		Scopes granting access to /admin/service-tokens, which manages Gafaelfawr service tokens.
		type	array
		default	admin:token
		items	type	string
	oidcClients	Scopes for the OpenID Connect clients admin page
		Scopes granting access to /admin/oidc-clients, which manages Gafaelfawr’s OpenID Connect clients.
		type	array
		default	admin:oidc
		items	type	string
	sentry	Scopes for the Sentry admin page
		Scopes granting access to /admin/sentry, which links to the Sentry dashboard and exercises error and log reporting.
		type	array
		default	exec:admin
		items	type	string
headerLogoUrl	Header logo URL
	HTTPS URL to an external logo image. Takes priority over headerLogoData if both are set. If neither URL nor data is provided, uses the default Rubin Observatory logo. When using this option, headerLogoWidth must also be provided.
	type	string
	pattern	^https://
headerLogoData	Header logo base64 data
	Base64-encoded image data (without the data URL prefix). Must be used together with headerLogoMimeType and headerLogoWidth. Used only if headerLogoUrl is not provided.
	type	string
headerLogoMimeType	Header logo MIME type
	MIME type for the base64-encoded logo data (e.g., ‘image/png’, ‘image/jpeg’, ‘image/svg+xml’). Required when headerLogoData is provided.
	type	string
	enum	image/png, image/jpeg, image/jpg, image/svg+xml, image/webp, image/gif
headerLogoHeight	Header logo height
	Height of the header logo in pixels.
	type	number
	minimum	1
	default	50
headerLogoWidth	Header logo width
	Width of the header logo in pixels. Required when using headerLogoUrl or headerLogoData to ensure correct aspect ratio.
	type	number
	minimum	1
headerLogoAlt	Header logo alt text
	Alternative text for the header logo for accessibility.
	type	string
	default	Logo
additionalProperties	False