How to Design Configuration for Rails Applications

My presentation slides from Kaigi on Rails 2026.

https://kaigionrails.org/2026/talks/willnet/

Transcript

1. How to Design Con guration for Rails Applications Shinichi Maeshima(@willnet) Kaigi on Rails 2026 fi 2026/10/17
2. Shinichi Maeshima Willnet Inc. @netwillnet @willnet https://blog.willnet.in
3. Iʼm a Technical Advisor
4. Weʼre not hiring!
5. Iʼm available for advisory work about one day a week 週一日程度のお手伝い先を募集しています👀
6. I organize ginza.rb
7. We will hold ぎんざRuby会議02 on 2027/01/23(Sat) at mybest Inc
8. We're looking for companies willing to host ginza.rb meetups!
9. How to Design Con guration for Rails Applications fi 設定をどう設計するとアプリケーション開発に集中できるか、という話をします
10. Con guration • Rails favors “convention over con guration,” so it needs fewer settings than other frameworks̶but it still needs some • Choosing something other than the default requires explicit con guration • Every framework needs application-speci c con guration fi fi fi fi fi Railsと言えば設定より規約、とはいえ全く設定しなくていいわけではない
11. Running a Web Application Requires Many Kinds of Con guration • Infrastructure con guration • Middleware con guration • Rails and gem con guration • Application-speci c con guration fi fi fi fi fi fi Webアプリケーションを構成する設定はいろんなところにある
12. Running a Web Application Requires Many Kinds of Con guration • Infrastructure con guration • Middleware con guration • Rails and gem con guration • Application-speci c con guration fi fi fi fi fi fi 今日は主にアプリケーション固有の設定の話をします
13. “Con guration” may mean di erent things to di erent people. ff fi ff 「設定」という言葉から連想されるものは人によって違いそう
14. What “Con guration” Means in This Talk • “Values that control application behavior and can be changed without changing the logic” fi この発表では設定を「アプリケーションの振る舞いを、ロジックを変えずに 変更するもの」という定義で話します
15. Example: Environment Variables
16. Example: Credentials
17. Example: YAML
18. Example: Database
19. fi fi Example: con g, con g.x
20. Example: Constants
21. Example: Class Variables and Class Instance Variables
22. Example: Methods
23. • con g • settingslogic • garo • dotenv • and more fi fi Example: Gems
24. So Many Options • Environment variables • Credentials • YAML • Database • con g, con g.x • Constants • Class variables and class instance variables • Methods fi fi • Gems
25. How Do We Choose? どれを選んだらええんや
26. Start by Classifying Con guration fi どれを選ぶかを話す前に、設定の性質を分類するところから始めましょう
27. Classi cation 1: Con guration Has a Flow • Con guration does not always live in just one place • Con guration values ows from its source, through intermediate layers, to the interface used by application code. fi fl fi fi fi 設定には“流れ”があり、起点・中継点・終点と値を受け渡して利用します
28. Source Example: Using dotenv • Write the following in a .env le • The .env le is the source fi fi 設定値が直接定義されているところが起点
29. Intermediate layer Example: Using dotenv • Values in .env become available as environment variables • Assign an environment variable to con g.x • The environment variable is the intermediate layer fi 起点に書かれた設定を、アプリケーションから利用可能な形に変換したものが 中継点
30. Interface Example: Using dotenv • The con g.x used by application code is the interface fi 設定値を実際に使うところが終点
31. These Roles Can Overlap • For example, assigning a value directly to a constant makes it serve as the source, intermediate layer, and interface 例えば定数などに直接値をアサインすればそれは起点・中継点・終点を全部兼 ねていると言える
32. But Should They? • Direct assignment is ne for local use, such as naming magic numbers • For application-wide settings, a dedicated place o ers: • Discoverability - Easy to nd and review • Consistency - Easier to keep settings organized and consistent • Environment Management - Easier to manage environment-speci c values fi ff fi fi 局所的な値であれば定数などに直接値を入れてもいいけど、基本的には分けて 管理した方が便利なことが多い
33. Classi cation 2: Secrets vs. Non-Secrets • Secrets (Example: a payment serviceʼs API secret key) • Must be stored securely, for example with encryption • Non-secrets(Examples: public external API URLs, database timeouts in seconds) • Can be managed in plain text • Whether a value needs to be secret depends on the environment (Example: database passwords) • Must be kept secret in production, but can often be stored in plain text in development fi 秘密の値は安全な形式で保存する必要があり、秘密の値かどうかは環境によっ て変わりうる
34. Classi cation 3: Who Changes It, and When? • Developers change it as part of a deployment • Developers or non-developers change it at any time • Example: feature ags • Requires external storage, such as a database • (This talk will not cover con guration management using external storage in depth) fi fl fi 任意のタイミングで変更したい設定値は、外部ストレージで扱う
35. Principles for Designing Con guration fi 設定を設計するときの方針
36. Principles for Designing Con guration • Consolidate • Make it easy to verify fi 「まとめる」と「確認しやすい形にする」
37. Consolidate 「まとめる」から話していきます
38. What Does “Consolidate” Mean? • Fewer places and mechanisms to manage make con guration easier to maintain fi 設定に関するものの数をなるべく減らした方が管理しやすいですよね
39. Sources, Intermediaries, and Con guration interfaces • Consolidate each stage • Sources and intermediaries often need to be considered together (for example, dotenv uses .env as the source and environment variables as the intermediate layer) • Consider con guration interfaces separately fi fi 起点・中継点・終点それぞれについてまとめていく(ただし起点と中継点はセ ットになっていることが多いので一緒に考える)
40. Consolidate Sources and Intermediaries 起点と中継点についてどうまとめるかを話します
41. Consolidate Sources and Intermediaries • Secrets and non-secrets have di erent requirements, so putting everything in one place is not realistic • Consider the following categories • Secrets(Production, Development) • Non-secrets ff まとめるなら全部一つにしたらいいじゃん、とはいかないのが面倒なところ。 要件によって最適な方法が違うのであった
42. Recommended Sources and Intermediaries for Production Secrets • Con guration management services provided by your PaaS or IaaS are often useful (for example, Secrets Manager) • Fine-grained access control with IAM • Easy to pass values through environment variables when using ECS • Credentials is an option for small teams that do not need advanced features, or environments without a con guration management service (for example, a VPS) fi fi 本番環境用の秘密の値はお使いのクラウドサービスが提供しているやつが多機 能なのでオススメ
43. Recommended Sources for Development Secrets • Ideally, avoid handling secrets in development altogether (For example, use a local storage instead of accessing S3 directly) • In that case, use a tool such as 1Password to share secrets with the team through environment variables • For example, you can access .env through 1Password (note: this does not work through Docker)) • Another option is to use the 1Password CLI with direnv • export API̲KEY=$(op read op://YourVault/Payment/API̲KEY) 開発環境で秘密の値を扱わなければいけないときは1Passwordなどのパスワ ードマネージャを使いましょう
44. Tools That Abstract Sources • Sometimes, you want to access di erent sources in production and development in the same way • Tools such as fnox and SecretSpec can help • They abstract sources such as 1Password and Secrets Manager, providing a consistent interface across environments ff 起点を抽象化するためのツールとしてfnoxやSecretSpecなどがあります
45. fnox Example
46. fnox Example どの環境でも同じように起動すれば良い、というのは認知負荷が下がって良い んじゃないでしょうか
47. Multiple Sources, One Intermediate layer • Rails 8.2 introduces Rails.app.creds • It provides transparent access to environment variables, .env les (in development), and Credentials • Lookup order: environment variables → .env les → Credentials fi fi Rails 8.2から使えるRails.app.credsで中継点をまとめることができる
48. Recommended Sources and Intermediaries for Non-Secrets • YAML les and con g̲for • Easy to de ne environment-speci c values and shared values • Supports more data types than environment variables fi fi fi fi fi 秘密ではない値やYAMLとcon g̲forがオススメ
49. fi fi fi con g̲for Example: Environment-Speci c Con guration
50. fi con g̲for Example: Deep Merge
51. Deep Merge Has Been Available Since Rails 6.1
52. Many Gems Have O ered Con guration Management, but con g̲for Now Covers the Basics fi ff fi fi 歴史的経緯でgemが使われていたものの、今となってはcon g̲forで基本的 なニーズは満たせる
53. Consolidate Con guration interfaces fi 終点についてどうまとめるかを話します
54. Consolidate Con guration interfaces • An con guration interface is how application code accesses con guration values • Direct access to environment variables, such as ENV.fetch('FOO') , is common, but I do not recommend it • I do not want to think about where con guration is stored! • A uni ed interface makes con guration easier to use • It also makes it easier to see which settings are available fi fi fi fi fi fi 終点では、起点と中継点について意識しないで統一的に扱いたい！
55. Recommended Con guration interface • For small applications, con g.x is convenient • Access both secrets and non-secrets through con g.x fi fi fi fi 小さいアプリケーションならcon g.xにまとめても良い
56. Recommended Con guration interface • For larger applications, create dedicated con guration classes • This makes con guration easier to verify fi fi fi 大きいアプリケーションなら専用のクラスを作ると確認しやすくできて良い
57. fi Recommended Con guration interface
58. Recommended Con guration interface • For larger applications, create dedicated con guration classes • This makes con guration easier to verify fi fi fi 専用のクラスを作ると確認しやすくできて良い
59. Principles for Designing Con guration (Revisited) • Consolidate • Make it easy to verify fi 設定を設計するときの方針の復習。「まとめる」と「確認しやすい形にする」
60. Make It Easy to Verify 確認しやすい形にする
61. What Does “Make It Easy to Verify” Mean? • It is hard to tell whether con gured values are correct • Especially in production • Con guration mistakes can cause outages, so we want to catch as many as possible • Catch as many con guration errors as possible, and make them harder to introduce fi fi fi 設定値が意図した値になっているのかを確認するのはとても難しい。意図して いない値が入らないようにしたり、意図していない値になったときにすぐ気づ けるようにしたい
62. Fail Immediately When a Required Value Is Missing 必要な設定値がなかったら即エラーになると不具合にすぐ気付けるので良い
63. Check Con guration at Startup to Avoid A ecting Users • Errors surface as deployment failures rather than errors seen by users ff fi Rails起動時にエラーにできるとユーザに影響を与えずに済む
64. Checking Whether Values Actually Work Is Harder • For example, you can check whether Stripe credentials are valid like this • But a temporary network error would cause the deployment to fail • This is an option if you can accept the trade-o , but that seems unlikely in most cases ff 設定が有効かどうかをチェックするのは難しい
65. Validation Can Be a Useful バリデーションである程度の確認はできる
66. Con guration Values Are Not Always Used As Is • For example • Converting types: use̲ssl = ENV.fetch('USE̲SSL') == 'true' • Combining values: url = "#{scheme}://#{host}:#{port}" • Tests for this kind of con guration processing are often skipped fi fi 設定値は型変換をしたり、他の設定と組み合わせたりなど変換をして使うこと があるけどそこのテストは省略されがち
67. Example: Transforming values only in production 本番環境しか通らないところで設定値を変換していると、変更するのが怖いで すよね
68. Classes Make Testing Easier クラスならテストしやすい
69. Test Example
70. Weʼve now covered all the principles 一通り話しました
71. For Those Who Want a Ready-Made Approach 既製品でいい感じにしたい人向けの方法
73. AnywayCon g • Provides features like the ones discussed today • Automatically brings sources and intermediaries together in a con guration class • Lookup order: environment variables → Credentials → YAML • Checks for required values and supports validation • Type conversion • If the ideas make sense but you are unsure where to start, give it a try fi fi 「まとめる」と「確認しやすい形にする」をやりやすくする機能が揃っている ので結局どうしたらいいかわからない人は試してみて
74. Summary • We classi ed the con guration that makes up a web application • We used those categories to explore how to design con guration that avoids accumulating technical debt • The core principles: consolidate and make it easy to verify • We covered several recommendations, but no single best practice ts every environment̶these principles matter more fi fi fi fi 設定に関する銀の弾丸はないので「まとめる」「確認しやすい形にする」で設 計してみて下さい
75. Closing Thought • Con guration is part of the application, too. Give it the same care as the rest of your code and keep it readable fi 設定もアプリケーションコードの一部なので、同じように可読性を高めていき たいですね
76. But What If That's Hard? • What if you nd it di cult to put this into practice? ffi fi そうは言っても実際にやるのは難しいんですよ、という人はどうしたらいい？
77. Iʼm available for advisory work about one day a week 週一日程度のお手伝い先を募集しています👀
78. Let me know what you think!