Cuttlefish is a library for Erlang applications that wish to walk the
fine line between Erlang
app.configs and a sysctl-like syntax.
The name is a pun on the pronunciation of 'sysctl' and jokes are
This repository retains full history of the original repository, basho/cuttlefish/, but intentionally cut ties with that repo to avoid confusion as to where is the most up-to-date, maintained version is.
This is the repository used to produce Hex.pm releases of the project.
While this readme and test suite is Riak-heavy, the fact is that this library can be used with any Erlang application that wants a more universally accessible configuration syntax. Still, I built this for Riak, and it's nice to have a concrete example to work with.
app.config is the definitive place for
configuring Riak. It's not odd for Erlang applications to be
configured this way, but it is a struggle for non-Erlang programmers
and automated deployment tools to manipulate these files. On the other
app.config is a useful construct for Erlang programmers,
and it is pretty coupled to OTP applications.
Cuttlefish's goal is to put a layer of abstraction on top of the
app.config that is easier to work with outside of the Erlang world.
It will allow Erlang programmers to write a schema for their
application's configuration file, which is independent of the
applications included in the project. The schema is one of the more
important parts of Cuttlefish, so we'll go into more detail on it
below, but it is written in Erlang and defines how the non-Erlang
configuration file works.
From this schema, you can generate a default
.conf file for your
application. This will be the file that is packaged with your
application as the default configuration.
The schema is also used to generate an
app.config that will be used
to start your application. Using the schema alone will generate all
the proper defaults. Your users can make changes to the
and those changes will overwrite the schema's defaults.
You an also have an
advanced.config which looks like the old
app.config for anything that no schema mapping is created for.
What does this look like for an application like Riak?
Well, the authors of Riak maintain a schema for Riak's config. It
defines all sorts of things we'll get into later. When we build Riak,
Cuttlefish generates a
riak.conf file that contains the default
shipping configuration of Riak. When a script to start Riak is run, a
Cuttlefish escript is spun up, reads the
riak.conf file and combines
that with the Schema to generate an
app.config. The script then
exits, and a new Erlang VM (destined to run Riak) is started with that
app.config. Down the line somewhere, you may be
troubleshooting some part of Riak, and the support organization at
Basho may need you to manipulate a configuration setting that is not
exposed by the schema because it is so infrequently used. In that
case, we can set that setting directly in an
sits in the same directory as
I hope that gives you a good idea about how this works at a high level.
You can learn more about the technical implementation of schemas at: https://github.com/basho/cuttlefish/wiki/Cuttlefish-for-Erlang-Developers
Riak uses the semantic of
$conf_dir/app.config for configuration.
We're going to replace that with a file called
riak.conf, with a
syntax that looks like this:
ring_size = 32 anti_entropy = debug log.error.file = /var/log/error.log log.console.file = /var/log/console.log log.syslog = on
More information for users here: https://github.com/basho/cuttlefish/wiki/Cuttlefish-for-Application-Users
Cuttlefish is ready for production deployments.
rebar3 as dev neotoma
Please see the NOTE in
src/conf_parse.peg as well.