Upright Documentation

Upright is designed to be run as a Rails engine within its own application and deployed using Kamal. To set up a new project, create a Rails app with SQLite3, add the upright gem, and run the installation generator.

Note that Upright uses subdomain-based routing. The app subdomain is used for the admin interface, while site-specific subdomains (e.g., nyc, lon) are used to view probe results for specific geographic locations.

rails new my-upright --database=sqlite3 --skip-test
cd my-upright
bundle add upright
bin/rails generate upright:install
bin/rails db:migrate

# Start the server
bin/dev

Upright exposes metrics via a Puma plugin at http://0.0.0.0:9394/metrics. To scrape these metrics, configure your Prometheus scrape_configs to target localhost:9394.

Available Metrics:

• upright_probe_duration_seconds: Probe execution duration
• upright_probe_up: Probe status (1 = up, 0 = down)
• upright_http_response_status: HTTP response status code

Labels: Metrics include the following labels: type, name, site_code, site_city, and site_country.

scrape_configs:
  - job_name: upright
    static_configs:
      - targets: ['localhost:9394']

Probes are defined in YAML files within the probes/ directory.

HTTP Probes (probes/http_probes.yml)

Supports url, expected_status, alert_severity (medium, high, critical), and basic_auth_credentials (referencing Rails credentials).

SMTP Probes (probes/smtp_probes.yml)

Requires a host field. Note: Most cloud providers block outbound port 25 by default; you may need to request unblocking.

Playwright Probes

Generate a new browser-based probe class using: bin/rails generate upright:playwright_probe MyServiceAuth.

For probes requiring authentication, implement a Playwright::Authenticator class in probes/authenticators/.

# probes/http_probes.yml
- name: Main Website
  url: https://example.com
  expected_status: 200

- name: API Health
  url: https://api.example.com/health
  expected_status: 200
  alert_severity: critical

To set up a new local development environment, run bin/setup. This command installs dependencies, prepares the database, and starts the development server.

To run the server, use:

bin/dev

Access the application at http://app.upright.localhost:3000.

Default Credentials:

• Username: admin
• Password: upright (or the value of the ADMIN_PASSWORD environment variable)

Playwright versions are managed via Upright::PLAYWRIGHT_VERSION in lib/upright/version.rb. This single version constant drives the Ruby gem, the npm package, and the trace viewer versions.

To perform an upgrade:

1. Update PLAYWRIGHT_VERSION in lib/upright/version.rb.
2. Update the version in package.json.
3. Run bin/setup (or manually: npm install && npx playwright install chromium && rake playwright:sync).
4. Run bin/rails test to verify compatibility.
5. Commit the updated public/trace-viewer/ files, package.json, and package-lock.json.

Use config/recurring.yml to schedule probes. Each entry specifies a command (the class method to trigger the check) and a schedule using every syntax.

production:
  http_probes:
    command: "Upright::Probes::HTTPProbe.check_and_record_all_later"
    schedule: every 30 seconds

  my_service_auth:
    command: "Probes::Playwright::MyServiceAuthProbe.check_and_record_later"
    schedule: every 15 minutes

Upright automatically loads custom probes and authenticators from paths defined in Upright.configuration.

• Probes: Files matching *_probe.rb in the probes_path are required. They are loaded into the ::Probes::Playwright namespace.
• Authenticators: Files in the authenticators_path are required. They are loaded into the ::Playwright::Authenticator namespace.

The StaticCredentials strategy implements a standard OmniAuth flow:

1. Request Phase: The strategy renders a simple HTML form with a username text field and a password password field. The form title is determined by the title option.
2. Callback Phase: Upon form submission, the strategy retrieves the username and password from the request parameters. It validates them against the provided credentials hash using ActiveSupport::SecurityUtils.secure_compare to prevent timing attacks.
3. Success: If credentials match, the uid is set to the username, and the info hash is populated with { name: username, email: "#{username}@localhost" }.
4. Failure: If credentials do not match or are blank, the strategy calls fail!(:invalid_credentials).

Upright automatically cleans up old probe results. You can tune the retention thresholds in config/initializers/upright.rb to manage database size and data availability.

Upright.configure do |config|
  config.stale_success_threshold = 24.hours     # Default: 24 hours
  config.stale_failure_threshold = 30.days       # Default: 30 days
  config.failure_retention_limit = 20_000        # Default: 20,000
end

You can configure the base hostname and authentication methods via the Upright.configure block in config/initializers/upright.rb.

Hostname

Set your production hostname to enable correct subdomain routing.

Authentication

• Static Credentials: By default, use admin/upright. Warning: Set the ADMIN_PASSWORD environment variable before deploying to production.
• OpenID Connect: Supports providers like Logto, Keycloak, Duo, and Okta.

# config/initializers/upright.rb
Upright.configure do |config|
  config.hostname = "upright.com"
  
  # For OpenID Connect
  config.auth_provider = :openid_connect
  config.auth_options = {
    issuer: "https://your-tenant.logto.app/oidc",
    client_id: ENV["OIDC_CLIENT_ID"],
    client_secret: ENV["OIDC_CLIENT_SECRET"]
  }
end