Aero config migration advice

[jacobobryant]

In preparation for the upcoming v1.0.0 release which includes an optional-but-recommended migration to Aero for config, I'm going through the upgrade instructions on one of my apps and wanted to give some more tips about rewriting your config in the format that Aero wants. Here's what step 4 says:

4. Edit resources/config.edn and config.env to include any custom config that you previously put in config.edn or secrets.env. For example, you'll need to copy the values of COOKIE_SECRET and JWT_SECRET from secrets.env into config.env. resources/config.edn will be parsed with Aero. To specify different config values for different environments, you'll do e.g. {:example/foo #profile {:prod "bar" :dev "baz"} ... instead of {:prod {:example/foo "bar" ...} :dev {:example/foo "baz" ...} ....

Here's specifically what I did. The process was fairly mechanical:

1. Update all the existing values in config.env.
2. Copy everything from secrets.env to config.env. (I also removed the exports, but it's fine if you leave them in.) Sort the lines (I used vim's :sort command), then remove duplicates.
3. Update all the existing values in resources/config.edn.
4. Open the old config.edn file and copy everything from the :prod section into resources/config.edn. For any keys that referenced values in secrets.env, add a #biff/secret. For example, I changed :mailgun/api-key "MAILGUN_API_KEY" to :mailgun/api-key #biff/secret MAILGUN_API_KEY.
5. Now copy everything from the :dev section into resources/config.edn. Add #biff/secret where needed. Any keys that start with :biff you can probably remove, since the default resources/config.edn file comes with various Biff config keys already set.
6. Wrap all the values that came from the :dev section with a #profile {:dev ...}. For example, in my config I changed :com.yakread/disable-email-task true to :com.yakread/disable-email-task #profile {:dev true}.
7. For each key that came from the :dev section, check to see if it was also in the :prod section. If so, merge the two keys with #profile, for example: :stripe/api-key #profile {:prod #biff/secret STRIPE_SECRET_KEY :dev #biff/secret STRIPE_TEST_SECRET_KEY}.

You probably don't need to migrate anything over from the :tasks section unless you defined some custom tasks that used custom config.

Going forward, the choice of whether to store a particular piece of config in resources/config.edn or config.env is up to you/your situation. Secrets should always be stored in config.env, but for everything else, you can default to putting it in resources/config.edn and then only move it to config.env if there's a need. For example, if you're developing an open-source app, you can put things in config.env so that other people can supply their own config values.

If you want to supply a default value in resources/config.edn but allow it to be overridden via config.env/an environment variable, you can do e.g. :foo/some-config-key #or [#biff/env FOO_SOME_CONFIG_KEY, "abc123"].

If you have any questions about migrating, feel free to ask here.