v7.0.0 — Go Uptime

jniltinho/gatus is now Go Uptime

The project has a name of its own: go-uptime. It derives from Gatus, by TwiN, has
been developed independently since v6.0.0, and keeps the Apache-2.0 license and the credit to the original project
(NOTICE, and the "Origin and license" section of the README). Nothing else about how it works changes in this release.

	before	now
Repository	jniltinho/gatus (redirects)	jniltinho/go-uptime
Image	jniltinho/gatus:v6.3.0 (stays available)	jniltinho/go-uptime:v7.0.0
Binary and tarballs	gatus, gatus_<version>_linux_<arch>.tar.gz	go-uptime, go-uptime_<version>_linux_<arch>.tar.gz
Environment	GATUS_CONFIG_PATH, GATUS_LOG_LEVEL, GATUS_DELAY_START_SECONDS	GO_UPTIME_* (the old names still work)

Upgrading from v6: read this first

The only required change in Docker is the name of the image. There is no database migration, and the configuration
file is the same. Full guide: docs/migrating-from-gatus.md.

-    image: jniltinho/gatus:v6.3.0
+    image: jniltinho/go-uptime:v7.0.0

Keep the name of your service, your volume and your database as they are.

What keeps working: the GATUS_* variables (with a warning in the log), an entrypoint or healthcheck that calls
/gatus (a symbolic link in the image), backups made on v6 (in clear or encrypted, through the API and the screen), the
preferences stored in each browser, and docs/manager-gatus.py with --gatus-url and GATUS_URL.

What is incompatible, and the way out of each:

• Prometheus: the metrics are now go_uptime_*. Add metrics-namespace: gatus to keep the names of v6 exactly.
• User-Agent of the checks: go-uptime/1.0 instead of Gatus/1.0. Allow it if a firewall or WAF filters by it.
• Everybody signs in once more: the session cookie was renamed.
• The image no longer sets GATUS_CONFIG_PATH and GATUS_LOG_LEVEL. Only matters if your YAML expands
  ${GATUS_LOG_LEVEL} or ${GATUS_CONFIG_PATH} counting on the value of the image: set the variable in your compose.
• JSON badge (badge.shields): the label is go-uptime; add &label=… to the shields.io URL to choose another.
• Linux with systemd: the binary is go-uptime. Either stay in /opt/gatus and swap the binary (one symlink), or
  move to /opt/go-uptime, which needs storage.path and the paths of the unit edited. Both are in the guide.
• Going back: v6 runs over the same database, but cannot read a backup made by v7. Keep one made on v6.

What does not change, on purpose: the identifiers that other systems use to find, close or filter alerts — the
Opsgenie alias, the Squadcast and SIGNL4 ids, the title of the GitHub and Gitea issues (alert(gatus): …), the Home
Assistant event gatus_alert, the default Zulip topic, and the source fields of Datadog, New Relic, PagerDuty, Splunk
and GitLab. An alert opened by v6 is still closed by v7. The visible text of the notifications now says Go Uptime.

Also in this release

• metrics-namespace: the prefix of the Prometheus metrics (default go_uptime).
• alerting.homeassistant.event-type: the event fired in Home Assistant (default gatus_alert).
• The images carry LICENSE and NOTICE, and the tarballs NOTICE.
• The example of the administration (.examples/docker-compose-admin) was missing its config.yaml since v6.1.0.
• The Go module is github.com/jniltinho/go-uptime/v7. go install still does not work (local replace directives).

Install

docker pull jniltinho/go-uptime:v7.0.0

Linux binaries for amd64 and arm64 are attached below; see
docs/install-linux.md. The upgrade from the
published jniltinho/gatus:v6.3.0 was tested with test/e2e/upgrade.sh before the tag: same database, same port, the
GATUS_* variables of a v6 installation, a browser with a v6 session and v6 preferences, and v6 backups.

Full changelog: v6.3.0...v7.0.0

v6.3.0

Highlights

Configurable number of endpoints per status page

A status page used to show at most 200 endpoints, a fixed number. It is now an option, and the default is 400:

status-pages:
  maximum-endpoints-per-page: 400   # 1 to 1000

• A page that selects more endpoints than the limit stays published and shows the first ones in display order (featured
  endpoints, then the sections), with the notice "Showing the first N services", where N is now the real number.
• The administration marks a truncated page in the listing (400+), warns when validating the page, and the preview
  shows the same notice. A restore warns about it too.
• gatus config validate refuses a value out of bounds or that is not an integer (0, 1001, 2.5).
• A definition accepts up to 1000 keys in endpoints (it was 200), whatever the limit in force.
• The cache of the public payloads now has a memory budget of 128 MiB, on top of its 1000 entries.

Read before upgrading

• The limit is an access rule. An endpoint beyond the cut is not served by the page at all: its details, chart,
  event stream and badges answer 404. With the default going from 200 to 400, a page that was truncated at 200 now
  publishes up to 200 more endpoints. If that is not what you want, set maximum-endpoints-per-page: 200.
• Going back to v6.2.0 or older: the older version ignores the option, shows 200 endpoints per page and refuses any
  definition with more than 200 keys in endpoints. A managed page like that stops being published, and a page of the
  configuration file like that keeps Gatus from starting. Bring those pages down to 200 keys first.

Measured with 1000 endpoints and 50 results each: a payload of about 4 MiB (under 40 KiB with gzip), assembled in about
20 ms. In the browser, use groups-collapsed: true on pages with many hundreds of endpoints: 275 DOM nodes instead of
70,000. See docs/status-pages.md.

Default logo, ui.logo: none and the login card

• Without ui.logo, the header of the dashboard, the header of the public status pages and the login cards now show the
  logo embedded in Gatus (/logo-192x192.png). This is visible after the upgrade: to keep the header without a
  logo, set ui.logo: none. A URL in ui.logo works as before.
• The login card now sits at 10% of the height of the window (it was 15%).

Upgrade

docker pull jniltinho/gatus:v6.3.0

Linux binaries for amd64 and arm64 are attached below; see
docs/install-linux.md. The in-place upgrade from
v6.2.0 was tested with test/e2e/upgrade.sh before the tag: endpoints, status pages, push keys, sessions and history
are kept. There is no database migration in this release.

Full changelog: v6.2.0...v6.3.0

v6.2.0

v6.2.0

A third theme for the interface, bio, next to dark and light.

Image: jniltinho/gatus:v6.2.0 (linux/amd64, linux/arm64)

The bio theme

A light theme in teal, blue and navy, with a navy header — the palette the logo has used since v6.0.2. It covers every
screen: the dashboard, the details pages, the administration, the public status pages and the login screen.

• Each visitor picks a theme with the new theme selector, which replaces the button that toggled between dark and
  light: in the header of the public pages, in the settings bar at the bottom left of the dashboard, and on the login
  screen. It shows the theme in use, opens a menu with the three themes and works with the keyboard. The choice is
  remembered in the browser, as before.
• ui.default-theme: dark | light | bio sets the theme of a visitor who has not chosen one. It is optional:
  without it, ui.dark-mode keeps deciding between dark and light, and the default is still dark. When both are set,
  ui.default-theme wins and the log says so. Any other value makes the configuration invalid, which
  gatus config validate reports.
• The page comes from the server already in the right theme, so it does not flash another one while loading.

See the two screens in docs/screenshots.

Nothing changes unless you ask for it

Upgrading without touching the configuration keeps the dark theme, and the dark and light choices that visitors
already made keep working. The dark and the light themes were checked element by element, on 24 screens and states,
before and after the change: no existing element changed colour. The status colours (up, down, pending, no data) are
the same in the three themes.

For whoever customises or sits in front of Gatus

• ui.custom-css keeps working in the three themes. It is loaded before the stylesheet of the application, as it
  always was: to override a variable of a theme (:root, :root.dark, :root.theme-bio), use !important or a more
  specific selector. This is now in the documentation of ui.custom-css.
• HTML pages now go out with Cache-Control: no-cache and Vary: Cookie, because the theme they carry depends on
  the theme cookie. The pages of the dashboard had no cache policy before. Pages that require a login keep
  private, no-store. A cache in front of Gatus now keeps one copy of an HTML page per cookie, and revalidates it.
• data-default-theme of <html> now carries the name of the default theme (light instead of an empty value).

For developers

• The rule that picks the theme lives in three places — the server, the inline script of index.html and theme.js —
  and the three are tested with one table of cases, web/app/src/utils/theme.cases.json.
• test/e2e/theme-colors.sh compares the computed colours of every element between two versions of the frontend, and
  with --contrast measures every text of the bio theme: 859 texts, none below the minimum and worse than in the light
  theme.
• The Tailwind gray scale goes through CSS variables so that a theme can tint it; a gray that means a status uses
  statusgray. See "Themes" in AGENTS.fork.md.
• test/e2e/upgrade.sh passes from v6.1.0 to v6.2.0 (29 checks).

Assets: gatus_6.2.0_linux_amd64.tar.gz and gatus_6.2.0_linux_arm64.tar.gz

v6.1.0

v6.1.0

Collapsible groups on the public status pages, a stricter check of the password hash, and an example configuration that
shows how to turn the administration on.

Image: jniltinho/gatus:v6.1.0 (linux/amd64, linux/arm64)

Collapsible groups on the status pages

The header of every group of a public status page is now a button that collapses and expands its endpoints, with the
mouse, Enter or Space. Collapsed or not, the header shows the status of the group and how many of its endpoints are in
each state (3 up, 2 up · 1 down), so a collapsed group still answers "is it fine?".

• A group with a problem is always expanded. Not operational, or still without data: it opens, whatever the page or
  the visitor chose. A visitor may collapse it during an incident, but the next refresh opens it again.
• groups-collapsed: true, a new option of a page (off by default), makes the operational groups start collapsed.
  In the administration it is the checkbox "Start with the groups collapsed".
• The choice of a visitor is remembered in their browser, per page and per group, and comes back when a group
  recovers from an incident. No group name is stored, only a hash, because a page can require a login.
• The page refreshes every 60 seconds over a payload cached for 30, as before: a group that starts failing opens on the
  next refresh. Its collapsed header already shows the new status and counts.

See docs/status-pages.md.

For API clients

GET /api/v1/status-pages/{slug} has two new fields: groupsCollapsed on the page and summary on each group
(total, up, down, pending, unknown, counting the endpoints listed in the group; featured endpoints are listed
in no group). Nothing was removed. A client that rejects unknown fields has to learn them.

Before going back to an older version

A version before v6.1.0 does not know groups-collapsed, and what it does depends on where the page lives:

• a page managed through the web that has the option becomes invalid and stops being published (404). Untick
  "Start with the groups collapsed" on those pages before going back, and do not restore on an older version a backup
  made with the option on;
• a page of the configuration file keeps working: the older version ignores the option, and the page opens expanded.

Fixed

• gatus config validate accepted a password that is not a bcrypt hash, and the server then panicked at startup.
  With security.basic.password-bcrypt-base64 set to a plain password or to a placeholder, the validation said "valid"
  and the start ended in a stack trace (illegal base64 data). The value is now checked when the configuration is
  validated: Error: ... invalid security configuration, status 1, which is also what the ExecStartPre of the systemd
  unit relies on. A working installation is not affected: with such a value the server never started.

Example configuration

• The default config.yaml shows the newer options (groups-collapsed, show-certificate-expiration, show-messages,
  the login of a page, a Push endpoint, ui.logo) and carries, commented out, the minimum to turn the administration
  on: a SQL storage, a login and admin.enabled. With those three blocks the file does not even need endpoints.
• .examples/docker-compose-admin is a
  Docker Compose setup with nothing else. It ships with a placeholder instead of a password: Gatus refuses to start
  until you paste the hash of yours (gatus password hash).

For developers

• test/e2e/status-page-groups.sh: 15 steps, with Push endpoints to take a group down and bring it back on demand.
• The rule of the groups is a pure module, web/app/src/utils/statusPageGroups.js, with unit tests.
• test/e2e/upgrade.sh passes from v6.0.2 to v6.1.0 (29 checks).

Assets: gatus_6.1.0_linux_amd64.tar.gz and gatus_6.1.0_linux_arm64.tar.gz

v6.0.2

v6.0.2

A new palette for the logo and a guide to run the binary as a systemd service. The server behaves exactly as in
v6.0.1; upgrading is a matter of changing the image tag or the binary.

Image: jniltinho/gatus:v6.0.2 (linux/amd64, linux/arm64)

Logo

The logo keeps its shape and gets a teal and steel-blue palette, with navy lettering. The darker half is deliberately
not navy: on the dark theme, which is the default, it would disappear. The favicon, the icons of the web app manifest
and the apple-touch-icon follow. As before, the header and the login screen only show a logo when ui.logo is set;
ui.logo: /logo-192x192.png shows this one, which Gatus serves itself.

If you see the old favicon after the upgrade, it is the cache of the browser.

Installing the binary on Linux

docs/install-linux.md installs the release
tarball in /opt/gatus and runs it with the unit in
docs/systemd/gatus.service:

• a gatus user; the binary and the configuration belong to root and are only readable by the group, so the service
  can rewrite neither;
• a hardened unit: the whole file system read-only except /opt/gatus/data, system call filters, CAP_NET_RAW for
  ICMP endpoints, and gatus config validate before every start (systemd-analyze security: 3.2, OK);
• logs in the journal under the identifier gatus, how to change the level, how to keep the journal across reboots
  and how to also write a file with logrotate. The level of Gatus is part of the text of each line, not a priority of
  the journal: filter with grep, not with journalctl -p;
• upgrade keeping the previous binary, nginx with the event stream unbuffered, and removal.

For developers

• test/e2e/upgrade.sh removes the containers and the data it creates (it left three containers behind per run).
• Every screenshot was retaken with the new logo.

Assets: gatus_6.0.2_linux_amd64.tar.gz and gatus_6.0.2_linux_arm64.tar.gz