Rails

Runlight läuft in einer App mit Rails 7.2, 8.0 oder 8.1, mit seinen Tabellen in der eigenen Datenbank der App und seinem Dashboard unter /runlight.

Das Gem runlight bringt eine Rails-Engine mit, die Runlight aus deiner App heraus ausliefert, mit seinen Tabellen in der eigenen Datenbank der App. Es ist das Ruby-Gem, das auf jede Anfrage die Antwort gibt, die auch die TypeScript-Bibliothek gibt, deshalb kann jede der beiden eine Datenbank lesen, die die andere geschrieben hat. Es funktioniert mit Rails 7.2, 8.0 und 8.1 auf Ruby 3.2 oder neuer und mit SQLite, Postgres, MySQL oder MariaDB.

Installieren

Füge das Gem hinzu und führe seinen Generator aus.

bundle add runlight
bin/rails generate runlight:install
bin/rails db:migrate

Der Generator schreibt config/initializers/runlight.rb und eine Migration, die Runlights Tabellen anlegt. Jeder ihrer Namen beginnt mit rl_, sodass sie neben den eigenen Tabellen der App stehen. Nach einem Upgrade des Gems bringt Runlight sie bei der ersten Anfrage selbst auf den neuesten Stand, und bin/rails runlight:migrate erledigt das sofort.

Konfigurieren

Der Initializer richtet das eine Runlight ein, das sich die App teilt.

Runlight.configure(
  store: Runlight::Stores.active_record,
  site: { name: "example.com", hostnames: ["example.com"], timezone: "Europe/London" },
  routes: { base_path: "/runlight", token: ENV.fetch("RUNLIGHT_TOKEN", "") },
)

Die Optionen tragen die Namen aus Konfiguration, in Snake Case geschrieben, deshalb funktionieren sites, trust_proxy, rate_limit, mail und managed_sites alle so wie dort. Die unter routes gehören zum Dashboard, etwa accounts: true, womit sich Leute mit ihrer eigenen E-Mail-Adresse und ihrem Passwort anmelden, sobald RUNLIGHT_SECRET gesetzt ist, wie unter Konten. Ein leeres Token hält das Dashboard geschlossen, und nil würde es für alle offen lassen. Um das Token in den Credentials der App aufzubewahren, lies es dort mit Rails.application.credentials.runlight_token.

Runlight::Stores.active_record legt die Tabellen in die Datenbank, mit der ApplicationRecord verbunden ist. In einer App mit mehreren Datenbanken übergibst du die abstrakte Klasse der gewünschten, etwa Runlight::Stores.active_record(AnalyticsRecord), und führst die Migration gegen diese Datenbank aus.

Das Skript einbinden

Füge das Skript ins Layout ein, direkt vor </head>.

<script defer src="/runlight/s.js"></script>

Setze dann RUNLIGHT_TOKEN auf eine lange zufällige Zeichenkette und öffne einmal /runlight/?token=, gefolgt von dieser Zeichenkette, um dich anzumelden, wie es Erste Schritte beschreibt.

Wie Anfragen es erreichen

Die Engine fügt der App eine Middleware hinzu. Sie beantwortet die Pfade unter /runlight, die Kurzlinks unter /go und jede Link-Domain, die du unter Einstellungen hinzufügst, bevor der Router sie sieht, und gibt jede andere Anfrage an die App weiter. Die CSRF-Prüfung von Rails würde den Tracker abweisen, der kein Token senden kann, und Runlight prüft seine Anfragen auf seine eigene Weise, deshalb kommt nichts in config/routes.rb. Die Middleware zeichnet außerdem die Abrufe von KI-Agenten auf, während deine Seiten ausgeliefert werden, was für alle anderen keine Zeit kostet.

Eine Link-Domain ist ein eigener Host, füge sie also zu config.hosts hinzu, wenn die App diese Liste setzt, sonst weist Rails die Anfrage vorher ab.

Der stündliche Check

Der stündliche Check verschickt E-Mail-Berichte und hält die Daten in Ordnung. Führe ihn alle paar Minuten aus, einmal für die ganze App und nicht in jedem Prozess. Mit Solid Queue fügst du ihn zu config/recurring.yml hinzu.

production:
  runlight_check:
    command: "Runlight.instance.check"
    schedule: every 5 minutes

Mit Cron oder einem anderen Scheduler, der einen Befehl ausführt, nimmst du den Rake-Task.

*/5 * * * * cd /var/www/app && bin/rails runlight:check

In Tests

Runlight zeichnet nichts auf, bis eine Anfrage es erreicht, deshalb merken Tests, die nie /runlight laden, keinen Unterschied. Ein Test des Dashboards selbst kann Runlight.configure mit einem eigenen Store erneut aufrufen, etwa Runlight::Stores.sqlite(":memory:"), und die Engine nutzt ab der nächsten Anfrage den neuen.

Was anders ist als bei der TypeScript-Bibliothek

Die Engine ist das Ruby-Gem innerhalb von Rails, deshalb gilt auch hier, was die Seite Ruby aufzählt. Dasselbe Gem hat einen eigenständigen Server, um Runlight auf einer eigenen Domain zu betreiben, mit einem Dashboard für mehrere Websites.