chamber 1.0.3 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +288 -173
- data/bin/chamber +2 -288
- data/lib/chamber.rb +19 -67
- data/lib/chamber/binary/heroku.rb +59 -0
- data/lib/chamber/binary/runner.rb +94 -0
- data/lib/chamber/binary/travis.rb +23 -0
- data/lib/chamber/commands/base.rb +33 -0
- data/lib/chamber/commands/comparable.rb +37 -0
- data/lib/chamber/commands/compare.rb +46 -0
- data/lib/chamber/commands/context_resolver.rb +72 -0
- data/lib/chamber/commands/files.rb +12 -0
- data/lib/chamber/commands/heroku.rb +30 -0
- data/lib/chamber/commands/heroku/clear.rb +25 -0
- data/lib/chamber/commands/heroku/compare.rb +31 -0
- data/lib/chamber/commands/heroku/pull.rb +30 -0
- data/lib/chamber/commands/heroku/push.rb +25 -0
- data/lib/chamber/commands/initialize.rb +73 -0
- data/lib/chamber/commands/securable.rb +48 -0
- data/lib/chamber/commands/secure.rb +16 -0
- data/lib/chamber/commands/show.rb +23 -0
- data/lib/chamber/commands/travis.rb +14 -0
- data/lib/chamber/commands/travis/secure.rb +35 -0
- data/lib/chamber/configuration.rb +34 -0
- data/lib/chamber/environmentable.rb +23 -0
- data/lib/chamber/errors/undecryptable_value_error.rb +6 -0
- data/lib/chamber/file.rb +17 -5
- data/lib/chamber/file_set.rb +18 -12
- data/lib/chamber/filters/boolean_conversion_filter.rb +41 -0
- data/lib/chamber/filters/decryption_filter.rb +69 -0
- data/lib/chamber/filters/encryption_filter.rb +57 -0
- data/lib/chamber/filters/environment_filter.rb +75 -0
- data/lib/chamber/filters/namespace_filter.rb +37 -0
- data/lib/chamber/filters/secure_filter.rb +39 -0
- data/lib/chamber/instance.rb +40 -0
- data/lib/chamber/namespace_set.rb +55 -16
- data/lib/chamber/rails/railtie.rb +1 -1
- data/lib/chamber/settings.rb +103 -42
- data/lib/chamber/system_environment.rb +3 -93
- data/lib/chamber/version.rb +2 -2
- data/spec/fixtures/settings.yml +27 -0
- data/spec/lib/chamber/commands/context_resolver_spec.rb +106 -0
- data/spec/lib/chamber/commands/files_spec.rb +19 -0
- data/spec/lib/chamber/commands/heroku/clear_spec.rb +11 -0
- data/spec/lib/chamber/commands/heroku/compare_spec.rb +11 -0
- data/spec/lib/chamber/commands/heroku/pull_spec.rb +11 -0
- data/spec/lib/chamber/commands/heroku/push_spec.rb +11 -0
- data/spec/lib/chamber/commands/secure_spec.rb +29 -0
- data/spec/lib/chamber/commands/show_spec.rb +43 -0
- data/spec/lib/chamber/file_set_spec.rb +1 -1
- data/spec/lib/chamber/file_spec.rb +32 -9
- data/spec/lib/chamber/filters/boolean_conversion_filter_spec.rb +44 -0
- data/spec/lib/chamber/filters/decryption_filter_spec.rb +55 -0
- data/spec/lib/chamber/filters/encryption_filter_spec.rb +48 -0
- data/spec/lib/chamber/filters/environment_filter_spec.rb +35 -0
- data/spec/lib/chamber/filters/namespace_filter_spec.rb +73 -0
- data/spec/lib/chamber/filters/secure_filter_spec.rb +36 -0
- data/spec/lib/chamber/namespace_set_spec.rb +61 -18
- data/spec/lib/chamber/settings_spec.rb +99 -23
- data/spec/lib/chamber/system_environment_spec.rb +1 -71
- data/spec/lib/chamber_spec.rb +40 -26
- data/spec/rails-2-test/config.ru +0 -0
- data/spec/rails-2-test/config/application.rb +5 -0
- data/spec/rails-2-test/script/console +0 -0
- data/spec/rails-3-test/config.ru +0 -0
- data/spec/rails-3-test/config/application.rb +5 -0
- data/spec/rails-3-test/script/rails +0 -0
- data/spec/rails-4-test/bin/rails +0 -0
- data/spec/rails-4-test/config.ru +0 -0
- data/spec/rails-4-test/config/application.rb +5 -0
- data/spec/spec_key +27 -0
- data/spec/spec_key.pub +9 -0
- metadata +85 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: e5d109673b130deb762adb5bb07bdce3f93c3848
|
4
|
+
data.tar.gz: 7bbce53ee5448ac94a876ca314461ce216ad881c
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 8e1cdda8675bdb504657159f52209dd24fa5bd9accecd2cfddbb68a1df08011684b1152eeb975362a0b3452d8a9183655e886f5b3078659a934349229ee5a4a3
|
7
|
+
data.tar.gz: d540cd77c3e966b9f355f1e910b74317254f4d8b6ea32e47db39fc92f567b3e6d71d029daebd059cbe371fcc5d63f7e3e106090dec9bb8f6944245cc3626dd0d
|
data/README.md
CHANGED
@@ -1,8 +1,34 @@
|
|
1
1
|
# Chamber [](https://travis-ci.org/m5rk/chamber) [](https://codeclimate.com/github/m5rk/chamber)
|
2
2
|
|
3
|
-
Chamber
|
4
|
-
|
5
|
-
|
3
|
+
Chamber is the auto-encrypting, extremely organizable, Heroku-loving, CLI-having,
|
4
|
+
non-extra-repo-needing, non-Rails-specific-ing, CI-serving configuration
|
5
|
+
management library.
|
6
|
+
|
7
|
+
## But What About Those Other Configuration Management Gems?
|
8
|
+
|
9
|
+
We reviewed [some other gems](#alternatives), and while each fit a specific need
|
10
|
+
and each did some things well, none of them met all of the criteria that we felt
|
11
|
+
we (and assumed others) needed.
|
12
|
+
|
13
|
+
<img src="https://akiajm7spx4gtbhaxe3qcomhaystacksoftwarearp.s3.amazonaws.com/photos/readmes/ten-commandments.png" align="right" />
|
14
|
+
|
15
|
+
**Our Ten Commandments of Configuration Management**
|
16
|
+
|
17
|
+
1. Thou shalt be configurable, but use conventions so that configuration isn't
|
18
|
+
necessary
|
19
|
+
1. Thou shalt seemlessly work with Heroku or other deployment platforms, where custom
|
20
|
+
settings must be stored in environment variables
|
21
|
+
1. Thou shalt seemlessly work with Travis CI and other cloud CI platforms
|
22
|
+
1. Thou shalt not force users to use arcane
|
23
|
+
really_long_variable_names_just_to_keep_their_settings_organized
|
24
|
+
1. Thou shalt not require users keep a separate repo or cloud share sync just to
|
25
|
+
keep their secure settings updated
|
26
|
+
1. Thou shalt not be bound to a single framework like Rails (it should be usable in
|
27
|
+
plain Ruby projects)
|
28
|
+
1. Thou shalt have an easy-to-use CLI for scripting
|
29
|
+
1. Thou shalt easily integrate with Capistrano for deployments
|
30
|
+
1. Thou shalt be well documented with full test coverage
|
31
|
+
1. Thou shalt not have to worry about accidentally committing secure settings
|
6
32
|
|
7
33
|
## Installation
|
8
34
|
|
@@ -24,6 +50,24 @@ Or install it yourself as:
|
|
24
50
|
$ gem install chamber
|
25
51
|
```
|
26
52
|
|
53
|
+
Once the gem is installed, you'll want to add it to your project. To do this,
|
54
|
+
type:
|
55
|
+
|
56
|
+
```sh
|
57
|
+
chamber init
|
58
|
+
```
|
59
|
+
|
60
|
+
This creates a public/private keypair for you to use with your project. The
|
61
|
+
private key will be called `.chamber.pem`. The public key will be called
|
62
|
+
`.chamber.pem.pub`.
|
63
|
+
|
64
|
+
`.chamber.pem` will be added to your gitignore file so that it is not
|
65
|
+
accidentally checked in. *Keep this file safe* since anyone who has it will be
|
66
|
+
able to decrypt any settings that Chamber encrypts for you.
|
67
|
+
|
68
|
+
Lastly, it will create a sample `settings.yml` file for you which you should
|
69
|
+
modify as needed.
|
70
|
+
|
27
71
|
## Basic Usage
|
28
72
|
|
29
73
|
### Convention Over Configuration
|
@@ -31,7 +75,6 @@ $ gem install chamber
|
|
31
75
|
By default Chamber only needs a base path to look for settings files. From
|
32
76
|
that path it will search for:
|
33
77
|
|
34
|
-
* The file `<basepath>/credentials.yml`
|
35
78
|
* The file `<basepath>/settings.yml`
|
36
79
|
* A set of files ending in `.yml` in the `<basepath>/settings` directory
|
37
80
|
|
@@ -43,12 +86,8 @@ Chamber.load basepath: '/path/to/my/application'
|
|
43
86
|
|
44
87
|
### In Rails
|
45
88
|
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
```ruby
|
50
|
-
Chamber.load basepath: Rails.root.join('config')
|
51
|
-
```
|
89
|
+
You do not have to do anything. Chamber will auto-configure itself to point to
|
90
|
+
the `config` directory.
|
52
91
|
|
53
92
|
### Accessing Settings
|
54
93
|
|
@@ -61,7 +100,7 @@ Given a `settings.yml` file containing:
|
|
61
100
|
|
62
101
|
```yaml
|
63
102
|
smtp:
|
64
|
-
server:
|
103
|
+
server: "example.com"
|
65
104
|
username: "my_user"
|
66
105
|
password: "my_pass"
|
67
106
|
```
|
@@ -80,15 +119,60 @@ Chamber.env.smtp.server
|
|
80
119
|
# => example.com
|
81
120
|
```
|
82
121
|
|
83
|
-
###
|
122
|
+
### Securing Your Settings
|
123
|
+
|
124
|
+
Certain settings you will want to keep from prying eyes. Unlike other
|
125
|
+
configuration management libraries, Chamber doesn't require you to keep those
|
126
|
+
files separate. You can check *everything* into your repo.
|
127
|
+
|
128
|
+
Why is keeping your secure files separate a pain? Because you must keep those
|
129
|
+
files in sync between all of your team members who are deploying the app.
|
130
|
+
Either you have to use a separate private repo, or you have to use something
|
131
|
+
like a Dropbox share. In either case, you'd then symlink the files from their
|
132
|
+
locations into your application. What. A. Pain.
|
133
|
+
|
134
|
+
Chamber uses public/private encryption keys to seemlessly store any of your
|
135
|
+
configuration values as encrypted text. The only file that needs to be synced
|
136
|
+
*once* between developers is the private key. And even that file would only be
|
137
|
+
needed by the users deploying the application. If you're deploying via CI,
|
138
|
+
Github, etc, then technically no developer needs it.
|
139
|
+
|
140
|
+
#### Working With Secure Configuration Settings
|
141
|
+
|
142
|
+
After running `chamber init` as described above, the hard work is done. From
|
143
|
+
here on out, Chamber makes working with secure settings almost an afterthought.
|
144
|
+
|
145
|
+
When you create your configuration YAML file (or add a new setting to an
|
146
|
+
existing one), you can format your secure keys like so:
|
147
|
+
|
148
|
+
```yaml
|
149
|
+
# settings.yml
|
150
|
+
|
151
|
+
_secure_my_secure_key_name: 'my secure value'
|
152
|
+
```
|
153
|
+
|
154
|
+
When Chamber sees this convention (`_secure_` followed by the key name), it will
|
155
|
+
automatically look to either encrypt or decrypt the value using the
|
156
|
+
public/private keys you generated above into something like:
|
157
|
+
|
158
|
+
```yaml
|
159
|
+
# settings.yml
|
160
|
+
|
161
|
+
_secure_my_secure_key_name: 8239f293r9283r9823r92hf9823hf9uehfksdhviwuehf923uhrehf9238
|
162
|
+
```
|
163
|
+
|
164
|
+
However you would still be able to access the value like so (assuming you had
|
165
|
+
the private key in the application's root):
|
84
166
|
|
85
|
-
|
86
|
-
|
167
|
+
```ruby
|
168
|
+
Chamber.env.my_secure_key_name
|
169
|
+
# => 'my secure value'
|
170
|
+
```
|
87
171
|
|
88
|
-
### Existing Environment Variables
|
172
|
+
### Using Existing Environment Variables
|
89
173
|
|
90
|
-
If deploying to a system which has all of your environment variables already
|
91
|
-
|
174
|
+
If deploying to a system which has all of your environment variables already set
|
175
|
+
(eg Heroku), you're not going to use all of the values stored in the YAML files.
|
92
176
|
Instead, you're going to want to pull certain values from environment variables.
|
93
177
|
|
94
178
|
**Example:**
|
@@ -97,7 +181,7 @@ Given a `settings.yml` file containing:
|
|
97
181
|
|
98
182
|
```yaml
|
99
183
|
smtp:
|
100
|
-
server:
|
184
|
+
server: "example.com"
|
101
185
|
username: "my_user"
|
102
186
|
password: "my_pass"
|
103
187
|
```
|
@@ -108,7 +192,7 @@ If an environment variable is already set like so:
|
|
108
192
|
export SMTP_SERVER="myotherserverisapentium.com"
|
109
193
|
```
|
110
194
|
|
111
|
-
Then when you ask Chamber to give you the SMTP server:
|
195
|
+
Then, when you ask Chamber to give you the SMTP server:
|
112
196
|
|
113
197
|
```ruby
|
114
198
|
Chamber[:smtp][:server]
|
@@ -121,14 +205,15 @@ variable.
|
|
121
205
|
## Deploying to Heroku
|
122
206
|
|
123
207
|
If you're deploying to Heroku, they won't let you upload custom config files. If
|
124
|
-
you do not have your config files all stored in your repo
|
125
|
-
|
126
|
-
|
208
|
+
you do not have your config files all stored in your repo, or some of your
|
209
|
+
settings are encrypted, it becomes more difficult to gain access to that
|
210
|
+
information on Heroku.
|
127
211
|
|
128
212
|
To solve this problem, Heroku allows you to set environment variables in your
|
129
213
|
application. Unfortunately this has the nasty side effect of being a pain to
|
130
214
|
deal with. For one, you have to deal with environment variables with unweildy
|
131
|
-
names. For another, it makes the
|
215
|
+
names (eg `MY_THIRD_PARTY_SERVICE_DEV_API_KEY`). For another, it makes the
|
216
|
+
organization of those variables difficult.
|
132
217
|
|
133
218
|
Fortunately, Chamber allows you to organize your environment variables in
|
134
219
|
separate files and access them easily using hash or object notation, however at
|
@@ -137,18 +222,14 @@ configuration settings up to Heroku as environment variables.
|
|
137
222
|
|
138
223
|
When Chamber accesses those same hash/object notated config values, it will
|
139
224
|
first look to see if an associated environment variable exists. If it does, it
|
140
|
-
will use that in place of any values inside of the config files
|
225
|
+
will use that in place of any values inside of the config files as [described
|
226
|
+
above](#using-existing-environment-variables).
|
141
227
|
|
142
|
-
|
228
|
+
To update Heroku with all the proper environment variables so that your app
|
229
|
+
works as expected, run the following from the root of your app:
|
143
230
|
|
144
231
|
```sh
|
145
|
-
|
146
|
-
|
147
|
-
chamber heroku push --preset=rails
|
148
|
-
|
149
|
-
# In the root folder of another type of application:
|
150
|
-
|
151
|
-
chamber heroku push --basepath=./
|
232
|
+
chamber heroku push
|
152
233
|
```
|
153
234
|
|
154
235
|
And all of your settings will be converted to environment variable versions
|
@@ -168,7 +249,7 @@ information.
|
|
168
249
|
To execute this, simply run:
|
169
250
|
|
170
251
|
```sh
|
171
|
-
chamber travis secure
|
252
|
+
chamber travis secure
|
172
253
|
```
|
173
254
|
|
174
255
|
This will add `secure` entries into your `.travis.yml` file. Each one will
|
@@ -202,15 +283,6 @@ associated namespaced files. Finally it will load all \*.yml files in the
|
|
202
283
|
`chamber` directory *except* `credentials.yml` because it has previously been
|
203
284
|
loaded.
|
204
285
|
|
205
|
-
### Object-Based Environment Variable Access
|
206
|
-
|
207
|
-
If you aren't a fan of the hash-based access, you can also access them
|
208
|
-
using methods:
|
209
|
-
|
210
|
-
```ruby
|
211
|
-
Chamber.env.smtp.server
|
212
|
-
```
|
213
|
-
|
214
286
|
### Predicate Methods
|
215
287
|
|
216
288
|
When using object notation, all settings have `?` and `_` predicate methods
|
@@ -256,28 +328,25 @@ Notice the difference:
|
|
256
328
|
|
257
329
|
One of the nice things about Chamber is that it runs each settings file through
|
258
330
|
ERB before it tries to parse it as YAML. The main benefit of this is that you
|
259
|
-
can use settings from previous files in ERB for later files.
|
260
|
-
used if you follow our convention of putting all of your sensitive information
|
261
|
-
in your `credentials.yml` file.
|
331
|
+
can use settings from previous files in ERB for later files.
|
262
332
|
|
263
333
|
**Example:**
|
264
334
|
|
265
335
|
```yaml
|
266
|
-
#
|
336
|
+
# settings.yml
|
267
337
|
|
268
338
|
production:
|
269
339
|
my_secret_key: 123456789
|
270
340
|
```
|
271
341
|
|
272
342
|
```erb
|
273
|
-
<%# settings.yml %>
|
343
|
+
<%# settings/some_service-production.yml %>
|
274
344
|
|
275
|
-
|
276
|
-
my_url: http://my_username:<%= Chamber[:my_secret_key] %>@my-url.com
|
345
|
+
my_service_url: http://my_username:<%= Chamber[:my_secret_key] %>@my-url.com
|
277
346
|
```
|
278
347
|
|
279
|
-
Because by default Chamber processes `
|
280
|
-
anything
|
348
|
+
Because by default Chamber processes `settings*.yml` settings files before
|
349
|
+
anything in the `settings` subdirectory, this works.
|
281
350
|
|
282
351
|
But it's all ERB so you can do as much crazy ERB stuff in your settings files as
|
283
352
|
you'd like:
|
@@ -313,9 +382,9 @@ under specific circumstances, you can use Chamber's namespaces.
|
|
313
382
|
**Example:**
|
314
383
|
|
315
384
|
```ruby
|
316
|
-
Chamber.load( :basepath
|
385
|
+
Chamber.load( :basepath => Rails.root.join('config'),
|
317
386
|
:namespaces => {
|
318
|
-
:environment =>
|
387
|
+
:environment => ::Rails.env } )
|
319
388
|
```
|
320
389
|
|
321
390
|
For this class, it will not only try and load the file `config/settings.yml`,
|
@@ -383,17 +452,50 @@ smtp:
|
|
383
452
|
````
|
384
453
|
|
385
454
|
The above will yield the same results, but allows you to keep the production
|
386
|
-
values in a separate file which can be secured separately.
|
455
|
+
values in a separate file which can be secured separately. Although I would
|
456
|
+
recommend keeping everything together and just [encrpyting your sensitive
|
457
|
+
info](#securing-your-settings)
|
458
|
+
|
459
|
+
If you would like to have items shared among namespaces, you can easily use
|
460
|
+
YAML's built-in merge functionality to do that for you:
|
461
|
+
|
462
|
+
```yaml
|
463
|
+
# settings.yml
|
464
|
+
|
465
|
+
default: &default
|
466
|
+
smtp:
|
467
|
+
headers:
|
468
|
+
X-MYAPP-NAME: My Application Name
|
469
|
+
X-MYAPP-STUFF: Other Stuff
|
470
|
+
|
471
|
+
development:
|
472
|
+
<<: *default
|
473
|
+
smtp:
|
474
|
+
username: my_development_username
|
475
|
+
password: my_development_password`
|
476
|
+
|
477
|
+
test:
|
478
|
+
<<: *default
|
479
|
+
smtp:
|
480
|
+
username: my_test_username
|
481
|
+
password: my_test_password`
|
482
|
+
|
483
|
+
staging:
|
484
|
+
<<: *default
|
485
|
+
smtp:
|
486
|
+
username: my_staging_username
|
487
|
+
password: my_staging_password`
|
488
|
+
```
|
387
489
|
|
388
490
|
#### Multiple Namespaces
|
389
491
|
|
390
492
|
Multiple namespaces can be defined by passing multiple items to the loader:
|
391
493
|
|
392
494
|
```ruby
|
393
|
-
Chamber.load( :basepath => '
|
495
|
+
Chamber.load( :basepath => Rails.root.join('config'),
|
394
496
|
:namespaces => {
|
395
|
-
:environment =>
|
396
|
-
:hostname =>
|
497
|
+
:environment => ::Rails.env,
|
498
|
+
:hostname => ENV['HOST'] } )
|
397
499
|
```
|
398
500
|
|
399
501
|
When accessed within the `test` environment on a system named `tumbleweed`, it
|
@@ -468,22 +570,63 @@ Each of the commands described below takes a few common options.
|
|
468
570
|
|
469
571
|
**Example:** `--preset=rails`
|
470
572
|
|
471
|
-
* `--
|
472
|
-
|
573
|
+
* `--rootpath` (or `-r`): Allows you to quickly set the rootpath of the
|
574
|
+
application. By default this is the directory that the `chamber` executable is
|
575
|
+
run from.
|
473
576
|
|
474
|
-
**Example:** `--
|
577
|
+
**Example:** `--rootpath=/path/to/my/application`
|
475
578
|
|
476
579
|
* `--basepath` (or `-b`): Sets the base path that Chamber will use to look for
|
477
580
|
its [common settings files](#convention-over-configuration).
|
478
581
|
|
479
582
|
**Example:** `--basepath=/path/to/my/application`
|
480
583
|
|
584
|
+
* `--files` (or `-f`): Allows you to specifically set the file patterns that
|
585
|
+
Chamber should look at in determining where to load settings information from.
|
586
|
+
|
587
|
+
**Example:** `--files=/path/to/my/application/secret.yml /path/to/my/application/settings/*.yml`
|
588
|
+
|
481
589
|
* `--namespaces` (or `-n`): The namespace values which will be considered for
|
482
590
|
loading settings files.
|
483
591
|
|
484
|
-
**Example:** `--namespaces=development`
|
592
|
+
**Example:** `--namespaces=development tumbleweed`
|
593
|
+
|
594
|
+
* `--encryption-key`: The path to the key which will be used for encryption.
|
595
|
+
This is optional unless you need to secure any settings.
|
596
|
+
|
597
|
+
Additionally you may pass in the actual contents of the key for this option.
|
598
|
+
|
599
|
+
**Example:** `--keypair=/path/to/my/app/my_project_rsa.pub`
|
600
|
+
|
601
|
+
* `--decryption-key`: The path to the key which will be used for decryption.
|
602
|
+
This is optional unless you need to decrypt any settings.
|
603
|
+
|
604
|
+
Additionally you may pass in the actual contents of the key for this option.
|
605
|
+
|
606
|
+
**Example:** `--keypair=/path/to/my/app/my_project_rsa`
|
607
|
+
|
608
|
+
_**Note:** `--basepath` and `--files` are mutually exclusive. `--files` will
|
609
|
+
always take precedence._
|
610
|
+
|
611
|
+
#### Somewhat Common Options
|
485
612
|
|
486
|
-
_**Note:**
|
613
|
+
_**Note:** Only select commands support the following options. Use `chamber help
|
614
|
+
SUBCOMMAND` to verify if a particular command does._
|
615
|
+
|
616
|
+
* `--dry-run` (or `-d`): The command will not actually execute, but will show
|
617
|
+
you a summary of what *would* have happened.
|
618
|
+
|
619
|
+
**Example:** `--dry-run`
|
620
|
+
|
621
|
+
* `--only-secured` (or `-o`): This is the default. Because most systems have no
|
622
|
+
issues reading from the config files you have stored in your repo, there is no
|
623
|
+
need to process *all* of your settings. So by default, Chamber will only
|
624
|
+
convert, push, etc those settings which have been gitignored or those which
|
625
|
+
have been encrpyted.
|
626
|
+
|
627
|
+
To process everything, use the `--skip-secure-only` flag.
|
628
|
+
|
629
|
+
**Example:** `--secure-only`, `--skip-secure-only`
|
487
630
|
|
488
631
|
#### Settings
|
489
632
|
|
@@ -499,7 +642,7 @@ about for a given context. It will be output as a hash of hashes by default.
|
|
499
642
|
|
500
643
|
**Example:** `--as-env`
|
501
644
|
|
502
|
-
**Example:** `chamber
|
645
|
+
**Example:** `chamber show --as-env`
|
503
646
|
|
504
647
|
###### Files
|
505
648
|
|
@@ -510,7 +653,19 @@ Additionally, the order is significant. Chamber will load settings from the
|
|
510
653
|
top down so any duplicate items in subsequent entries will override items from
|
511
654
|
previous ones.
|
512
655
|
|
513
|
-
**Example:** `chamber
|
656
|
+
**Example:** `chamber files`
|
657
|
+
|
658
|
+
###### Secure
|
659
|
+
|
660
|
+
Will verify that any items which are marked as secure (eg `_secure_my_setting`)
|
661
|
+
have secure values. If it appears that one does not, the user will be prompted
|
662
|
+
as to whether or not they would like to encrpyt it.
|
663
|
+
|
664
|
+
This command differs from other tasks in that it will process all files that
|
665
|
+
match Chamber's conventions and not just those which match the passed in
|
666
|
+
namespaces.
|
667
|
+
|
668
|
+
**Example:** `chamber secure`
|
514
669
|
|
515
670
|
###### Compare
|
516
671
|
|
@@ -539,17 +694,25 @@ environments.
|
|
539
694
|
|
540
695
|
**Example:** `--second=staging`, `--second=staging my_host_name`
|
541
696
|
|
542
|
-
**Example:** `chamber
|
697
|
+
**Example:** `chamber compare --first=development --second=staging`
|
698
|
+
|
699
|
+
###### Init
|
700
|
+
|
701
|
+
Init can be used to initialize a new application/project with everything that
|
702
|
+
Chamber needs in order to run properly. This includes:
|
703
|
+
|
704
|
+
* Creating a public/private keypair
|
705
|
+
* Setting the proper permissions on the the newly created keypair
|
706
|
+
* Adding the private key to the gitignore file
|
707
|
+
* Creating a template `settings.yml` file
|
708
|
+
|
709
|
+
**Example:** `chamber init`
|
543
710
|
|
544
711
|
#### Heroku
|
545
712
|
|
546
713
|
As we described above, working with Heroku environment variables is tedious at
|
547
714
|
best. Chamber gives you a few ways to help with that.
|
548
715
|
|
549
|
-
_**Note:** I'll be using the `--preset` shorthand `-p` for brevity below but the
|
550
|
-
examples will work with any of the other options described
|
551
|
-
[above](#common-options)._
|
552
|
-
|
553
716
|
##### Heroku Common Options
|
554
717
|
|
555
718
|
* `--app` (or `-a`): Heroku application name for which you would like to affect
|
@@ -557,20 +720,6 @@ examples will work with any of the other options described
|
|
557
720
|
|
558
721
|
**Example:** `--app=my-heroku-app-name`
|
559
722
|
|
560
|
-
* `--dry-run` (or `-d`): The command will not actually execute, but will show
|
561
|
-
you a summary of what *would* have happened.
|
562
|
-
|
563
|
-
**Example:** `--dry-run`
|
564
|
-
|
565
|
-
* `--only-ignored` (or `-o`): This is the default. Because Heroku has no issues
|
566
|
-
reading from the config files you have stored in your repo, there is no need
|
567
|
-
to set *all* of your settings as environment variables. So by default,
|
568
|
-
Chamber will only convert and push those settings which have been gitignored.
|
569
|
-
|
570
|
-
To push everything, use the `--no-only-ignored` flag.
|
571
|
-
|
572
|
-
**Example:** `--only-ignored`, `--no-only-ignored`
|
573
|
-
|
574
723
|
##### Heroku Commands
|
575
724
|
|
576
725
|
###### Push
|
@@ -579,10 +728,10 @@ As we described above, this command will take your current settings and push
|
|
579
728
|
them to Heroku as environment variables that Chamber will be able to
|
580
729
|
understand.
|
581
730
|
|
582
|
-
**Example:** `chamber heroku push
|
731
|
+
**Example:** `chamber heroku push --namespaces=production --app=my-heroku-app`
|
583
732
|
|
584
733
|
_**Note:** To see exactly how Chamber sees your settings as environment variables, see
|
585
|
-
the [chamber settings show](#
|
734
|
+
the [chamber settings show](#settings-commands) command above._
|
586
735
|
|
587
736
|
###### Pull
|
588
737
|
|
@@ -598,9 +747,9 @@ specify the following option:
|
|
598
747
|
_**Note:** Eventually this will be parsed into YAML that Chamber can load
|
599
748
|
straight away, but for now, it's basically just redirecting the output._
|
600
749
|
|
601
|
-
**Example:** `--into=/path/to/my/app/settings/heroku.
|
750
|
+
**Example:** `--into=/path/to/my/app/settings/heroku.config`
|
602
751
|
|
603
|
-
**Example:** `chamber heroku pull
|
752
|
+
**Example:** `chamber heroku pull --app=my-heroku-app --into=/path/to/my/app/heroku.config`
|
604
753
|
|
605
754
|
###### Diff
|
606
755
|
|
@@ -608,7 +757,7 @@ Will use git's diff function to display the difference between what Chamber
|
|
608
757
|
knows about locally and what Heroku currently has set. This is very handy for
|
609
758
|
knowing what changes may be made if `chamber heroku push` is executed.
|
610
759
|
|
611
|
-
**Example:** `chamber heroku diff
|
760
|
+
**Example:** `chamber heroku diff --namespaces=production --app=my-heroku-app`
|
612
761
|
|
613
762
|
###### Clear
|
614
763
|
|
@@ -616,34 +765,18 @@ Will remove any environment variables from Heroku that Chamber knows about.
|
|
616
765
|
This is useful for clearing out Chamber-related settings without touching
|
617
766
|
Heroku addon-specific items.
|
618
767
|
|
619
|
-
**Example:** `chamber heroku clear
|
768
|
+
**Example:** `chamber heroku clear --namespaces=production --app=my-heroku-app`
|
620
769
|
|
621
770
|
#### Travis CI
|
622
771
|
|
623
|
-
##### Travis Common Options
|
624
|
-
|
625
|
-
* `--dry-run` (or `-d`): The command will not actually execute, but will show
|
626
|
-
you a summary of what *would* have happened.
|
627
|
-
|
628
|
-
**Example:** `--dry-run`
|
629
|
-
|
630
|
-
* `--only-ignored` (or `-o`): This is the default. Because Travis has no issues
|
631
|
-
reading from the config files you have stored in your repo, there is no need
|
632
|
-
to set *all* of your settings as environment variables. So by default,
|
633
|
-
Chamber will only convert and push those settings which have been gitignored.
|
634
|
-
|
635
|
-
To push everything, use the `--no-only-ignored` flag.
|
636
|
-
|
637
|
-
**Example:** `--only-ignored`, `--no-only-ignored`
|
638
|
-
|
639
772
|
##### Travis Commands
|
640
773
|
|
641
774
|
###### Secure
|
642
775
|
|
643
|
-
Travis CI allows you to use the public key on your Travis repo to encrypt
|
644
|
-
|
645
|
-
|
646
|
-
|
776
|
+
Travis CI allows you to use the public key on your Travis repo to encrypt items
|
777
|
+
as environment variables which you would like for Travis to be able to have
|
778
|
+
access to, but which you wouldn't necessarily want to be in plain text inside of
|
779
|
+
your repo.
|
647
780
|
|
648
781
|
This command takes the settings that Chamber knows about, encrypts them, and
|
649
782
|
puts them inside of your .travis.yml at which point they can be safely
|
@@ -652,7 +785,7 @@ committed.
|
|
652
785
|
_**Warning:** This will delete *all* of your previous 'secure' entries under
|
653
786
|
'env.global' in your .travis.yml file._
|
654
787
|
|
655
|
-
**Example:** `chamber travis secure
|
788
|
+
**Example:** `chamber travis secure --namespaces=continuous_integration`
|
656
789
|
|
657
790
|
### Basic Boolean Conversion
|
658
791
|
|
@@ -674,12 +807,12 @@ if Chamber.env.my_feature.enabled?
|
|
674
807
|
end
|
675
808
|
```
|
676
809
|
|
677
|
-
|
678
|
-
far as Ruby is concerned, is `true
|
679
|
-
`
|
680
|
-
|
681
|
-
|
682
|
-
positives.
|
810
|
+
Now because environment variables are always strings, `false` becomes `'false'`.
|
811
|
+
And because, as far as Ruby is concerned, any `String` is `true`, `enabled?`
|
812
|
+
would return `true`. Now, you could completely omit the `enabled` key, however
|
813
|
+
this causes issues if you would like to audit your settings (say for each
|
814
|
+
environment) to make sure they are all the same. Some will have the `enabled`
|
815
|
+
setting and some will not, which will give you false positives.
|
683
816
|
|
684
817
|
You could work around it by doing this:
|
685
818
|
|
@@ -689,7 +822,7 @@ if Chamber.env.my_feature.enabled == 'true'
|
|
689
822
|
end
|
690
823
|
```
|
691
824
|
|
692
|
-
but that looks awful.
|
825
|
+
but that looks awful and isn't very idomatic.
|
693
826
|
|
694
827
|
To solve this problem, Chamber reviews all of your settings values and, if they
|
695
828
|
are any of the following exact strings (case insensitive):
|
@@ -714,7 +847,8 @@ accessing it. Don't worry, Chamber will take you 98% of the way there.
|
|
714
847
|
Just include it like so:
|
715
848
|
|
716
849
|
```ruby
|
717
|
-
class Settings
|
850
|
+
class Settings
|
851
|
+
extend Chamber
|
718
852
|
end
|
719
853
|
```
|
720
854
|
|
@@ -723,51 +857,11 @@ environment, you can simply use `Settings[:application_host]`.
|
|
723
857
|
|
724
858
|
## Best Practices
|
725
859
|
|
726
|
-
### Why Do We Need Chamber?
|
727
|
-
|
728
|
-
> Don't store sensitive information in git.
|
729
|
-
|
730
|
-
A better way to say it is that you should store sensitive information separate
|
731
|
-
from non-sensitive information. There's nothing inherently wrong with storing
|
732
|
-
sensitive information in git. You just wouldn't want to store it in a public
|
733
|
-
repository.
|
734
|
-
|
735
|
-
If it weren't for this concern, managing settings would be trivial, easily
|
736
|
-
solved use any number of approaches; e.g., [like using YAML and ERB in an
|
737
|
-
initializer](http://urgetopunt.com/rails/2009/09/12/yaml-config-with-erb.html).
|
738
|
-
|
739
860
|
### Organizing Your Settings
|
740
861
|
|
741
|
-
We recommend starting with a single `
|
742
|
-
|
743
|
-
|
744
|
-
|
745
|
-
### Keeping Private Settings Private
|
746
|
-
|
747
|
-
Obviously the greater the number of files which need to be kept private the more
|
748
|
-
difficult it is to manage the settings. Therefore we suggest beginning with one
|
749
|
-
private file that stores all of your credentials.
|
750
|
-
|
751
|
-
### Ignoring Settings Files
|
752
|
-
|
753
|
-
We recommend adding the following to your `.gitignore` file:
|
754
|
-
|
755
|
-
```
|
756
|
-
# Ignore the environment-specific files that contain the real credentials:
|
757
|
-
/config/credentials.yml
|
758
|
-
/config/credentials-*.yml
|
759
|
-
|
760
|
-
# But don't ignore the example file that shows the structure:
|
761
|
-
!/config/credentials-example.yml
|
762
|
-
```
|
763
|
-
|
764
|
-
Along with any namespace-specific exclusions. For example, if you're using
|
765
|
-
Rails, you may want to exclude some of your environment-specific files:
|
766
|
-
|
767
|
-
```
|
768
|
-
*-staging.yml
|
769
|
-
*-production.yml
|
770
|
-
```
|
862
|
+
We recommend starting with a single `settings.yml` file. Once this file begins
|
863
|
+
to become too unwieldy, you can begin to extract common options (let's say SMTP
|
864
|
+
settings) into another file (perhaps `settings/smtp.yml`).
|
771
865
|
|
772
866
|
### Full Example
|
773
867
|
|
@@ -778,29 +872,48 @@ Let's walk through how you might use Chamber to configure your SMTP settings:
|
|
778
872
|
|
779
873
|
stuff:
|
780
874
|
not: "Not Related to SMTP"
|
875
|
+
```
|
781
876
|
|
877
|
+
```yaml
|
782
878
|
# config/settings/smtp.yml
|
783
879
|
|
784
|
-
|
785
|
-
|
786
|
-
|
787
|
-
|
880
|
+
default: &shared
|
881
|
+
smtp:
|
882
|
+
headers:
|
883
|
+
X-MYAPP-NAME: My Application Name
|
884
|
+
X-MYAPP-STUFF: Other Stuff
|
788
885
|
|
789
|
-
|
886
|
+
development:
|
887
|
+
<<: *shared
|
888
|
+
smtp:
|
889
|
+
username: my_dev_user
|
890
|
+
password: my_dev_password
|
790
891
|
|
791
|
-
|
792
|
-
|
793
|
-
|
892
|
+
staging:
|
893
|
+
<<: *shared
|
894
|
+
smtp:
|
895
|
+
_secure_username: my_staging_user
|
896
|
+
_secure_password: my_staging_password
|
897
|
+
|
898
|
+
production:
|
899
|
+
<<: *shared
|
900
|
+
smtp:
|
901
|
+
_secure_username: my_production_user
|
902
|
+
_secure_password: my_production_password
|
794
903
|
```
|
795
904
|
|
796
|
-
Now you can access both `username` and
|
905
|
+
Now, assuming you're running in staging, you can access both `username` and
|
906
|
+
`headers` off of `smtp` like so:
|
797
907
|
|
798
908
|
```ruby
|
799
909
|
Chamber[:smtp][:headers]
|
800
910
|
# => { X-MYAPP-NAME: 'My Application Name', X-MYAPP-STUFF: 'Other Stuff' }
|
801
911
|
|
912
|
+
Chamber[:smtp][:username]
|
913
|
+
# => my_staging_username
|
914
|
+
|
802
915
|
Chamber[:smtp][:password]
|
803
|
-
# =>
|
916
|
+
# => my_staging_password
|
804
917
|
```
|
805
918
|
|
806
919
|
## Alternatives
|
@@ -810,9 +923,11 @@ Chamber[:smtp][:password]
|
|
810
923
|
* [idkfa](https://github.com/bendyworks/idkfa)
|
811
924
|
* [settingslogic](https://github.com/binarylogic/settingslogic)
|
812
925
|
|
813
|
-
|
926
|
+
## Thanks
|
814
927
|
|
815
|
-
|
928
|
+
Special thanks to all those gem authors above @binarylogic, @bendyworks,
|
929
|
+
@laserlemon and @bkeepers. They gave us the inspiration to write this gem and
|
930
|
+
we would have made a lot more mistakes without them paving the way. Thanks all!
|
816
931
|
|
817
932
|
## Contributing
|
818
933
|
|