{"id":36220589,"url":"https://github.com/dannysimfukwe/stable-rails","last_synced_at":"2026-05-04T21:02:42.270Z","repository":{"id":331470166,"uuid":"1125513994","full_name":"dannysimfukwe/stable-rails","owner":"dannysimfukwe","description":"Stable is a Zero-config cross-platform CLI tool to manage local Rails applications with automatic Caddy setup, local trusted HTTPS certificates, and easy start/stop functionality. Supports macOS, Linux, and Windows.","archived":false,"fork":false,"pushed_at":"2026-01-07T16:12:06.000Z","size":538,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-11T10:43:43.855Z","etag":null,"topics":["developer-tools","development-environment","devops","devops-tools","rails","zero-config"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/dannysimfukwe.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T21:38:06.000Z","updated_at":"2026-01-07T16:12:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dannysimfukwe/stable-rails","commit_stats":null,"previous_names":["dannysimfukwe/stable-rails"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dannysimfukwe/stable-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannysimfukwe%2Fstable-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannysimfukwe%2Fstable-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannysimfukwe%2Fstable-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannysimfukwe%2Fstable-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dannysimfukwe","download_url":"https://codeload.github.com/dannysimfukwe/stable-rails/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannysimfukwe%2Fstable-rails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32624693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["developer-tools","development-environment","devops","devops-tools","rails","zero-config"],"created_at":"2026-01-11T04:56:15.466Z","updated_at":"2026-05-04T21:02:42.255Z","avatar_url":"https://github.com/dannysimfukwe.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stable CLI\n\nStable is a cross-platform CLI tool to manage local Rails applications with automatic Caddy setup, local trusted HTTPS certificates, and easy start/stop functionality. Supports macOS, Linux, and Windows.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"stable-demo.gif\" alt=\"Stable CLI Demo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## Features\n\n- Add and remove Rails apps.\n- Automatically generate and manage local HTTPS certificates using `mkcert`.\n- Automatically assign `.test` domains.\n- Start individual apps or start all registered apps at once.\n- Stop individual apps or stop all running apps at once.\n- Restart Rails apps.\n- Reload Caddy after adding/removing apps.\n- List all registered apps.\n- Upgrade, downgrade, or switch Ruby versions for apps.\n- Run multiple apps with different Ruby versions simultaneously.\n\n## Installation\n\n```bash\ngem install stable-cli-rails\n```\n\n### Or add it to your Gemfile\n```bash\ngem \"stable-cli-rails\"\n```\n\n## Stable Desktop App\n\nFor a native macOS GUI experience, download the Stable Desktop app:\n\n**[Download Stable Desktop for macOS](https://github.com/dannysimfukwe/stable-rails/releases/latest)**\n\nThe desktop app provides:\n- Menu bar tray icon for quick access\n- Native GUI for managing Rails apps\n- Start/stop apps with a click\n- Rails console access\n- Database table viewer\n- App logs viewer\n\n\u003e **Note**: Both the CLI and Desktop app share the same projects directory (`~/StableCaddy/projects`), so you can use either one interchangeably.\n\n## Platform-Specific Setup\n\n### macOS\n```bash\n# Install Homebrew if not already installed\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Install Stable CLI\ngem install stable-cli-rails\n\n# Run setup\nstable setup\n```\n\n### Linux (Ubuntu/Debian)\n```bash\n# Update package lists and install build tools\nsudo apt update\nsudo apt install -y build-essential curl\n\n# Install Ruby (if not already installed)\nsudo apt install -y ruby ruby-dev\n\n# Install Stable CLI\ngem install stable-cli-rails\n\n# Run setup\nstable setup\n```\n\n### Linux (CentOS/RHEL)\n```bash\n# Install build tools\nsudo yum install -y gcc gcc-c++ make curl\n\n# Install Ruby (if not already installed)\nsudo yum install -y ruby ruby-devel\n\n# Install Stable CLI\ngem install stable-cli-rails\n\n# Run setup\nstable setup\n```\n\n### Windows\n```bash\n# Install Ruby from https://rubyinstaller.org/\n# Install Git for Windows (includes Git Bash)\n# Install dependencies manually:\n# - Caddy: https://caddyserver.com/docs/install\n# - mkcert: https://github.com/FiloSottile/mkcert/releases\n# - PostgreSQL: https://www.postgresql.org/download/windows/\n# - MySQL: https://dev.mysql.com/downloads/mysql/\n\n# Install Stable CLI\ngem install stable-cli-rails\n\n# Run setup (may require manual dependency installation)\nstable setup\n```\n\n## Setup\n\nInitialize Caddy home and required directories:\n\n```bash\nstable setup\n```\n\nThis will create:\n- `~/StableCaddy/` for Caddy configuration.\n- `~/StableCaddy/certs` for generated certificates.\n- `~/StableCaddy/projects` for Rails applications.\n- `~/StableCaddy/Caddyfile` for Caddy configuration.\n\n## CLI Commands\n\n### List apps\n\n```bash\n# List all registered apps\nstable list\n```\n\nLists all registered apps and their domains.\n\n### Setup Stable environment\n\n```bash\nstable setup\n```\n\nInitializes the Stable environment by creating required directories and installing dependencies. This is required before using other Stable commands.\n\n### Create a new Rails app\n\n```bash\n# Create a new Rails app with options\nstable new myapp [--ruby 3.4.4] [--rails 8.1.1] [--skip-ssl] [--db --mysql] [--db --postgres]\n\n# Create a new Rails app with default sqlite\nstable new myapp\n```\n\nCreates a new Rails app, generates `.ruby-version`, installs Rails, adds the app to Stable, and optionally secures it with HTTPS.\n\n#### Database Support\n\nYou can create Rails apps with integrated database support using the `--mysql` or `--postgres` flags. Stable will handle gem installation, database creation, and configuration automatically.\n\n```bash\n# Create a new Rails app with PostgreSQL\nstable new myapp --db --postgres\n\n# Create a new Rails app with MySQL\nstable new myapp --db --mysql\n```\n\n- The CLI will prompt for the database root username and password during setup.  \n- The corresponding gem (`pg` for PostgreSQL or `mysql2` for MySQL) will be added to the Gemfile automatically.  \n- `database.yml` will be configured for `development`, `test`, and `production` environments.  \n- The database will be created and prepared (`rails db:prepare`) automatically.  \n\n### Add a Rails app\n\n```bash\nstable add /path/to/rails_app\n```\n\nThis will:  \n- Register the app.  \n- Add a `/etc/hosts` entry.  \n- Generate local trusted HTTPS certificates.  \n- Add a Caddy reverse proxy block.  \n- Reload Caddy.\n\n### Remove a Rails app\n\n```bash\nstable remove app_name\n```\n\nThis will:\n- Remove the app from registry.\n- Remove `/etc/hosts` entry.\n- Remove the Caddy reverse proxy block.\n- Reload Caddy.\n\n**Note:** This only removes the app from Stable management. The project files remain intact.\n\n### Destroy an app (DANGER!)\n\n```bash\nstable destroy app_name\n```\n\n**⚠️ DANGER: This permanently deletes the application and ALL its files!**\n\nThis command requires confirmation - you must type the exact app name to proceed. It will:\n\n- Stop the app if it's running\n- Remove the app from registry\n- Remove `/etc/hosts` entry\n- Remove the Caddy reverse proxy block\n- **Clean up RVM gemset** (e.g., `3.4.7@appname`) *on macOS/Linux*\n- **Delete the entire project directory and all files**\n- Reload Caddy\n\n**Example:**\n```bash\n$ stable destroy my-app\n⚠️  WARNING: This will permanently delete the application 'my-app'\n   Path: /Users/user/stable/projects/my-app\n   Domain: my-app.test\n   This action CANNOT be undone!\n\nType 'my-app' to confirm destruction: my-app\n\n🗑️  Destroying my-app...\n   Deleting project directory...\n✅ Successfully destroyed my-app\n```\n\n### Start an app\n\n```bash\nstable start app_name\n```\n\nStarts the Rails server on the assigned port and ensures Caddy is running with the proper reverse proxy. Rails logs can be viewed in your terminal.\n\n### Start all apps\n\n```bash\nstable start-all\n```\n\nStarts all registered Rails applications. This command checks each app to see if it's already running and only starts the ones that are stopped, providing feedback for each app started along with the total count.\n\n### Stop an app\n\n```bash\nstable stop app_name\n```\n\nStops the Rails server running on the assigned port.\n\n### Stop all apps\n\n```bash\nstable stop-all\n```\n\nStops all running Rails applications registered in Stable. This command checks each app to see if it's actually running before attempting to stop it, and provides feedback for each app stopped along with the total count.\n\n### Restart an app\n\n```bash\nstable restart app_name\n```\n\nStops and then starts the Rails server, useful for reloading code changes or configuration updates.\n\n### Open an app in the browser\n\n```bash\nstable open app_name\n```\n\nOpens an app in the browser.\n\n### Open app folder in editor\n\n```bash\nstable workdir app_name [--editor vscode]\n```\n\nOpens the app folder in a code editor (defaults to vscode). Supported editors include vscode, sublime, atom, etc.\n\n### Share an app via public tunnel\n\n```bash\nstable share app_name [provider] [--qrcode]\n```\n\nShares the app via a public tunnel using the specified provider (ngrok or stable, defaults to ngrok). Optionally generates a QR code for the shared URL.\n\n### Secure an app manually\n\n```bash\nstable secure app_name.test\n```\n\nGenerates or updates trusted local HTTPS certificates and reloads Caddy.\n\n### Reload Caddy\n\n```bash\nstable caddy_reload\n```\n\nReloads Caddy configuration after changes.\n\n### Health check\n\n```bash\nstable doctor\n```\n\nChecks the environment, RVM/Ruby, Caddy, mkcert, and app readiness.\n\n### Change Ruby version for an app\n\n```bash\nstable upgrade-ruby myapp 3.4.7\n```\n\nChanges the Ruby version for a specific app (upgrade, downgrade, or switch). Automatically handles gemset cleanup and recreation for clean environment transitions.\n\n#### Cross-Platform Support\n\n- **macOS/Linux**: Full automation with RVM gemsets and automatic gem installation\n- **Windows**: Updates app configuration and provides instructions for manual Ruby/bundle installation\n\n#### Examples\n\n```bash\n# Upgrade Ruby version\nstable upgrade-ruby myapp 3.4.7\n\n# Downgrade Ruby version\nstable upgrade-ruby myapp 3.3.0\n\n# Patch version switch\nstable upgrade-ruby myapp 3.4.5\n```\n\n**macOS/Linux**: Creates fresh RVM gemsets and installs gems automatically\n**Windows**: Updates `.ruby-version` file and provides manual installation instructions\n\nThe command updates `.ruby-version`, cleans up old gemsets (on Unix), creates fresh environments, and ensures gem compatibility.\n\n\n\n## Testing\n\nStable uses RSpec for testing. To run the test suite:\n\n```bash\n# Run all tests\nbundle exec rspec\n\n# Run specific test file\nbundle exec rspec spec/commands/new_spec.rb\n\n# Run with Rake (same as bundle exec rspec)\nrake spec\n```\n\nThe test suite includes:\n- Unit tests for all services and commands\n- Integration tests for CLI functionality\n- Cross-platform compatibility tests\n- Database integration tests\n\n### Test Structure\n\n```\nspec/\n├── cli/                    # CLI integration tests\n├── commands/              # Command-specific tests\n├── services/              # Service layer tests\n│   └── database/          # Database-specific tests\n├── spec_helper.rb         # Test configuration\n└── spec.opts             # RSpec options\n```\n\n## Paths\n\n- Caddy home: `~/StableCaddy`\n- Caddyfile: `~/StableCaddy/Caddyfile`\n- Certificates: `~/StableCaddy/certs`\n- Projects directory: `~/StableCaddy/projects`\n- App configurations: `~/StableCaddy/projects/{app_name}/{app_name}.yml`  \n\n## Dependencies\n\n### Package Manager (one of):\n- **macOS**: Homebrew\n- **Linux**: APT (Ubuntu/Debian), YUM/DNF (CentOS/RHEL), or Pacman (Arch)\n- **Windows**: Manual installation required\n\n### Core Dependencies:\n- **Caddy**: Web server and reverse proxy\n- **mkcert**: Local HTTPS certificate generation\n- **Ruby version manager**: RVM, rbenv, or chruby\n- **PostgreSQL**: Database server (optional)\n- **MySQL**: Database server (optional)\n\n`stable setup` will attempt to install missing dependencies automatically on macOS and Linux. On Windows, manual installation is required.\n\n## Notes\n\n- Make sure to run `stable setup` initially.\n- **macOS/Linux**: Requires `sudo` to modify `/etc/hosts`.\n- **Windows**: Requires administrator privileges to modify `C:\\Windows\\System32\\drivers\\etc\\hosts`.\n- Rails apps are started on ports assigned by Stable (default 3000+).\n- Domains are automatically suffixed with `.test`.\n- **Windows**: Some features may have limited support. Manual installation of dependencies is required.\n\n## How to Contribute\n\nWe welcome contributions to Stable! Here's how to get started:\n\n### Development Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/your-username/stable-cli.git\n   cd stable-cli\n   ```\n\n2. **Install dependencies**\n   ```bash\n   bundle install\n   ```\n\n3. **Run tests**\n   ```bash\n   bundle exec rspec\n   ```\n\n4. **Install locally for testing**\n   ```bash\n   gem build stable-cli-rails.gemspec\n   gem install stable-cli-rails-*.gem\n   ```\n\n### Development Workflow\n\n1. **Create a feature branch**\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n\n2. **Make your changes** and ensure tests pass\n   ```bash\n   bundle exec rspec\n   ```\n\n3. **Follow the coding standards**\n   - Use `bundle exec rubocop` to check code style\n   - Write tests for new features\n   - Update documentation as needed\n\n4. **Submit a pull request**\n   - Ensure all tests pass\n   - Update CHANGELOG.md if applicable\n   - Provide a clear description of changes\n\n### Cross-Platform Testing\n\nSince Stable supports multiple platforms, please test on:\n- macOS (primary development platform)\n- Linux (Ubuntu/Debian recommended)\n- Windows (if possible, or document limitations)\n\n### Reporting Issues\n\nWhen reporting bugs, please include:\n- Your operating system and version\n- Ruby version (`ruby -v`)\n- Steps to reproduce the issue\n- Expected vs actual behavior\n\n## License\n\nMIT License\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannysimfukwe%2Fstable-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannysimfukwe%2Fstable-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannysimfukwe%2Fstable-rails/lists"}