RailsCaddyDev

Automatically configures Caddy as a local reverse proxy for Rails development. When you start rails server, it registers routes via the Caddy admin API so that <domain>.localhost proxies to your locally running Rails server with HTTPS.

Prerequisites

• Caddy installed and running locally
• Ruby >= 3.1

Installation

Add it to your application's Gemfile:

gem 'rails_caddy_dev', group: :development

Then run:

bundle install

Setup

In your application's bin/rails file, replace this:

require "rails/commands"

with this:

require ENV.key?('RAILS_CADDY_DEV') ? "rails_caddy_dev/commands" : "rails/commands"

This will ensure your Caddy configuration is updated each time you start your Rails server in development.

Usage

Start your Rails server with the RAILS_CADDY_DEV environment variable set:

RAILS_CADDY_DEV=1 rails server

This will configure Caddy to proxy <dirname>.localhost (where <dirname> is the basename of your Rails root) to your Rails server, accessible over HTTPS. To use a different hostname, set RAILS_CADDY_DEV_DOMAIN:

RAILS_CADDY_DEV=1 RAILS_CADDY_DEV_DOMAIN=myapp rails server

Environment Variables

Variable	Description	Default
RAILS_CADDY_DEV	Enables Caddy configuration (must be set)	—
RAILS_CADDY_DEV_DOMAIN	Used to derive the .localhost hostname	Basename of the current working directory
PORT	Rails server port to proxy to	Auto-detected available port (falls back to 3000)
CADDY_HOST	Caddy admin API host	localhost
CADDY_PORT	Caddy admin API port	2019

Dynamic Port Allocation

If PORT is not set, the gem automatically detects an available TCP port and uses it. This means you can run multiple Rails servers without port conflicts — no manual configuration needed.

You can also use the standalone executable to find an available port yourself:

export PORT=$(bundle exec rails_caddy_dev port)

Subdomains

Subdomains are also supported due to a wildcard Caddy route that will be configured. For example, if the resolved domain is myapp, then api.myapp.localhost will also proxy to your Rails server.

Removing a Route

To remove the Caddy route for the current project, run:

bundle exec rails_caddy_dev delete

This deletes the route registered for RAILS_CADDY_DEV_DOMAIN (or the current directory's basename if unset).

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/joelmoss/rails_caddy_dev.

License

The gem is available as open source under the terms of the MIT License.