easy_caddy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15359e9854098ff355b15635597ff9979952d9224835eb31594676492fbd64d9
+  data.tar.gz: b3f4b62942373f0554e0d0ff92671bccb8fe7efd8ffef16038f4248c251687bb
+SHA512:
+  metadata.gz: 2cccf4fca5dbe0eb0148998507d67666b294dcc0233c34fd83b2789e6c18c44191981dc2391b9f319067bc183729078b2985994641f9247838134c3361efbdf2
+  data.tar.gz: d8c66f1dba6f6d32210c2a2cbfa910a1560668a7ea5e5a84cfe9e6371142036fcd0543035b488f9b415f9e1c6ac9c58b6ac1e17cc06006e6f71a9e8c057e45bf

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-06-09
+
+### Added
+
+- Initial public release.
+- Thor CLI `ecaddy` with commands: `setup`, `run`, `ensure`, `up`, `down`,
+  `list`, `edit`, `logs`, `remove`, `reload`, `status`, `doctor`, `audit`.
+- Single-source-of-truth path management via `EasyCaddy::Paths` — every
+  filesystem path derives from the `ECADDY_HOME` env var (defaults to
+  `~/.config/caddy`), keeping the tool fully redirectable for tests and
+  multi-user setups.
+- YAML registry (`ecaddy.yml`) tracking each site by name, enabled state,
+  and source Caddyfile path.
+- Conflict detection: `*.localhost` domain collisions and
+  `reverse_proxy localhost:PORT` port collisions across registered
+  fragments, plus TCP probing of upstream ports via `ecaddy doctor`.
+- Automatic rewrite of relative `output file` log paths to absolute paths
+  on registration, so Caddy (running as a background service detached from
+  the project directory) can write log files correctly.
+- One-shot machine bootstrap (`ecaddy setup`): Homebrew install of Caddy,
+  global Caddyfile scaffold, `caddy trust` for local-CA HTTPS, and
+  `brew services` start. Idempotent — safe to re-run.
+- Foreground `ecaddy run --site NAME` mode: registers the fragment, traps
+  `SIGTERM`/`SIGINT`, and unregisters on exit — designed to drop into a
+  Procfile alongside the Rails server.
+
+[0.1.0]: https://github.com/pniemczyk/easy_caddy/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pawel Niemczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,333 @@
+# ecaddy
+
+[![Gem Version](https://badge.fury.io/rb/easy_caddy.svg)](https://rubygems.org/gems/easy_caddy)
+[![Docs](https://img.shields.io/badge/docs-pniemczyk.github.io%2Feasy__caddy-blue)](https://pniemczyk.github.io/easy_caddy/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-orange)](CHANGELOG.md)
+
+**[📖 Documentation](https://pniemczyk.github.io/easy_caddy/)**  |  **[GitHub](https://github.com/pniemczyk/easy_caddy)**  |  **[Changelog](CHANGELOG.md)**
+
+One global [Caddy](https://caddyserver.com/) for all your local Rails projects.
+
+Instead of fighting port conflicts from multiple Caddy processes, `ecaddy` manages a single shared Caddy instance. Each project keeps its own `Caddyfile` — `ecaddy` copies it in and out of the global config on demand.
+
+## How it works
+
+```
+Browser
+  │
+  ▼
+Caddy  (~/.config/caddy/Caddyfile)
+  │         imports sites/*.caddy
+  ├── fishme.localhost   → localhost:3104
+  ├── letly.localhost    → localhost:3100
+  └── traiderb.localhost → localhost:3106
+```
+
+Each Rails project has its own `Caddyfile`. When you start the project, `ecaddy` copies it into `~/.config/caddy/sites/<name>.caddy` and reloads the global Caddy. When you stop, it removes the fragment and reloads again.
+
+## Installation
+
+```bash
+gem install easy_caddy
+ecaddy setup
+```
+
+`ecaddy setup` is a one-time bootstrap that:
+
+1. Installs Caddy via Homebrew if not already present
+2. Scaffolds `~/.config/caddy/{sites,disabled}/`
+3. Writes the global `Caddyfile` (with `import sites/*.caddy`)
+4. Symlinks it into `/opt/homebrew/etc/Caddyfile` so `brew services` picks it up
+5. Runs `caddy trust` to install the local CA in your system keychain (makes `https://*.localhost` green in browsers)
+6. Starts Caddy as a `brew services` background service
+
+Run `ecaddy setup` again at any time — every step is idempotent.
+
+### The `--site` option
+
+Every `ecaddy` command that registers or references a project uses a **site name** — a short identifier you choose, e.g. `fishme`. This name:
+
+- Determines the fragment filename: `~/.config/caddy/sites/fishme.caddy`
+- Is used by `up`, `down`, `edit`, `remove` to target the right project
+- Should be unique across all your local projects
+
+The name is **not** read from the Caddyfile — you always supply it explicitly with `--site fishme` (short: `-s fishme`). This keeps `ecaddy` compatible with any Caddyfile content.
+
+## Project setup
+
+Each project needs two things: a `Caddyfile` and a Procfile line.
+
+### 1. Write your project Caddyfile
+
+Put a `Caddyfile` in your project root. Write it however you need — `ecaddy` treats it as read-only source. One automatic transform is applied on copy: relative `output file` log paths are rewritten to absolute paths so Caddy (running as a background service with no relation to your project directory) can actually write the log files.
+
+```caddy
+# Caddyfile (in your Rails project root)
+
+fishme.localhost {
+  handle /vite-dev/* {
+    reverse_proxy localhost:3054
+  }
+
+  reverse_proxy localhost:3104
+  tls internal
+
+  log {
+    level INFO
+    output file log/caddy.log {
+      roll_size 2mb
+      roll_keep 5
+      roll_keep_for 48h
+    }
+  }
+}
+
+vite.fishme.localhost {
+  reverse_proxy localhost:3054
+  tls internal
+}
+```
+
+Pick unique ports across your projects. Common pattern:
+
+| Project  | App port | Vite port |
+|----------|----------|-----------|
+| fishme   | 3104     | 3054      |
+| letly    | 3100     | 3050      |
+| traiderb | 3106     | 3056      |
+
+### 2. Add a Procfile line
+
+```procfile
+# Procfile.dev
+
+web:   bin/rails server -p 3104
+js:    yarn dev
+caddy: ecaddy run --config ./Caddyfile --site fishme
+```
+
+When foreman (or overmind) starts, `ecaddy run` copies your `Caddyfile` into the global config and reloads Caddy. When you press `Ctrl-C`, it removes the fragment and reloads again — the domain disappears cleanly.
+
+### 3. Allow `.localhost` in Rails
+
+```ruby
+# config/environments/development.rb
+
+config.hosts << /.*\.localhost/
+```
+
+### 4. Start your project
+
+```bash
+bin/dev
+```
+
+Visit `https://fishme.localhost` — done.
+
+## Commands
+
+### `ecaddy setup`
+
+One-time machine bootstrap. Install Caddy, scaffold the global config, trust the local CA, start the brew service.
+
+```bash
+ecaddy setup
+```
+
+---
+
+### `ecaddy run`
+
+Register a project Caddyfile, block, and unregister on shutdown. Use in `Procfile.dev`.
+
+```bash
+ecaddy run --config ./Caddyfile --site fishme
+ecaddy run -c ./Caddyfile -s fishme
+```
+
+On `SIGTERM` or `SIGINT`, the fragment is removed and Caddy is reloaded before the process exits.
+
+Relative `output file` log paths in the Caddyfile are automatically rewritten to absolute paths (resolved from the directory of `--config`) before the fragment is installed.
+
+---
+
+### `ecaddy ensure`
+
+One-shot variant of `run`. Copies the Caddyfile, reloads Caddy, exits immediately. The site stays registered until you run `ecaddy down` or `ecaddy remove`.
+
+```bash
+ecaddy ensure --config ./Caddyfile --site fishme
+```
+
+Useful in CI or shell scripts where you want Caddy configured but don't need a foreground process.
+
+---
+
+### `ecaddy list`
+
+Show all registered sites.
+
+```bash
+ecaddy list
+ecaddy list --format json
+```
+
+```
+┌──────────┬────────┬──────────────────────────────────────────────┬────────────┬──────────────────────────┐
+│ Name     │ Status │ Domains                                      │ Ports      │ Source                   │
+├──────────┼────────┼──────────────────────────────────────────────┼────────────┼──────────────────────────┤
+│ fishme   │ up     │ fishme.localhost, vite.fishme.localhost       │ 3054, 3104 │ /projects/fishme/Caddyfile │
+│ letly    │ down   │ letly.localhost, vite.letly.localhost         │ 3050, 3100 │ /projects/letly/Caddyfile  │
+└──────────┴────────┴──────────────────────────────────────────────┴────────────┴──────────────────────────┘
+```
+
+---
+
+### `ecaddy up NAME` / `ecaddy down NAME`
+
+Enable or disable a registered site without removing it.
+
+```bash
+ecaddy down fishme   # moves sites/fishme.caddy → disabled/fishme.caddy, reloads
+ecaddy up fishme     # moves disabled/fishme.caddy → sites/fishme.caddy, reloads
+```
+
+---
+
+### `ecaddy status`
+
+Show global Caddy state and per-site health (whether the upstream app is actually running).
+
+```bash
+ecaddy status
+```
+
+```
+  Caddy service: running
+  Config:        /Users/you/.config/caddy/Caddyfile
+
+  fishme               up
+    fragment: /Users/you/.config/caddy/sites/fishme.caddy
+    source:   /projects/fishme/Caddyfile
+  letly                up (app not running)
+    fragment: /Users/you/.config/caddy/sites/letly.caddy
+    source:   /projects/letly/Caddyfile
+```
+
+---
+
+### `ecaddy doctor`
+
+Scan all registered sites for port/domain conflicts and dead upstreams.
+
+```bash
+ecaddy doctor
+```
+
+Exits `0` if all clear or only INFO findings. Exits `1` on any BLOCK.
+
+| Severity | Meaning |
+|----------|---------|
+| `BLOCK`  | Two sites share a port or domain — one will fail |
+| `WARN`   | A port is bound by an unexpected process |
+| `INFO`   | Upstream not listening (app not started) |
+
+---
+
+### `ecaddy edit NAME`
+
+Open a site's fragment in `$EDITOR`. Caddy is validated and reloaded after you save.
+
+```bash
+ecaddy edit fishme
+```
+
+This edits the copy in `~/.config/caddy/sites/fishme.caddy`, not your project source. Re-run `ecaddy run` (or `ecaddy ensure`) to sync from your project `Caddyfile` again.
+
+---
+
+### `ecaddy remove NAME`
+
+Remove a site's fragment and registry entry entirely.
+
+```bash
+ecaddy remove fishme
+ecaddy remove fishme --force   # skip confirmation
+```
+
+---
+
+### `ecaddy reload`
+
+Validate the global config and reload Caddy.
+
+```bash
+ecaddy reload
+```
+
+---
+
+### `ecaddy version`
+
+```bash
+ecaddy version
+# ecaddy 0.1.0
+```
+
+## Global config layout
+
+```
+~/.config/caddy/
+  Caddyfile           # global root: { admin ... } + import sites/*.caddy
+  ecaddy.yml          # registry: name → { enabled, source_path }
+  sites/
+    fishme.caddy      # enabled fragments — loaded by Caddy
+    letly.caddy
+  disabled/
+    traiderb.caddy    # disabled fragments — preserved, not loaded
+```
+
+The global `Caddyfile` is also symlinked at `/opt/homebrew/etc/Caddyfile` so `brew services start caddy` picks it up automatically.
+
+## Conflict detection
+
+Before registering any Caddyfile, `ecaddy` parses it and checks:
+
+- **Domain collision** — same `*.localhost` domain already registered by another enabled site → BLOCK
+- **Port collision** — same `reverse_proxy localhost:PORT` already in use by another site → BLOCK
+
+These checks run on `ecaddy run`, `ecaddy ensure`, and `ecaddy up`. Run `ecaddy doctor` at any time for a full cross-site audit.
+
+## Environment variable
+
+Set `ECADDY_HOME` to override the config root (defaults to `~/.config/caddy`). Useful for testing:
+
+```bash
+ECADDY_HOME=/tmp/ecaddy_test ecaddy list
+```
+
+## Development
+
+```bash
+bin/setup              # bundle install
+bundle exec rspec      # run the full spec suite
+bundle exec rubocop    # lint
+bin/console            # IRB session with easy_caddy preloaded
+```
+
+To run the CLI against the local source without installing the gem:
+
+```bash
+bundle exec exe/ecaddy <command>
+```
+
+Cutting a release: bump `EasyCaddy::VERSION` in `lib/easy_caddy/version.rb`, add a `CHANGELOG.md` entry, commit, then `bundle exec rake release` — that tags the commit and pushes the gem to RubyGems (requires `gem signin` first).
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/pniemczyk/easy_caddy>. Please run the spec suite and `rubocop` before opening a PR.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/exe/ecaddy

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/easy_caddy'
+
+EasyCaddy::CLI.start(ARGV)

data/lib/easy_caddy/caddy.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative 'paths'
+
+module EasyCaddy
+  module Caddy
+    BINARY = 'caddy'
+
+    def self.installed?
+      system('which caddy > /dev/null 2>&1')
+    end
+
+    def self.validate(caddyfile = Paths.caddyfile)
+      system("#{BINARY} validate --config #{caddyfile} 2>&1")
+    end
+
+    def self.validate!(caddyfile = Paths.caddyfile)
+      return unless caddyfile.exist?
+
+      out = `#{BINARY} validate --config #{caddyfile} 2>&1`
+      raise "Caddy config invalid:\n#{out}" unless $CHILD_STATUS.success?
+    end
+
+    def self.reload(caddyfile = Paths.caddyfile)
+      unless caddyfile.exist?
+        warn '  [ecaddy] Skipping reload — global Caddyfile not found. Run `ecaddy setup` first.'
+        return
+      end
+
+      out = `#{BINARY} reload --config #{caddyfile} 2>&1`
+      raise "Caddy reload failed:\n#{out}" unless $CHILD_STATUS.success?
+    end
+
+    def self.trust
+      system("#{BINARY} trust")
+    end
+
+    def self.running?
+      pid = brew_service_pid
+      pid && pid > 0
+    end
+
+    def self.start_service
+      system('brew services start caddy')
+    end
+
+    def self.restart_service
+      system('brew services restart caddy')
+    end
+
+    def self.brew_service_pid
+      output = `brew services list 2>/dev/null | grep '^caddy '`
+      m = output.match(/(\d+)/)
+      m&.captures&.first&.to_i
+    end
+
+    def self.process_pid
+      out = `pgrep -f 'caddy run' 2>/dev/null`.strip
+      return nil if out.empty?
+
+      out.lines.first.to_i
+    end
+
+    def self.install_via_brew
+      system('brew install caddy')
+    end
+  end
+end

data/lib/easy_caddy/cli.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'version'
+require_relative 'commands/setup'
+require_relative 'commands/remove'
+require_relative 'commands/edit'
+require_relative 'commands/list'
+require_relative 'commands/up'
+require_relative 'commands/down'
+require_relative 'commands/status'
+require_relative 'commands/doctor'
+require_relative 'commands/reload'
+require_relative 'commands/ensure'
+require_relative 'commands/run'
+require_relative 'commands/logs'
+require_relative 'commands/audit'
+
+module EasyCaddy
+  class CLI < Thor
+    def self.exit_on_failure? = true
+
+    desc 'setup', 'One-time machine bootstrap: install Caddy, scaffold config, start service'
+    def setup
+      require 'tty-prompt'
+      Commands::Setup.new(prompt: TTY::Prompt.new).call
+    end
+
+    desc 'remove NAME', 'Remove a site from global Caddy and delete its fragment'
+    option :force, type: :boolean, default: false, aliases: '-f', desc: 'Skip confirmation'
+    def remove(name)
+      require 'tty-prompt'
+      Commands::Remove.new(name: name, force: options[:force], prompt: TTY::Prompt.new).call
+    end
+
+    desc 'edit NAME', 'Open a site fragment in $EDITOR and reload Caddy'
+    def edit(name)
+      Commands::Edit.new(name: name).call
+    end
+
+    desc 'list', 'List all registered sites'
+    option :format, type: :string, default: 'table', aliases: '-f', desc: 'Output format: table or json'
+    def list
+      Commands::List.new(format: options[:format]).call
+    end
+
+    desc 'up NAME', 'Enable a disabled site and reload Caddy'
+    def up(name)
+      Commands::Up.new(name: name).call
+    end
+
+    desc 'down NAME', 'Disable an enabled site and reload Caddy'
+    def down(name)
+      Commands::Down.new(name: name).call
+    end
+
+    desc 'status', 'Show global Caddy state and per-site health'
+    def status
+      Commands::Status.new.call
+    end
+
+    desc 'doctor', 'Scan for port/domain conflicts and dead upstreams'
+    def doctor
+      Commands::Doctor.new.call
+    end
+
+    desc 'reload', 'Validate and reload the global Caddy config'
+    def reload
+      Commands::Reload.new.call
+    end
+
+    desc 'ensure', 'One-shot: copy project Caddyfile into global config and exit (for scripts/CI)'
+    option :config, type: :string, required: true,  aliases: '-c', desc: 'Path to project Caddyfile'
+    option :site,   type: :string, required: true,  aliases: '-s', desc: 'Site name (used as fragment filename)'
+    def ensure
+      Commands::Ensure.new(config_path: options[:config], site: options[:site]).call
+    end
+
+    desc 'run', 'Register Caddyfile; block and unregister on shutdown (for Procfile.dev)'
+    option :config, type: :string, required: true,  aliases: '-c', desc: 'Path to project Caddyfile'
+    option :site,   type: :string, required: true,  aliases: '-s', desc: 'Site name (used as fragment filename)'
+    def caddy_run
+      Commands::Run.new(config_path: options[:config], site: options[:site]).call
+    end
+    map 'run' => :caddy_run
+
+    desc 'logs', 'Tail the Caddy log files for a site'
+    option :site,   type: :string,  required: true, aliases: '-s', desc: 'Site name'
+    option :lines,  type: :numeric, default: 200,   aliases: '-n', desc: 'Number of lines (with --no-follow)'
+    option :follow, type: :boolean, default: true, desc: 'Follow log (tail -F). Use --no-follow to print and exit.'
+    def logs
+      Commands::Logs.new(site: options[:site], lines: options[:lines], follow: options[:follow]).call
+    end
+
+    desc 'audit', 'Print a full system + TLS + site snapshot'
+    option :site, type: :string,  aliases: '-s', desc: 'Limit to a single site'
+    option :fix,  type: :boolean, default: false, desc: 'After report, prompt to apply a fix for each failing check'
+    def audit
+      Commands::Audit.new(site: options[:site], fix: options[:fix]).call
+    end
+
+    desc 'version', 'Print ecaddy version'
+    def version
+      puts "ecaddy #{EasyCaddy::VERSION}"
+    end
+  end
+end