197 lines
11 KiB
HTML
197 lines
11 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Managing application configuration with Envy</title>
|
|
<meta name="description" content="Application configuration can be a pain. Modern web apps don't live on dedicated boxes, they run on VPSes somewhere in the amorphous "cloud", and keeping configuration out of your application's repository can seem like more trouble than it's worth. Fortun...">
|
|
<meta name="author" content="Alexis King">
|
|
<meta name="keywords" content="envy, racket, 12factor">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<link rel="icon" href="/favicon.ico">
|
|
<link rel="canonical" href="http://lexi-lambda.github.io/blog/2015/08/30/managing-application-configuration-with-envy/">
|
|
<link rel="next" href="/blog/2015/08/22/deploying-racket-applications-on-heroku/">
|
|
<link rel="prev" href="/blog/2015/09/23/canonical-factories-for-testing-with-factory-girl-api/">
|
|
<!-- CSS -->
|
|
<link rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Merriweather+Sans:400,300,300italic,400italic,700,700italic,800,800italic|Merriweather:400,300,300italic,400italic,700,700italic,900,900italic|Source+Code+Pro:200,300,400,500,600,700,900">
|
|
<link rel="stylesheet" type="text/css" href="/css/application.min.css">
|
|
<link rel="stylesheet" type="text/css" href="/css/pygments.min.css">
|
|
<!-- Feeds -->
|
|
<link rel="alternate" type="application/atom+xml"
|
|
href="/feeds/all.atom.xml" title="Atom Feed">
|
|
<link rel="alternate" type="application/rss+xml"
|
|
href="/feeds/all.rss.xml" title="RSS Feed">
|
|
<!-- JS -->
|
|
<!-- <script src="/js/application.min.js"></script> -->
|
|
<script type="text/javascript">
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-65250372-1', 'auto');
|
|
ga('send', 'pageview');
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<div id="page-content">
|
|
<!-- Navigation Bar -->
|
|
<header>
|
|
<nav role="navigation" class="navigation-bar">
|
|
<ul class="navigation-items left">
|
|
<li id="blog-title-header"><a href="/"><h1>Alexis King</h1></a></li>
|
|
</ul>
|
|
<ul class="navigation-items center"></ul>
|
|
<ul class="navigation-items right">
|
|
<li><a href="/">Home</a></li>
|
|
<li><a href="/about.html">About</a></li>
|
|
</ul>
|
|
</nav>
|
|
</header>
|
|
<section role="main">
|
|
<!-- Main column -->
|
|
<div class="content" class="col-md-12">
|
|
|
|
|
|
|
|
<article class="main">
|
|
<header>
|
|
<h1 class="title">Managing application configuration with Envy</h1>
|
|
<div class='date-and-tags'>
|
|
<time datetime="2015-08-30T16:05:37">
|
|
2015-08-30
|
|
</time>
|
|
<span style="margin: 0 3px">⦿</span>
|
|
<span class="tags"><a href="/tags/envy.html">envy</a>, <a href="/tags/racket.html">racket</a>, <a href="/tags/12factor.html">12factor</a></span>
|
|
</div>
|
|
</header>
|
|
|
|
<p>Application configuration can be a pain. Modern web apps don’t live on dedicated boxes, they run on VPSes somewhere in the amorphous “cloud”, and keeping configuration out of your application’s repository can seem like more trouble than it’s worth. Fortunately, <a href="http://12factor.net">The Twelve-Factor App</a> provides a set of standards for keeping web apps sane, and <a href="http://12factor.net/config">one of those guidelines advises keeping configuration in the environment</a>.</p>
|
|
|
|
<p><a href="https://github.com/lexi-lambda/envy">Envy</a> is the declarative bridge between Racket code and the outside world of the environment.</p>
|
|
<!-- more-->
|
|
|
|
<h1 id="introducing-envy">Introducing Envy</h1>
|
|
|
|
<p>I built Envy to distill the common tasks needed when working with environment variables into a single, declarative interface that eliminates boilerplate and makes it easy to see which environment variables an application depends on (instead of having them littered throughout the codebase). Using it is simple. Just require <code>envy</code> and you’re good to go.</p>
|
|
|
|
<p>The best way to use Envy is to create a “manifest” module that declares all the environment variables your application might use. For example, the following module is a manifest that describes an application that uses three environment variables:</p>
|
|
|
|
<div class="brush: racket">
|
|
<table class="sourcetable">
|
|
<tbody>
|
|
<tr>
|
|
<td class="linenos">
|
|
<div class="linenodiv">
|
|
<pre>1
|
|
2
|
|
3
|
|
4
|
|
5
|
|
6
|
|
7
|
|
8
|
|
9</pre></div></td>
|
|
<td class="code">
|
|
<div class="source">
|
|
<pre><span></span><span class="c1">; environment.rkt</span>
|
|
<span class="kn">#lang </span><span class="nn">typed/racket/base</span>
|
|
|
|
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="n">envy</span><span class="p">)</span>
|
|
|
|
<span class="p">(</span><span class="n">define/provide-environment</span>
|
|
<span class="n">api-token</span>
|
|
<span class="p">[</span><span class="n">log-level</span> <span class="n"><a href="http://docs.racket-lang.org/ts-reference/special-forms.html#(form._((lib._typed-racket/base-env/prims..rkt)._~3a))" style="color: inherit">:</a></span> <span class="n"><a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types..rkt)._.Symbol))" style="color: inherit">Symbol</a></span> <span class="kd">#:default</span> <span class="o">'</span><span class="ss">info</span><span class="p">]</span>
|
|
<span class="p">[</span><span class="n">parallel?</span> <span class="n"><a href="http://docs.racket-lang.org/ts-reference/special-forms.html#(form._((lib._typed-racket/base-env/prims..rkt)._~3a))" style="color: inherit">:</a></span> <span class="n"><a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types..rkt)._.Boolean))" style="color: inherit">Boolean</a></span><span class="p">])</span>
|
|
</pre></div>
|
|
</td></tr></tbody></table>
|
|
</div>
|
|
|
|
<p>When this module is required, Envy will automatically do the following:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Envy will check the values of three environment variables: <code>API_TOKEN</code>, <code>LOG_LEVEL</code>, and <code>PARALLEL</code>.</p></li>
|
|
<li>
|
|
<p>If either <code>API_TOKEN</code> or <code>PARALLEL</code> is not set, an error will be raised:</p>
|
|
<pre><code>envy: The required environment variable "API_TOKEN" is not defined.</code></pre></li>
|
|
<li>
|
|
<p>The values for <code>LOG_LEVEL</code> and <code>PARALLEL</code> will be parsed to match their type annotations.</p></li>
|
|
<li>
|
|
<p>If <code>LOG_LEVEL</code> is not set, it will use the default value, <code>'info</code>.</p></li>
|
|
<li>
|
|
<p>The values will be stored in <code>api-token</code>, <code>log-level</code>, and <code>parallel?</code>, all of which will be provided by the enclosing module.</p></li></ol>
|
|
|
|
<p>Now just <code>(require (prefix-in env: "environment.rkt"))</code>, and the environment variables are guaranteed to be available in your application’s code.</p>
|
|
|
|
<h1 id="working-with-typed-racket">Working with Typed Racket</h1>
|
|
|
|
<p>As you may have noticed by the example above, Envy is built with Typed Racket in mind. In fact, <code>define/provide-environment</code> will <em>only</em> work within a Typed Racket module, but that doesn’t mean Envy can’t be used with plain Racket—the manifest module can always be required by any kind of Racket module.</p>
|
|
|
|
<p>However, when using Typed Racket, Envy provides additional bonuses. Environment variables are inherently untyped—they’re all just strings—but Envy assigns the proper type to each environment variable automatically, so no casting is necessary.</p>
|
|
|
|
<pre><code>> parallel?
|
|
- : Boolean
|
|
#t</code></pre>
|
|
|
|
<p>Envy really shines when using optional environment variables with the <code>#:default</code> option. The type of the value given to <code>#:default</code> doesn’t need to be the same type of the environment variable itself, and if it isn’t, Envy will assign the value a union type.</p>
|
|
|
|
<pre><code>> (define-environment
|
|
[num-threads : Positive-Integer #:default #f])
|
|
> num-threads
|
|
- : (U Positive-Integer #f)
|
|
#f</code></pre>
|
|
|
|
<p>This added level of type-safety means it’s easy to manage optional variables that don’t have reasonable defaults: the type system will enforce that all code considers the possibility that such variables do not exist.</p>
|
|
|
|
<h1 id="and-more">And more…</h1>
|
|
|
|
<p>To see the full set of features that Envy already provides, <a href="https://lexi-lambda.github.io/envy/envy.html">take a look at the documentation</a>. That said, this is just the first release based on my initial use-cases, but I’m sure there are more features Envy could have to accommodate common application configuration patterns. If you have an idea that could make Envy better, <a href="https://github.com/lexi-lambda/envy/issues">open an issue and make a suggestion</a>! I already have plans for a <code>#lang envy</code> DSL, which will hopefully cut the boilerplate out in its entirety.</p>
|
|
|
|
<p>And finally, to give credit where credit is due, Envy is heavily inspired by <a href="https://github.com/eval/envied">Envied</a> (both in name and function), an environment variable manager for Ruby, which I’ve used to great effect.</p>
|
|
|
|
<p>Try it out!</p>
|
|
|
|
<ul>
|
|
<li><code>raco pkg install envy</code></li>
|
|
<li><a href="https://github.com/lexi-lambda/envy">Envy on GitHub</a></li>
|
|
<li><a href="https://lexi-lambda.github.io/envy/envy.html">Envy documentation</a></li></ul>
|
|
<footer>
|
|
<script type="text/javascript">
|
|
var disqus_shortname = 'lexi-lambda';
|
|
(function() {
|
|
var dsq = document.createElement('script');
|
|
dsq.type = 'text/javascript';
|
|
dsq.async = true;
|
|
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
|
|
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
|
|
})();
|
|
</script>
|
|
<div id="disqus_thread"></div>
|
|
<ul class="pager">
|
|
<li class="previous">
|
|
<a href="/blog/2015/09/23/canonical-factories-for-testing-with-factory-girl-api/">← <em>Canonical factories for testing with factory_girl_api</em></a>
|
|
</li>
|
|
<li class="next">
|
|
<a href="/blog/2015/08/22/deploying-racket-applications-on-heroku/"><em>Deploying Racket applications on Heroku</em> →</a>
|
|
</li>
|
|
</ul>
|
|
</footer>
|
|
</article>
|
|
</div>
|
|
</section>
|
|
<footer>
|
|
<div class="content">
|
|
<h2 id="copyright-notice">© 2016, Alexis King</h2>
|
|
<h3>
|
|
Built with <a href="https://github.com/greghendershott/frog">Frog</a>, the
|
|
<strong>fr</strong>ozen bl<strong>og</strong> tool.
|
|
</h3>
|
|
<h3>
|
|
Feeds are available via <a href="/feeds/all.atom.xml">Atom</a>
|
|
or <a href="/feeds/all.rss.xml">RSS</a>.
|
|
</h3>
|
|
</div>
|
|
</footer>
|
|
</div>
|
|
</body>
|
|
</html> |