{"id":30285878,"url":"https://github.com/rubys/navigator","last_synced_at":"2025-08-16T20:44:18.009Z","repository":{"id":309201840,"uuid":"1035462386","full_name":"rubys/navigator","owner":"rubys","description":"Modern Go-based multi-tenant Rails proxy with HTTP caching, structured logging, and automatic process recovery","archived":false,"fork":false,"pushed_at":"2025-08-10T15:14:26.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T15:26:25.120Z","etag":null,"topics":["chi-router","go","http-cache","multi-tenant","process-management","proxy","rails","structured-logging"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubys.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-10T13:04:04.000Z","updated_at":"2025-08-10T15:14:10.000Z","dependencies_parsed_at":"2025-08-16T03:18:24.104Z","dependency_job_id":null,"html_url":"https://github.com/rubys/navigator","commit_stats":null,"previous_names":["rubys/navigator"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/rubys/navigator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubys%2Fnavigator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubys%2Fnavigator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubys%2Fnavigator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubys%2Fnavigator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubys","download_url":"https://codeload.github.com/rubys/navigator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubys%2Fnavigator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270769206,"owners_count":24642069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chi-router","go","http-cache","multi-tenant","process-management","proxy","rails","structured-logging"],"created_at":"2025-08-16T20:44:13.808Z","updated_at":"2025-08-16T20:44:17.984Z","avatar_url":"https://github.com/rubys.png","language":"Go","readme":"# Navigator\n\nNavigator is a modern Go-based web server that replaces nginx/Passenger for multi-tenant Rails applications. It provides intelligent request routing, dynamic process management, authentication, HTTP/2 support, and high-performance caching with flexible configuration options.\n\n## Features\n\n- **Multi-tenant Support**: Routes requests to appropriate Rails instances based on URL patterns\n- **Dynamic Process Management**: Starts and stops Puma processes on-demand with configurable idle timeout\n- **HTTP Caching**: 100MB memory cache with LRU eviction for static assets (70% performance improvement)\n- **Structured Logging**: JSON logs with contextual fields using logrus\n- **HTTP/2 Support**: Modern HTTP/2 protocol with h2c (cleartext) support\n- **Automatic Process Recovery**: Detects crashed processes and restarts them automatically\n- **Authentication**: HTTP Basic authentication support via htpasswd files\n- **Smart Asset Serving**: Different cache TTLs for fingerprinted vs regular assets\n- **Compression**: Gzip compression for text-based content\n- **Flexible Configuration**: YAML files, environment variables, and command-line flags\n- **Modern CLI**: Cobra-powered CLI with subcommands and comprehensive help\n\n## Architecture\n\nBuilt with modern Go libraries:\n- **[Chi Router](https://github.com/go-chi/chi)**: Fast HTTP router with middleware support\n- **[Logrus](https://github.com/sirupsen/logrus)**: Structured logging with JSON output\n- **[HTTP Cache](https://github.com/victorspringer/http-cache)**: Memory-based caching with LRU eviction\n- **[Cobra](https://github.com/spf13/cobra)**: Modern CLI framework with subcommands\n- **[Viper](https://github.com/spf13/viper)**: Configuration management with YAML/ENV support\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/rubys/navigator.git\ncd navigator\n\n# Install dependencies\ngo mod download\n\n# Build the binary\ngo build -o navigator cmd/navigator/main.go\n```\n\n## Quick Start\n\n```bash\n# Start Navigator with command-line flags\n./navigator serve --root /path/to/rails/app --listen :3000\n\n# Or start in the current directory (uses '.' as default)\n./navigator serve\n\n# Or use environment variables\nNAVIGATOR_RAILS_ROOT=/path/to/rails/app ./navigator serve\n\n# Or use a configuration file (automatically looks for config/navigator.yml)\n./navigator serve\n\n# Or specify a custom configuration file\n./navigator serve --config /path/to/navigator.yaml\n\n# Get help and see all available commands\n./navigator --help\n./navigator serve --help\n```\n\n## Configuration\n\nNavigator supports three configuration methods (in order of precedence):\n\n### 1. Command-Line Flags (Highest Priority)\n\n```bash\n./navigator serve \\\n  --root /path/to/rails/app \\\n  --listen :3000 \\\n  --url-prefix /showcase \\\n  --max-puma 20 \\\n  --idle-timeout 10m \\\n  --log-level debug \\\n  --htpasswd /path/to/htpasswd\n```\n\n### 2. Environment Variables\n\nAll configuration can be set via environment variables with the `NAVIGATOR_` prefix:\n\n```bash\nexport NAVIGATOR_RAILS_ROOT=\"/path/to/rails/app\"\nexport NAVIGATOR_SERVER_LISTEN=\":3000\"\nexport NAVIGATOR_SERVER_URL_PREFIX=\"/showcase\"\nexport NAVIGATOR_MANAGER_MAX_PUMA=20\nexport NAVIGATOR_MANAGER_IDLE_TIMEOUT=\"10m\"\nexport NAVIGATOR_AUTH_HTPASSWD_FILE=\"/path/to/htpasswd\"\nexport NAVIGATOR_LOGGING_LEVEL=\"debug\"\n\n./navigator serve\n```\n\n### 3. YAML Configuration File (Lowest Priority)\n\nNavigator automatically looks for `config/navigator.yml` relative to the root directory. You can also create a custom `navigator.yaml` file:\n\n```yaml\nserver:\n  listen: \":3000\"\n  url_prefix: \"/showcase\"\n\nrails:\n  root: \"/path/to/rails/app\"\n  showcases: \"config/tenant/showcases.yml\"\n  db_path: \"db\"\n  storage: \"storage\"\n\nmanager:\n  max_puma: 20\n  idle_timeout: \"10m\"\n\nauth:\n  htpasswd_file: \"/path/to/htpasswd\"\n\nlogging:\n  level: \"debug\"\n```\n\nThen run:\n```bash\n# Uses config/navigator.yml if present in root directory\n./navigator serve\n\n# Or specify a custom config file\n./navigator serve --config navigator.yaml\n```\n\n### Configuration Options\n\n| Option | CLI Flag | Environment Variable | Default | Description |\n|--------|----------|---------------------|---------|-------------|\n| Rails Root | `--root` | `NAVIGATOR_RAILS_ROOT` | `.` | Application root directory |\n| Listen Address | `--listen` | `NAVIGATOR_SERVER_LISTEN` | `:3000` | HTTP server bind address |\n| URL Prefix | `--url-prefix` | `NAVIGATOR_SERVER_URL_PREFIX` | `/showcase` | URL prefix to strip |\n| Max Puma | `--max-puma` | `NAVIGATOR_MANAGER_MAX_PUMA` | `10` | Max concurrent Puma processes |\n| Idle Timeout | `--idle-timeout` | `NAVIGATOR_MANAGER_IDLE_TIMEOUT` | `5m` | Process idle timeout |\n| Htpasswd File | `--htpasswd` | `NAVIGATOR_AUTH_HTPASSWD_FILE` | `` | Authentication file path |\n| Log Level | `--log-level` | `NAVIGATOR_LOGGING_LEVEL` | `info` | Log level (debug/info/warn/error) |\n\n## Performance\n\nNavigator provides significant performance improvements:\n\n- **Static Asset Caching**: 70% faster response times (1.49ms → 0.45ms)\n- **Memory Cache**: 100MB LRU cache with 1-hour TTL\n- **Smart TTL**: 24-hour cache for fingerprinted assets\n- **HTTP/2**: Modern protocol support with multiplexing\n- **Compression**: Automatic gzip compression\n\n## Structured Logging\n\nAll logs are output in JSON format for easy parsing:\n\n```json\n{\n  \"level\": \"info\",\n  \"message\": \"HTTP request\",\n  \"method\": \"GET\",\n  \"path\": \"/studios/\",\n  \"status\": 200,\n  \"duration_ms\": 45,\n  \"remote_addr\": \"192.168.1.100\",\n  \"user_agent\": \"Mozilla/5.0...\",\n  \"request_id\": \"req-123\",\n  \"timestamp\": \"2025-08-10T12:00:00.000Z\"\n}\n```\n\nEnable debug logging for detailed tenant routing:\n```bash\n./navigator serve --rails-root /path/to/app --log-level debug\n```\n\n## CLI Commands\n\nNavigator provides several commands for different operations:\n\n### `navigator serve`\nStart the Navigator server (main command):\n```bash\n./navigator serve --rails-root /path/to/rails/app\n```\n\n### `navigator config validate`\nValidate configuration and display resolved settings:\n```bash\n./navigator config validate --rails-root /path/to/app\n./navigator config validate --config navigator.yaml\n```\n\nThis command will:\n- Load and validate configuration from all sources\n- Check that required files exist (Rails root, showcases.yml)\n- Display the final resolved configuration\n- Show configured tenants\n\n### `navigator version`\nDisplay version information:\n```bash\n./navigator version\n```\n\n### `navigator --help`\nShow comprehensive help:\n```bash\n./navigator --help           # Show all commands\n./navigator serve --help     # Show serve command options\n./navigator config --help    # Show config subcommands\n```\n\n## Rails Integration\n\n### showcases.yml Format\n\nNavigator expects a `showcases.yml` file with Ruby-style symbols:\n\n```yaml\n\"2025\":\n  raleigh:\n    :name: \"Raleigh Studio\"\n    :region: \"us-east\"\n    :events:\n      disney:\n        :name: \"Disney Theme\"\n        :date: \"2025-03-15\"\n      summer:\n        :name: \"Summer Showcase\"\n        :date: \"2025-07-20\"\n```\n\n### Environment Variables Set by Navigator\n\nFor each Rails instance, Navigator sets:\n\n- `RAILS_APP_DB`: Tenant database identifier (e.g., \"2025-raleigh-disney\")\n- `RAILS_APP_OWNER`: Tenant owner name\n- `RAILS_APP_SCOPE`: URL scope (e.g., \"2025/raleigh/disney\")\n- `DATABASE_URL`: SQLite database URL\n- `RAILS_STORAGE`: Storage path for the tenant\n- `RAILS_ENV`: Always \"production\"\n- `RAILS_PROXY_HOST`: Proxy host for URL generation\n\n## Multi-Tenant Routing\n\nNavigator routes requests based on URL patterns:\n\n- `/` → Redirects to `/studios/`\n- `/studios/` → `index` tenant\n- `/2025/raleigh/disney/` → `2025-raleigh-disney` tenant\n- Static assets served directly with caching\n\n## Process Management\n\n- **On-Demand Startup**: Puma processes start on first request\n- **Idle Cleanup**: Processes stopped after configurable timeout (default: 5 minutes)\n- **Automatic Recovery**: Crashed processes detected and restarted automatically\n- **Port Management**: Dynamic port allocation starting from 4000\n- **Health Monitoring**: Continuous process health checks\n\n## Authentication\n\nHTTP Basic authentication via htpasswd files:\n\n```bash\n# Create htpasswd file\nhtpasswd -c /path/to/htpasswd username\n\n# Add users\nhtpasswd /path/to/htpasswd another_user\n\n# Use with Navigator\n./navigator -rails-root /path/to/app -htpasswd /path/to/htpasswd\n```\n\nSupports APR1, Bcrypt, SHA, and Crypt hash formats.\n\n## Development\n\n### Project Structure\n\n```\nnavigator/\n├── cmd/navigator/          # Main application entry point\n├── internal/\n│   ├── cli/               # Cobra CLI commands and Viper configuration\n│   ├── config/            # Configuration and YAML parsing  \n│   ├── logger/            # Structured logging wrapper\n│   ├── manager/           # Puma process management\n│   ├── proxy/             # HTTP routing, caching, auth\n│   └── server/            # HTTP/2 server implementation\n├── config/                # Example configuration files\n├── go.mod                 # Go module definition\n├── README.md              # This file\n└── LICENSE               # MIT license\n```\n\n### Building\n\n```bash\n# Standard build\ngo build -o navigator cmd/navigator/main.go\n\n# Cross-compile for Linux\nGOOS=linux GOARCH=amd64 go build -o navigator cmd/navigator/main.go\n\n# Build with version info\ngo build -ldflags \"-X main.version=1.0.0\" -o navigator cmd/navigator/main.go\n```\n\n### Testing\n\n```bash\n# Run tests\ngo test ./...\n\n# With coverage\ngo test -cover ./...\n\n# With race detection  \ngo test -race ./...\n\n# Manual testing\ncurl http://localhost:3000/studios/\ncurl http://localhost:3000/2025/raleigh/disney/\n```\n\n## Deployment\n\n### Systemd Service\n\nCreate `/etc/systemd/system/navigator.service`:\n\n```ini\n[Unit]\nDescription=Navigator Rails Proxy\nAfter=network.target\n\n[Service]\nType=simple\nUser=rails\nWorkingDirectory=/opt/rails/app\nExecStart=/usr/local/bin/navigator serve --rails-root /opt/rails/app --listen :3000\nRestart=always\nRestartSec=10\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnable and start:\n```bash\nsudo systemctl enable navigator\nsudo systemctl start navigator\nsudo journalctl -u navigator -f  # View logs\n```\n\n### Docker\n\n```dockerfile\nFROM golang:1.22-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o navigator cmd/navigator/main.go\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nWORKDIR /app\nCOPY --from=builder /app/navigator .\nEXPOSE 3000\nCMD [\"./navigator\", \"serve\", \"--rails-root\", \"/app\"]\n```\n\n## Monitoring\n\nNavigator provides health check endpoints:\n\n- `GET /up` - Basic health check\n- `GET /health` - Detailed health check\n\nAll operations are logged with structured JSON including:\n- Request details (method, path, status, duration)\n- Process management events\n- Cache hit/miss statistics  \n- Error conditions with context\n\n## Troubleshooting\n\n### Common Issues\n\n**Port conflicts**: Navigator manages ports 4000+ automatically\n```bash\n./navigator serve --max-puma 50  # Increase port range\n```\n\n**Authentication failures**: Check htpasswd format\n```bash\n./navigator serve --log-level debug  # See auth details\n```\n\n**Tenant not found**: Verify showcases.yml symbols\n```bash\n# Correct: :name\n# Incorrect: name\n```\n\n**High memory usage**: Adjust cache size by editing source:\n```go\nmemory.AdapterWithCapacity(50000000)  // 50MB instead of 100MB\n```\n\n### Performance Tuning\n\n1. **Cache Size**: Adjust memory cache based on available RAM\n2. **Process Limits**: Set `max-puma` based on CPU cores\n3. **Idle Timeout**: Balance resource usage vs startup latency\n4. **Log Level**: Use \"warn\" or \"error\" in production for performance\n\n## Dependencies\n\n- **Go 1.22+**: Modern Go features and performance\n- **Chi v5**: HTTP router with middleware support\n- **Logrus**: Structured JSON logging\n- **HTTP-Cache**: Memory caching with LRU eviction\n- **Cobra**: Modern CLI framework with subcommands\n- **Viper**: Configuration management (YAML/ENV/flags)\n- **htpasswd**: Multi-format password file support\n- **YAML v3**: Configuration file parsing\n\n## Contributing\n\nPull requests welcome! Please ensure:\n- Code follows Go conventions (`go fmt`, `go vet`)\n- Tests pass (`go test ./...`)\n- Documentation is updated\n- Commit messages are descriptive\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: Use GitHub issue tracker\n- **Documentation**: See [CLAUDE.md](CLAUDE.md) for development details\n- **Performance**: All requests logged with timing information","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubys%2Fnavigator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubys%2Fnavigator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubys%2Fnavigator/lists"}