Skip to content
24/48h shipping across Italy
Home Documentation
Shop Blog Contact Us My account
Skip to content
Documentation navigation

OneUptime for k0smos

Local self-hosted OneUptime configuration for validating the k0smos oneuptimeapi module.

The upstream OneUptime Docker Compose setup is intentionally not vendored here: it changes frequently and the official release branch is the source of truth. This folder stores only the k0smos-specific launcher and environment template.

Ports

  • OneUptime UI/API: http://localhost:18080
  • OneUptime custom status-page HTTPS port: 18443
  • PostgreSQL backup/admin port exposed by upstream: 5400

The HTTP/HTTPS host ports intentionally avoid 80 and 443 so the stack can run next to k0smos, Caddy, FrankenPHP, or another local reverse proxy.

Start on Windows

cd docker\oneuptime
Copy-Item config.env.example config.env
# Edit config.env and replace every "change-me-..." secret before first start.
.\start.ps1

Start on Linux or macOS

cd docker/oneuptime
cp config.env.example config.env
# Edit config.env and replace every "change-me-..." secret before first start.
sh ./start.sh

Both launchers clone https://github.com/OneUptime/oneuptime.git into docker/oneuptime/runtime on first use and then run the upstream docker-compose.yml with this folder's config.env.

Before the first Compose start, edit docker/oneuptime/config.env and replace at least ONEUPTIME_SECRET and all database passwords. Keep ONEUPTIME_HTTP_PORT=18080 and verify that configured probe URLs use http://localhost:18080. Never commit config.env.

To refresh the upstream release checkout later:

.\start.ps1 -Update

or:

./start.sh --update

k0smos validation notes

After OneUptime is reachable at http://localhost:18080:

  1. Register the first admin account.
  2. Create or select a project.
  3. Create a dedicated API key for k0smos.
  4. Create an Incoming Request monitor and copy its heartbeat secret.
  5. Configure /admin/oneuptimeapi/settings in k0smos with:
    • Base URL: http://localhost:18080
    • API key: the dedicated key
    • Project ID: the OneUptime project ID
    • Default status page ID, when available
    • Default heartbeat secret: the Incoming Request monitor secret
  6. Call POST /api/admin/oneuptimeapi/test-connection and confirm that the expected project envelope is returned.

Continue with the live verification checklist in modules/OneUptimeApi/src/AI.OneUptimeApi.md § "Deferred Live Verification".

Public front status widget

The module contributes a public status-page widget to the default front theme footer (template slot front.footer.widgets). It is opt-in per tenant:

  1. Configure and enable the integration in /admin/oneuptimeapi/settings.
  2. Enable "front status page widget" (oneuptimeapi.front_widget_enabled).
  3. Set a default status page ID so the summary proxy has a target.

The browser calls the public proxy GET /api/oneuptimeapi/status-summary, which runs the OneUptime status-page summary server-side and returns only derived, non-sensitive signals (an overall state plus incident/maintenance counts). The API key, heartbeat secret, and base URL are never sent to the browser. When the widget is disabled or unconfigured the proxy returns {enabled:false} and the widget stays hidden. Post-implementation checks live in modules/OneUptimeApi/src/AI.OneUptimeApi.md § "Deferred Live Verification".

When a OneUptime monitor needs to call a k0smos instance running on the host from Docker Desktop, use host.docker.internal in the monitored URL. If k0smos is running in another Compose project, use a shared Docker network or expose a host port explicitly.