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.

Dataset documentation cards#

When repertoireUrl is set, the /docs page’s docs.mdx can list the datasets from Repertoire service discovery with the <DatasetDocsCards> component instead of hand-written cards. Each card shows the dataset’s name and discovery description, and links to its discovery docs_url when it has one. When repertoireUrl is not set, the component renders nothing. See Dataset documentation cards.

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. To link to it from MDX content, use <ServiceLink service="comanage" /> (see Service links). 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

This page was last modified on .