Rails Development Environment Configuration

Rails Development Environment Configuration#

Sure's development environment is started with a single command — bin/dev — which uses Foreman to run all required processes in parallel. Environment variables are loaded by dotenv-rails from .env.local (and related files) before Rails initializers run.

bin/dev and Foreman#

bin/dev is the canonical entry point for local development. It:

Auto-installs the foreman gem if not present, and runs rbenv rehash for rbenv users .
Sets a default PORT=3000 (overridable) .
Exports two debug-related variables — RUBY_DEBUG_OPEN=true and RUBY_DEBUG_LAZY=true — which allow the debug gem to accept remote connections only when a debugger call is hit .
Delegates to bundle exec foreman start -f Procfile.dev .

foreman is listed as a development-group gem in the Gemfile so it is always available in the bundle.

Procfile.dev — Managed Processes#

Procfile.dev defines three processes:

Label	Command
`web`	`bundle exec ${DEBUG:+rdbg -O -n -c --} bin/rails server`
`css`	`bundle exec bin/rails tailwindcss:watch`
`worker`	`bundle exec sidekiq`

The web entry uses a shell parameter expansion trick: when the DEBUG environment variable is set, rdbg (the Ruby debugger) is prepended to the Rails server command automatically .

Environment Variable Loading#

Gem: dotenv-rails#

dotenv-rails is loaded in the development and test groups . This gem automatically loads .env* files before Rails initializers run. There is also a conditional inclusion for production when BENCHMARKING_ENABLED is set .

dotenv-rails follows a standard file precedence order (highest priority first):

.env.local — personal overrides, not committed to git
.env.development.local
.env.test.local (in test env)
.env.development
.env

Variables already set in the shell environment take precedence over all .env files.

.env.local.example → .env.local#

The developer-facing template is .env.local.example. Copy it to .env.local before first run . It contains development defaults for:

SELF_HOSTED=true, ONBOARDING_STATE=open
PORT=3000
WebAuthn local defaults: WEBAUTHN_RP_ID=localhost, WEBAUTHN_ALLOWED_ORIGINS=http://localhost:3000
Placeholders for OPENAI_ACCESS_TOKEN, TWELVE_DATA_API_KEY, Langfuse, OIDC, etc.

.env.example — Self-Hosting Reference#

.env.example is not intended for local developer setup. Its header explicitly redirects developers to .env.local.example . It documents all variables supported for self-hosting, including database, Redis, SMTP, Active Storage backends, Active Record Encryption keys, and third-party integrations.

Key Environment Variables for Dev#

Variable	Default / Purpose
`PORT`	`3000` — set in `bin/dev`, overridable
`RUBY_DEBUG_OPEN`	`true` — enables remote debug connections
`RUBY_DEBUG_LAZY`	`true` — defers debugger load until `debugger` is called
`DEBUG`	If set, activates `rdbg` in the web process via `Procfile.dev`
`DB_HOST`	`localhost` (bare metal) or `db` (devcontainer)
`REDIS_URL`	`redis://localhost:6379/1`
`SELF_HOSTED`	`true` in dev — enables self-hosting feature paths
`SKYLIGHT_ENABLED`	Controls whether the `skylight` gem loads in dev vs. production

Setup Flow (First Run)#

Per the README:

Copy .env.local.example → .env.local and fill in any needed secrets.
Run bin/setup to install gems, build assets, and run db:prepare.
Run bin/dev to start all processes.

The app is then available at http://localhost:3000.

bin/dev — entry point script
Procfile.dev — process definitions
Gemfile — dotenv-rails and foreman gem declarations
.env.local.example — developer env template
.env.example — self-hosting env reference
Dev Container Setup — Docker-based alternative with environment vars pre-wired via docker-compose.yml