Use Cases¶

Navigator addresses common challenges in multi-tenant and distributed applications. This page describes some typical use cases with configuration examples.

Background¶

Navigator was designed to address challenges that arise in modern multi-tenant Rails applications, particularly those using SQLite for database-per-tenant architectures. While SQLite was the motivation for many features, Navigator is database-agnostic and works with any Rails backend.

Key Resources:

Multi-Tenant Rails: Everybody Gets a Database - Mike Dalessio
SQLite Replication with Beamer - Stephen Margheim
Kamal Geo Proxy - Kevin McConnell

Navigator is inspired by Basecamp's Thruster and implemented as a reverse proxy in Go.

Quick Start¶

To use Navigator in your Dockerfile:

COPY --from=samruby/navigator:latest /navigator /usr/local/bin/navigator
CMD ["navigator", "config/navigator.yml"]

Use Case 1: Multi-Tenant and Monorepos¶

Challenge: Serve multiple tenants with isolated databases from a single codebase, potentially with different application components (API, admin, web).

Solution: Navigator launches separate instances of the same Rails application for each tenant, varying environment variables such as DATABASE_URL.

Capabilities¶

Multi-tenant setup: Multiple tenants sharing the same codebase with isolated databases using template variables
Monorepo structure: API server, admin panel, and web server from different directories
Managed processes: Background services like Sidekiq shared across tenants
Different tenant types: Production, staging/demo, and development environments

Configuration Example¶

server:
  listen: 3000
  static:
    public_dir: public

applications:
  env:
    DATABASE_URL: "sqlite3:db/${tenant_id}.sqlite3"
    RAILS_ENV: "production"

  tenants:
    - name: acme
      path: /acme
      working_dir: /app
      var:
        tenant_id: acme_production

    - name: widgets-co
      path: /widgets
      working_dir: /app
      var:
        tenant_id: widgets_production

How it works¶

Each tenant has its own process and database
Processes start on-demand and idle out when not in use
Single Docker image serves all tenants
Template variables customize environment per tenant

See multi-tenant-monorepo-example.yml for a complete example.

Use Case 2: Machine Auto-Suspend (Fly.io)¶

Challenge: Reduce costs and enable global distribution by automatically suspending or stopping machines when idle.

Solution: Navigator tracks active requests and triggers machine suspension or shutdown after a configurable idle timeout.

How it works¶

Fly.io supports autostop and suspend for idle machines. Navigator tracks active requests and triggers suspension/shutdown after a configurable timeout, enabling distribution across many machines that only run when needed.

Lifecycle Hooks¶

Navigator's lifecycle hooks enable powerful automation for machine state changes:

Pre-suspension hooks (idle event) could: - Upload databases and files to S3 or cloud storage - Send metrics to monitoring services - Notify other services about pending suspension - Checkpoint long-running computations

Post-resume hooks (resume event) could: - Sync state from shared storage - Reconnect to external services - Notify monitoring systems of machine availability - Restore application state

Configuration Example¶

server:
  idle:
    action: suspend  # or "stop"
    timeout: 20m

hooks:
  server:
    idle:
      - command: /usr/local/bin/backup-to-s3.sh
        timeout: 30s
    resume:
      - command: /usr/local/bin/restore-from-s3.sh
        timeout: 30s

applications:
  tenants:
    - name: myapp
      path: /
      working_dir: /app

See suspend-stop-example.yml for a complete example.

Use Case 3: WebSocket Support¶

Challenge: Run WebSocket servers alongside Rails applications, especially with Rails 8's Solid Cable which requires Action Cable and Rails on the same machine.

Solution: Navigator acts as both reverse proxy and process manager, routing WebSocket requests to standalone servers.

Background¶

WebSockets enable two-way communication between server and browser, with connections typically open for minutes or hours. Rails recommends running a separate Standalone Cable Server for performance, scalability, and stability.

Rails 7 and earlier: Three services (Rails, Redis, Action Cable) Rails 8 with Solid Cable: Action Cable and Rails must run on the same machine

How it works¶

Navigator combines reverse proxy routing and process management in a single tool, eliminating the need for separate tools like Nginx/Traefik and Foreman/Overmind.

Configuration Example¶

server:
  listen: 3000
  static:
    public_dir: public

  # Reverse proxy WebSocket requests to standalone Action Cable server
  reverse_proxies:
    - name: action-cable
      path: "^/cable"
      target: "http://localhost:28080"
      websocket: true

applications:
  # Disable WebSocket tracking for main app (proxies WebSockets elsewhere)
  track_websockets: true  # Global default

  tenants:
    - name: main-app
      path: /
      working_dir: /app
      track_websockets: false  # Override: this app proxies WebSockets to standalone server

WebSocket Connection Tracking¶

Navigator can track WebSocket connections to prevent apps from shutting down during idle timeouts. This is useful when apps handle WebSockets directly, but unnecessary when proxying to standalone servers.

When to disable tracking: - Apps that proxy WebSockets to separate services (like example above) - Apps that don't handle WebSocket connections at all - When minimizing memory overhead is critical

See websockets-example.yml and WebSocket Support documentation for complete examples.

Use Case 4: Dynamic Routing with Fly-Replay¶

Challenge: Route requests to specific regions, apps, or machines while handling failures gracefully.

Solution: Navigator implements Fly.io's Dynamic Routing with smart fallback behavior.

Fly-Replay Modes¶

Prefer mode: Requests that can't route to intended destination go to available server Force mode: Failed routing returns error

Navigator's Approach¶

Navigator takes a middle ground: when requests can't be routed to the intended destination, it shows a user-friendly maintenance page that can be searched in logs. This is better than silent failures and provides visibility for debugging.

Configuration Example¶

server:
  listen: 3000

routes:
  fly:
    replay:
      - path: "^/api/"
        app: api-backend
        status: 307
      - path: "^/admin/"
        region: ord  # Chicago
        status: 307

applications:
  tenants:
    - name: web-app
      path: /
      working_dir: /app

Features¶

Multi-target routing: Route to regions, apps, or specific machines
Smart fallback: Automatic reverse proxy for requests >1MB
Maintenance pages: User-friendly error pages
Pattern matching: Flexible URL pattern configuration
Method filtering: Apply rules to specific HTTP methods

See routing-example.yml for a complete example.

Use Case 5: Lightweight Admin Endpoints with CGI¶

Challenge: Execute administrative scripts (database sync, user management, status checks) without starting a full web application process.

Solution: Navigator's CGI support allows running standalone scripts directly, with user isolation and automatic config reload.

Benefits¶

No app startup overhead: Scripts run immediately without starting Rails
Lower memory footprint: No persistent Rails process needed
Security: Run scripts as different Unix users (privilege separation)
Smart config reload: Automatically reload Navigator config after script execution

Configuration Example¶

server:
  listen: 3000
  cgi_scripts:
    # Database synchronization endpoint
    - path: /admin/sync
      script: /opt/scripts/sync_databases_s3.rb
      method: POST
      user: rails
      group: rails
      timeout: 10m
      reload_config: config/navigator.yml
      env:
        RAILS_DB_VOLUME: /mnt/db
        RAILS_ENV: production

    # Lightweight status check
    - path: /admin/status
      script: /opt/scripts/check_status.sh
      method: GET
      user: rails
      timeout: 5s
      env:
        DB_PATH: /mnt/db

auth:
  enabled: true
  htpasswd: /etc/navigator/htpasswd
  # CGI endpoints still require authentication

Use Cases for CGI Scripts¶

Database operations: Sync, backup, migration without Rails overhead
User management: Update htpasswd files with automatic config reload
Health checks: Lightweight status endpoints
Webhooks: Handle incoming webhooks from external services
Administrative tasks: One-off scripts that don't justify a full web app

How it Works¶

Request arrives at /admin/sync
Navigator matches path to CGI configuration
Script executes as configured user (e.g., rails)
Standard CGI environment variables are set
Script output returned to client
If reload_config is specified and file changed, Navigator reloads automatically

See CGI Scripts Documentation for detailed information and examples.

Future Use Case Ideas¶

While Navigator currently focuses on the use cases above, there are several interesting directions worth exploring based on production usage patterns and community feedback.

A/B Testing and Feature Flags¶

Route different users to different application instances based on cookies, headers, or URL parameters. This would enable:

Testing new features with a subset of users
Gradual feature rollouts
Canary deployments at the proxy level
User cohort experimentation

Potential Configuration:

routing:
  ab_tests:
    - name: new-ui-test
      header: X-Feature-Flag
      value: new-ui
      target: /v2
      percentage: 10  # 10% of users

Rate Limiting and Protection¶

Per-tenant or per-IP rate limiting to prevent abuse:

Automatic blocking of suspicious traffic patterns
Per-tenant request quotas
Integration with fail2ban or similar tools
DDoS protection at the application level

Potential Configuration:

rate_limiting:
  global:
    requests_per_minute: 1000
  per_tenant:
    requests_per_minute: 100
  per_ip:
    requests_per_minute: 60

Health Checks and Circuit Breakers¶

Automatic health monitoring with resilience patterns:

Health checks for tenant apps before proxying (already implemented)
Circuit breaker patterns to prevent cascading failures
Graceful degradation when services are unavailable
Automatic retry with exponential backoff for Fly-Replay fallback (already implemented)

Potential Configuration:

health_checks:
  interval: 30s
  timeout: 5s
  unhealthy_threshold: 3

circuit_breaker:
  failure_threshold: 5
  timeout: 60s

Enhanced Observability¶

Integration with observability platforms:

Datadog, New Relic, Honeycomb integration
OpenTelemetry distributed tracing
Prometheus metrics endpoint (planned)
Comprehensive monitoring across all tenants

Potential Configuration:

observability:
  opentelemetry:
    enabled: true
    endpoint: http://collector:4318
  prometheus:
    enabled: true
    path: /metrics

Request Transformation¶

Advanced request/response manipulation:

Header injection and removal
Request/response body transformation
Content negotiation
Protocol upgrades (HTTP/1.1 → HTTP/2)

Geographic Routing Intelligence¶

Smarter geographic routing based on:

Client IP geolocation
Latency measurements
Regional capacity
Time-of-day patterns

These ideas represent potential evolution paths as usage patterns and requirements emerge from production deployments. Community feedback and real-world needs will guide prioritization.

Choosing Your Use Case¶

Your Scenario	Recommended Use Case	Key Features
Multiple customers with separate DBs	Multi-Tenant (#1)	Process isolation, template variables
Global deployment on Fly.io	Auto-Suspend (#2)	Cost optimization, lifecycle hooks
Rails 8 with Solid Cable	WebSockets (#3)	Process management, routing
Multi-region deployment	Dynamic Routing (#4)	Fly-Replay, maintenance pages

Use Cases¶

Background¶

Quick Start¶

Use Case 1: Multi-Tenant and Monorepos¶

Capabilities¶

Configuration Example¶

How it works¶

Use Case 2: Machine Auto-Suspend (Fly.io)¶

How it works¶

Lifecycle Hooks¶

Configuration Example¶

Use Case 3: WebSocket Support¶

Background¶

How it works¶

Configuration Example¶

WebSocket Connection Tracking¶

Use Case 4: Dynamic Routing with Fly-Replay¶

Fly-Replay Modes¶

Navigator's Approach¶

Configuration Example¶

Features¶

Use Case 5: Lightweight Admin Endpoints with CGI¶

Benefits¶

Configuration Example¶

Use Cases for CGI Scripts¶

How it Works¶

Future Use Case Ideas¶

A/B Testing and Feature Flags¶

Rate Limiting and Protection¶

Health Checks and Circuit Breakers¶

Enhanced Observability¶

Request Transformation¶

Geographic Routing Intelligence¶

Choosing Your Use Case¶

See Also¶