Skip to content
sergiorsPublic

About

Event-driven runtime for declarative apps, with serverless functions, schedules, and persistent services.

Topics

Resources

Stars

18 stars

Watchers

1 watching

Forks

Repository files navigation

Relay

Relay is an event-driven serverless runtime for apps that combine functions, scheduled jobs, and persistent services. It runs on infrastructure you control and uses Redis Streams1 for external events and Docker2 for workload execution.

Functions execute handlers triggered by event patterns or schedules, with automatic retries and dead-letter queues for failed executions. Persistent services run continuously and are reconciled to their declared configuration.

Getting Started

You need Docker Engine and Docker Compose.

mkdir relay && cd relay
curl -fsSLO https://raw.githubusercontent.com/sergiors/relay/main/compose.yaml
mkdir apps
docker compose up -d
docker compose exec relay relay health

The stack publishes unauthenticated Redis and development-credential PostgreSQL on host ports, and Relay mounts the host Docker socket read-only to manage containers. The read-only mount does not make the Docker API read-only: a compromised Relay process can exercise the daemon's full authority (often equivalent to host root). Treat Docker Engine access as highly privileged, and do not expose this stack to untrusted networks.

What you get

  • Event-driven functions — Redis Streams, declarative event matching, at-least-once delivery, automatic retries, pending-message recovery, and dead-letter queues.
  • Managed runtimes — Python 3.14/3.15 and Node.js 24/26, with JavaScript and TypeScript support, reusable warm containers, and bounded concurrency.
  • Cron schedules — Minute-precision scheduling, IANA timezones, cluster-wide deduplication, publication recovery, and startup catch-up.
  • Persistent services — Run APIs, workers, gateways, and other long-running processes using managed runtimes or container images, with replicas, networking, and optional Traefik routing.
  • Git-based deployments — Connect a Git repository, synchronize application code, and deploy updates without rebuilding or restarting Relay.
  • Resource controls — Per-container memory, CPU, and PID limits for functions and services.
  • Configuration and secrets — Environment variables and secret references for applications, functions, and services.
  • Observability — Prometheus metrics, structured logs, persisted statistics, and OpenTelemetry tracing.
  • Operations — Health checks, manual invocation, DLQ inspection and replay, and graceful shutdown.
  • Flexible deployment — Run the Relay process under Docker, systemd, Kubernetes, or another process manager.

See Apps, Events, Schedules, and Services for workload behavior.

Guarantees

  • Event and schedule delivery is at least once, not exactly once. Handlers that cause side effects should be idempotent.
  • Relay keeps messages pending while matched work is unresolved. It acknowledges only after all matched invocations succeed or are durably dead-lettered.
  • Unavailable apps and temporary capacity limits do not cause matching work to be acknowledged or consume a retry.
  • Schedule publication is deduplicated cluster-wide; handler execution still follows at-least-once delivery.
  • Persistent services are reconciled toward their declared replicas and configuration.
  • Resource limits apply per container; adding concurrency or replicas increases aggregate resource use.

See Events and Schedules for delivery and recovery details, and Operations for deployment guidance.

Apps

An app is a direct child of /apps with a template.yaml. A template can combine event handlers, schedules, and persistent services. This MongoDB CDC rule matches inserts to the users collection (use tableName for PostgreSQL):

runtime: nodejs24.x

events:
  - handler: handler.handler
    pattern:
      recordType: [INSERT]
      collectionName: [users]

See Apps for the template reference, Events for matching and delivery, Schedules for cron triggers, and Services for long-running workloads. Changes under /apps are applied live; see Configuration.

Commands

relay start

relay health

relay stats
relay stats reset

relay app ls
relay app inspect <name>
relay app invoke <name> [json|-]

relay runtime ls
relay runtime inspect <runtime>
relay runtime check [runtime]
relay runtime update <runtime>
relay runtime update --all

relay secret ls
relay secret set <name> [-]
relay secret rm <name>

relay git keygen
relay git set <repository>
relay git sync
relay git status
relay git remove

relay dlq ls
relay dlq inspect <id>
relay dlq replay <id>
relay dlq rm <id>

Manual invocation takes a JSON object, or - to read it from stdin. Secret values can be entered at a hidden prompt or read from stdin; they are never command-line arguments. For command details, see CLI.

relay app invoke my-app '{"recordType":"INSERT"}'
relay app invoke my-app - < event.json

# -T keeps stdin a pipe instead of an allocated pseudo-TTY.
docker compose exec -T relay relay app invoke my-app - < event.json

relay secret set API_KEY  # hidden prompt (requires a terminal)
printf '%s' 'value' | relay secret set API_KEY -
docker compose exec -T relay relay secret set API_KEY - < value.txt

Documentation

Document Covers
Installation Deployment and setup
Configuration Environment variables and defaults
Apps Templates, runtimes, secrets, and resources
Events Event matching, retries, delivery, and DLQ
Schedules Cron, timezones, and recovery
Services Services, replicas, networking, and routing
Operations Monitoring, recovery, logs, and Git sync
CLI Commands, flags, and prerequisites

Contributing

See development and testing for build and validation instructions.

License

Relay is licensed under the GNU General Public License v3.0.

See LICENSE.md.

Footnotes

  1. Support for additional event brokers is planned (#9). ↩

  2. Support for additional runtime backends, including Kubernetes, is planned (#10). ↩

About

Event-driven runtime for declarative apps, with serverless functions, schedules, and persistent services.

Topics

Resources

Stars

18 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages