upright 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68ab49fec5d7d1e512a1f639de64f0ff2d856d6b753cf9ff8593fb8d2011f4dd
+  data.tar.gz: 4841c873eadfa45a515f15bd6c1a12648cc923b72d93bb6efec1e62f3601e94c
+SHA512:
+  metadata.gz: e69af1adfbf82119f843ade06fe6c06b5ee3bc7c595fe0e338351d7ad13383f0e10223391bbde959c1437649fe176d3807034ef325c7ab1178cf24f4f1f58de7
+  data.tar.gz: '011039880bc90c861b67a8c315e9ad1b3e25379db5dcf0bce931bb47ce5625d98ba967659b879773cd8c773c2c5728f08d9ea80c09b64377cf52e0623292e63c'

data/LICENSE.md

@@ -0,0 +1,10 @@
+# O'Saasy License Agreement
+
+Copyright © 2026, 37signals LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,455 @@
+# Upright
+
+Upright is a self-hosted synthetic monitoring system. It provides a framework for running health check probes from multiple geographic sites and reporting metrics via Prometheus. Alerts can then be configured with AlertManager.
+
+## Features
+
+- **Playwright Probes** - Browser-based probes for user flows with video recording and logs
+- **HTTP Probes** - Simple HTTP health checks with configurable expected status codes
+- **SMTP Probes** - EHLO handshake verification for mail servers
+- **Traceroute Probes** - Network path analysis with hop-by-hop latency tracking
+- **Multi-Site Support** - Run probes from multiple geographic locations with staggered scheduling
+- **Observability** - OTLP compatible, Prometheus metrics, OpenTelemetry tracing, and AlertManager support
+- **Configurable Authentication** - OmniAuth integration with support for any OIDC provider
+
+### Not Included
+
+- **Dashboards** - Instead, Grafana is suggested for monitoring the Prometheus metrics generated here
+- **Notifications** - Instead, Alertmanager is included for alerting and notifications
+- **Hosting** - Instead, you can use a VPS from DigitalOcean, Hetzner, etc.
+
+### Components
+
+- Rails engine
+- SQLite
+- Solid Queue for background and recurring jobs
+- Mission Control - Jobs to monitor Solid Queue and manually enqueue probes
+- Kamal for deployments
+- Prometheus metrics for uptime queries and alerting
+- AlertManager for notifications
+- Open Telemetry Collector - logs, metrics and traces can be shipped to any OTLP compatible endpoint
+
+## Installation
+
+Upright is designed to be run in it's own Rails app and deployed with Kamal.
+
+### Quick Start (New Project)
+
+Create a new Rails application and install Upright:
+
+```bash
+rails new my-upright --database=sqlite3 --skip-test
+cd my-upright
+bundle add upright --github=basecamp/upright
+bin/rails generate upright:install
+bin/rails db:setup
+```
+
+Start the server:
+
+```bash
+bin/dev
+```
+
+Visit http://app.my-upright.localhost:3000 to see your Upright instance.
+
+> **Note**: Upright uses subdomain-based routing. The `app` subdomain is the admin interface, while site-specific subdomains (e.g., `nyc`, `lon`) show probe results for each location. The `.localhost` TLD resolves to 127.0.0.1 on most systems.
+
+### What the Generator Creates
+
+The `upright:install` generator creates:
+
+- `config/initializers/upright.rb` - Engine configuration
+- `config/sites.yml` - Site definitions for each VPS you host Upright on
+- `config/prometheus/prometheus.yml` - Prometheus configuration
+- `config/alertmanager/alertmanager.yml` - AlertManager configuration
+- `config/otel_collector.yml` - OpenTelemetry Collector configuration
+- `probes/` - Directory for all HTTP, SMTP, Traceroute YAML config as well as Playwright probe classes
+
+It also mounts the engine at `/` in your routes.
+
+## Configuration
+
+### Basic Setup
+
+See `config/initializers/upright.rb`
+
+### Hostname Configuration
+
+Upright uses subdomain-based routing. Configure your production hostname:
+
+```ruby
+# config/initializers/upright.rb
+Upright.configure do |config|
+  config.hostname = "upright.com"
+end
+```
+
+For local development, the hostname defaults to `{service_name}.localhost` (e.g., `upright.localhost`).
+
+### Site Configuration
+
+Define your monitoring locations in `config/sites.yml`:
+
+```yaml
+shared:
+  sites:
+    - code: nyc
+      city: New York City
+      country: US
+      geohash: dr5reg
+      provider: digitalocean
+
+    - code: ams
+      city: Amsterdam
+      country: NL
+      geohash: u17982
+      provider: digitalocean
+
+    - code: sfo
+      city: San Francisco
+      country: US
+      geohash: 9q8yy
+      provider: hetzner
+```
+
+Each site node identifies itself via the `SITE_SUBDOMAIN` environment variable, configured in your Kamal deploy.yml.
+
+### Authentication
+
+#### Static Credentials
+
+Upright uses static credentials by default with username `admin` and password `upright`.
+
+> [!WARNING]
+> Change the default password before deploying to production by setting the `ADMIN_PASSWORD` environment variable.
+
+
+#### OpenID Connect
+
+For production environments, Upright supports OpenID Connect (Logto, Keycloak, Duo, Okta, etc.):
+
+```ruby
+# config/initializers/upright.rb
+Upright.configure do |config|
+  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
+```
+
+## Defining Probes
+
+### HTTP Probes
+
+Add probes to `probes/http_probes.yml`:
+
+```yaml
+- name: Main Website
+  url: https://example.com
+  expected_status: 200
+
+- name: API Health
+  url: https://api.example.com/health
+  expected_status: 200
+
+- name: Admin Panel
+  url: https://admin.example.com
+  basic_auth_credentials: admin_auth  # Key in Rails credentials
+```
+
+### SMTP Probes
+
+Add probes to `probes/smtp_probes.yml`:
+
+```yaml
+- name: Primary Mail Server
+  host: mail.example.com
+
+- name: Backup Mail Server
+  host: mail2.example.com
+```
+
+### Playwright Probes
+
+Generate a new browser-based probe:
+
+```bash
+bin/rails generate upright:playwright_probe MyServiceAuth
+```
+
+This creates a probe class:
+
+```ruby
+# probes/my_service_auth_probe.rb
+class Probes::Playwright::MyServiceAuthProbe < Upright::Probes::Playwright::Base
+  # Optionally authenticate before running
+  # authenticate_with_form :my_service
+
+  def check
+    page.goto("https://app.example.com")
+    page.fill('[name="email"]', "test@example.com")
+    page.click('button[type="submit"]')
+    page.wait_for_selector(".dashboard")
+  end
+end
+```
+
+See https://playwright-ruby-client.vercel.app/docs/api/page for how to create Playwright tests.
+
+#### Creating Authenticators
+
+For probes that require authentication, create an authenticator:
+
+```ruby
+# probes/authenticators/my_service.rb
+class Playwright::Authenticator::MyService < Upright::Playwright::Authenticator::Base
+  def signin_redirect_url = "https://app.example.com/dashboard"
+  def signin_path = "/login"
+  def service_name = :my_service
+
+  def authenticate
+    page.goto("https://app.example.com/login")
+    page.get_by_label("Email").fill(credentials.my_service.email)
+    page.get_by_label("Password").fill(credentials.my_service.password)
+    page.get_by_role("button", name: "Sign in").click
+  end
+end
+```
+
+## Scheduling
+
+Configure probe scheduling with Solid Queue in `config/recurring.yml`:
+
+```yaml
+production:
+  http_probes:
+    class: Upright::ProbeCheckJob
+    args: [http]
+    schedule: every 30 seconds
+
+  smtp_probes:
+    class: Upright::ProbeCheckJob
+    args: [smtp]
+    schedule: every 30 seconds
+
+  my_service_auth:
+    class: Upright::ProbeCheckJob
+    args: [playwright, MyServiceAuth]
+    schedule: every 15 minutes
+```
+
+## System Requirements
+
+### Minimum VM Specifications
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| CPU | 2 vCPU | 2 vCPU |
+| RAM | 2 GB | 4 GB |
+| Disk | 25 GB | 50 GB |
+
+Playwright browser automation is memory-intensive. For sites running many Playwright probes concurrently, consider 4 GB RAM.
+
+### Software Requirements
+
+- **OS**: Ubuntu 24.04+ or Debian 12+ (any Linux with Docker support)
+- **Docker**: 24.0+ (installed automatically by Kamal)
+- **Ruby**: 3.4+ (for local development only; production runs in Docker)
+- **Rails**: 8.0+
+
+
+### Firewall Rules
+
+Open the following ports:
+
+| Port | Protocol | Direction | Purpose |
+|------|----------|-----------|---------|
+| 22 | TCP | Inbound | SSH access |
+| 80 | TCP | Inbound | HTTP (redirects to HTTPS) |
+| 443 | TCP | Inbound | HTTPS |
+| 25 | TCP | Outbound | SMTP probes (if used) |
+
+### SMTP Port 25 Note
+
+Most cloud providers block outbound port 25 by default to prevent spam. If you plan to use SMTP probes, you must request port 25 to be unblocked.
+
+This is not required for HTTP or Playwright probes.
+
+## DNS Setup
+
+For multiple geographic locations, use subdomains for each site. Each subdomain points to a different server:
+
+```
+; Primary dashboard
+app.upright.example.com      A    203.0.113.10
+
+; Monitoring nodes
+ams.upright.example.com      A    203.0.113.10    ; Amsterdam
+nyc.upright.example.com      A    198.51.100.20   ; New York
+sfo.upright.example.com      A    192.0.2.30      ; San Francisco
+```
+
+## Deployment with Kamal
+
+### Example `config/deploy.yml`
+
+```yaml
+service: upright
+image: your-org/upright
+
+servers:
+  web:
+    hosts:
+      - nyc.upright.example.com
+    env:
+      tags:
+        SITE_SUBDOMAIN: nyc
+
+    hosts:
+      - ams.upright.example.com
+    env:
+      tags:
+        SITE_SUBDOMAIN: ams
+
+    hosts:
+      - sfo.upright.example.com
+    env:
+      tags:
+        SITE_SUBDOMAIN: sfo
+
+registry:
+  server: ghcr.io
+  username: your-org
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+env:
+  clear:
+    RAILS_ENV: production
+    RAILS_LOG_TO_STDOUT: true
+  secret:
+    - RAILS_MASTER_KEY
+    - OIDC_CLIENT_ID
+    - OIDC_CLIENT_SECRET
+
+accessories:
+  playwright:
+    image: mcr.microsoft.com/playwright:v1.55.0-noble
+    cmd: npx -y playwright run-server --port 53333
+    host: nyc.upright.example.com
+    port: 53333
+    env:
+      clear:
+        DEBUG: pw:api
+```
+
+## Observability
+
+### Prometheus
+
+The engine exposes metrics at `/metrics`. Configure Prometheus to scrape:
+
+```yaml
+scrape_configs:
+  - job_name: upright
+    static_configs:
+      - targets: ['localhost:3000']
+    metrics_path: /metrics
+```
+
+### Metrics Exposed
+
+- `upright_probe_duration_seconds` - Probe execution duration
+- `upright_probe_success` - Probe success/failure (1/0)
+- `upright_probe_status_code` - HTTP status code for HTTP probes
+
+Labels include: `probe_name`, `probe_type`, `site_code`, `site_city`, `site_country`
+
+### AlertManager
+
+Example alert rules (`prometheus/rules/upright.rules`):
+
+```yaml
+groups:
+  - name: upright
+    rules:
+      - alert: ProbeDown
+        expr: upright_probe_success == 0
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Probe {{ $labels.probe_name }} is down"
+
+      - alert: ProbeSlow
+        expr: upright_probe_duration_seconds > 10
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Probe {{ $labels.probe_name }} is slow"
+```
+
+### OpenTelemetry
+
+Traces are automatically created for each probe execution. Configure your collector endpoint:
+
+```ruby
+Upright.configure do |config|
+  config.otel_endpoint = "https://otel.example.com:4318"
+end
+```
+
+## Local Development
+
+### Setup
+
+```bash
+bin/setup
+```
+
+This installs dependencies, prepares the database, and starts the dev server.
+
+### Running Services
+
+Start supporting Docker services (Playwright server, etc.):
+
+```bash
+bin/services
+```
+
+### Running the Server
+
+```bash
+bin/dev
+```
+
+Visit http://app.upright.localhost:3000 and sign in with:
+- **Username**: `admin`
+- **Password**: `upright` (or value of `ADMIN_PASSWORD` env var)
+
+### Testing Playwright Probes
+
+Run probes with a visible browser window:
+
+```bash
+LOCAL_PLAYWRIGHT=1 bin/rails console
+```
+
+```ruby
+Probes::Playwright::MyServiceAuthProbe.check
+```
+
+### Running Tests
+
+```bash
+bin/rails test
+```
+
+## License
+
+The gem is available under the terms of the [O'Saasy License](LICENSE.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/upright/_global.css

@@ -0,0 +1,104 @@
+@layer reset, base, components, utilities;
+
+:root {
+  /* Spacing */
+  --inline-space: 1ch;
+  --block-space: 1rem;
+
+  /* Text */
+  --font-sans: -apple-system, BlinkMacSystemFont, sans-serif;
+  --font-mono: "IBM Plex Mono", "JetBrains Mono", ui-monospace, "Cascadia Code", "Fira Code", monospace;
+
+  --text-x-small: 0.7rem;
+  --text-small: 0.8rem;
+  --text-normal: 0.9rem;
+  --text-large: 1.25rem;
+  --text-x-large: 1.5rem;
+
+  /* OKLCH colors: Primitives */
+  --lch-black: 0% 0 0;
+  --lch-white: 100% 0 0;
+  --lch-canvas: var(--lch-white);
+  --lch-canvas-deep: var(--lch-white);
+  --lch-ink-inverted: var(--lch-white);
+
+  --lch-ink-darkest: 26% 0.05 264;
+  --lch-ink-darker: 40% 0.026 262;
+  --lch-ink-dark: 56% 0.014 260;
+  --lch-ink-medium: 66% 0.008 258;
+  --lch-ink-light: 84% 0.005 256;
+  --lch-ink-lighter: 92% 0.003 254;
+  --lch-ink-lightest: 96% 0.002 252;
+
+  --lch-blue-dark: 57.02% 0.1895 260.46;
+  --lch-blue-lighter: 92% 0.026 254;
+
+  --lch-green-dark: 55% 0.162 147;
+  --lch-red-dark: 59% 0.19 38;
+
+  /* Colors: Semantic */
+  --color-black: oklch(var(--lch-black));
+  --color-white: oklch(var(--lch-white));
+  --color-canvas: oklch(var(--lch-canvas));
+  --color-ink: oklch(var(--lch-ink-darkest));
+  --color-ink-dark: oklch(var(--lch-ink-dark));
+  --color-ink-medium: oklch(var(--lch-ink-medium));
+  --color-ink-light: oklch(var(--lch-ink-light));
+  --color-ink-lighter: oklch(var(--lch-ink-lighter));
+  --color-ink-lightest: oklch(var(--lch-ink-lightest));
+  --color-ink-inverted: oklch(var(--lch-ink-inverted));
+
+  /* Colors: Abstractions */
+  --color-link: oklch(var(--lch-blue-dark));
+  --color-positive: oklch(var(--lch-green-dark));
+  --color-negative: oklch(var(--lch-red-dark));
+  --color-selected: oklch(var(--lch-blue-lighter));
+
+  /* Borders & Shadows */
+  --border: 1px solid var(--color-ink-lighter);
+  --shadow: 0 0 0 1px oklch(var(--lch-black) / 5%),
+            0 0.2em 0.2em oklch(var(--lch-black) / 5%),
+            0 0.4em 0.4em oklch(var(--lch-black) / 5%),
+            0 0.8em 0.8em oklch(var(--lch-black) / 5%);
+
+  /* Focus rings */
+  --focus-ring-color: var(--color-link);
+  --focus-ring-size: 2px;
+
+  /* Layout */
+  --main-padding: clamp(var(--inline-space), 3vw, calc(var(--inline-space) * 3));
+  --main-width: 1400px;
+
+  /* Grain */
+  --grain-opacity: 0.04;
+}
+
+/* Dark mode: Update primitive values only */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --lch-canvas: 18% 0.04 250;
+    --lch-canvas-deep: 12% 0.035 255;
+    --lch-ink-inverted: var(--lch-black);
+
+    --lch-ink-darkest: 92% 0.01 250;
+    --lch-ink-darker: 80% 0.015 250;
+    --lch-ink-dark: 65% 0.02 250;
+    --lch-ink-medium: 50% 0.025 250;
+    --lch-ink-light: 35% 0.03 250;
+    --lch-ink-lighter: 24% 0.035 250;
+    --lch-ink-lightest: 20% 0.04 250;
+
+    --lch-blue-dark: 70% 0.14 250;
+    --lch-blue-lighter: 25% 0.05 250;
+
+    --lch-green-dark: 75% 0.15 145;
+    --lch-red-dark: 70% 0.16 42;
+
+    --shadow: 0 0 0 1px oklch(var(--lch-black) / 0.4),
+              0 .2em 1.6em -0.8em oklch(var(--lch-black) / 0.5),
+              0 .4em 2.4em -1em oklch(var(--lch-black) / 0.6),
+              0 .4em .8em -1.2em oklch(var(--lch-black) / 0.7);
+
+    --grain-opacity: 0.1;
+  }
+}