Thanks to @tylerflint for the original Makefile, rel.config, and runner script which inspired this project!
You can build a release with the release
task:
mix release
This task constructs the complete release for you. The output is sent to rel/<project>
. To see what flags you can pass to this task, use mix help release
.
One really cool thing you can do is mix release --dev
. This will symlink your application's code into the release, allowing you to make code changes, recompile with MIX_ENV=prod mix compile
, and rerun your release with rel/<project>/bin/<project> console
to see the changes. Being able to rapidly test and tweak your release like this goes a long way to making the release process less tedious!
mix release.clean [--implode]
Without args, this will clean up the release corresponding to the current project version.
With --implode
, all releases, configuration, generated tools, etc.,
will be cleaned up, leaving your project directory the same as if exrm
had never been run. This is a destructive operation, as you can't get
your releases back unless they were source-controlled, so exrm will ask
you for confirmation before proceeding with the cleanup.
NOTE: Umbrella projects work a little differently. Each sub-project is built into it's own release, but contains all of it's dependencies
This project's goal is to make releases with Elixir projects a breeze. It is composed of a mix task, and build files required to successfully take your Elixir project and perform a release build, and a simplified configuration mechanism which integrates with your current configuration and makes it easy for your operations group to configure the release once deployed. All you have to do to get started is the following:
defp deps do
[{:exrm, "~> 0.12.7"}]
end
mix deps.get
mix deps.compile
mix release
There are two forms of configuration I will deal with here. One is configuration for the release process, the latter is handling application configuration for your release. The following custom release configuration is supported:
sys.config
- This is the configuration file the release will use in production. I would useconfig/config.exs
orconfig/myapp.conf
instead of this, but it's there if you want it.vm.args
- This file contains line-separated arguments that the Erlang VM will use when booting up. Provide your own here and it will be used instead of the default one. Make sure you provide values forsname
andcookie
though, or you won't be able to connect to your release!relx.config
- This file is used to provide configuration to exrm's underyling relx dependency. The dependency will be going away in the future, but the configuration file will remain (though it may be renamed). See the documentation at relx's GitHub page for more information on what you can provide here. The default one should cover 99% of cases, but if you need to tweak values, you can provide your own relx configuration, by creating a file atrel/relx.config
and setting the config values you care about. You do not need to provide the entire configuration, as your customizations will be merged with the defaults exrm uses.
I'm going to go in to more detail on how application configuration works later on,
for now just know that when you run mix release
for the first time,
exrm will warn you that it couldn't find a yourapp.conf
and
yourapp.schema.exs
file, and generates them for you based on your
current configuration which is defined in config/config.exs
. The
.conf
is where you will configure your app, and the .schema.exs
is
where you define the configuration available in the .conf
.
> rel/test/bin/test console
Erlang/OTP 17 [erts-6.0] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]
Interactive Elixir (0.14.3) - press Ctrl+C to exit (type h() ENTER for help)
iex([email protected])1> :gen_server.call(:test, :ping)
:v1
iex([email protected])2>
See the next few sections for information on how to deploy, run, upgrade/downgrade, and remotely connect to your release!
Elixir has support for providing configuration using Elixir terms in a
config/config.exs
file. While this is perfectly usable, it's not very
simple for your operations group to work with, and generally contains no
useful documentation on what each setting is for or what they do. To
help make configuration much more easy and maintainable, exrm bundles a
dependency called conform.
Conform relies primarily on two files: a yourapp.schema.exs
file, and
a yourapp.conf
file. The .conf file is where you will configure your
app, and the .schema.exs file is where you define what configuration is
available in the .conf, and how it is translated to the final
sys.config
that your release loads up at runtime.
Conform itself has the best documentation on how to work with these files, and to see an example app which makes use of this, check out the exrm-test project.
Here's a quick rundown on how it works. You probably already have a config.exs
file, and if
you don't that's fine, it's not required. If you do have one already,
you can compile your project and run mix conform.new
to generate the
conform schema from your current configuration. If you don't have one,
check out the conform README on how to create one. Once you have the
schema file in your config
directory, you can work off the
definitions generated from your current config, and/or start adding
definitions for config settings you wish to add.
Once your schema is all set, you can generate the default .conf file for
your app using mix conform.configure
. This will output a .conf file to
config/yourapp.conf
. This will be bundled with your release, and
located in $DEPLOY_DIR/releases/$RELEASE_VER/myapp.conf
. Your ops
group can then do all their configuration in production via that file.
If you are wondering how that .conf file is usable by the VM, it's very
simple. When you run bin/test start
, or any other command which boots
your app, a conform escript is run which translates the .conf via the
schema (also bundled with the release) to Elixir terms, that is then
merged over the top of the sys.config which is also bundled with the
release, and then saved over the top of the existing sys.config. Once
the escript has finished executing, your app is booted using that
sys.config file, and everything carries on like normal.
NOTE: Your config/config.exs
file is still converted to the
sys.config
which is bundled with the release. If you wish to hide
settings from your end users, put them in there, and remove the
definitions for them from your schema file. The sys.config
is merged
with the configuration which is defined in the .conf, so your settings
will still be applied, they just won't be exposed for end users.
Now that you've generated your first release, it's time to deploy it! Let's walk through a simulated deployment to the /tmp
directory on your machine, using the example app from the Appendix.
mix release
mkdir -p /tmp/test
cp rel/test/test-0.0.1.tar.gz /tmp/
cd /tmp/test
tar -xf /tmp/test-0.0.1.tar.gz
Now to start your app:
bin/test start
You can test if your app is alive and running with bin/test ping
.
If you want to connect a remote shell to your now running app:
bin/test remote_console
Ok, you should be staring at a standard iex
prompt, but slightly different: iex(test@localhost)1>
. The prompt shows us that we are currently connected to test@localhost
, which is the value of name
in our vm.args
file. Feel free to ping the app using :gen_server.call(:test, :ping)
to make sure it works.
At this point, you can't just abort from the prompt like usual and make the node shut down. This would be an obviously bad thing in a production environment. Instead, you can issue :init.stop
from the iex
prompt, and this will shut down the node. You will still be connected to the shell, but once you quit the shell, the node is gone.
If you want to execute a command against your running node without attaching a shell:
bin/test rpc erlang now
or
bin/test rpc calendar valid_date "{2014,3,14}."
Notice that the arguments required are in module, function, argument
format. The argument parameter will be evaluated as an Erlang term,
and applied to the module/function. Multiple args should be formatted as
a list, i.e. [arg1, arg2, arg3].
.
So you've made some changes to your app, and you want to generate a new relase and perform a no-downtime upgrade. I'm here to tell you that this is going to be a breeze, so I hope you're ready (I'm using my test app as an example here again):
mix release
mkdir -p /tmp/test/releases/0.0.2
cp rel/test/test-0.0.2.tar.gz /tmp/test/releases/0.0.2/test.tar.gz
cd /tmp/test
bin/test upgrade "0.0.2"
Annnnd we're done. Your app was upgraded in place with no downtime, and is now running your modified code. You can use bin/test remote_console
to connect and test to be sure your changes worked as expected.
You can also provide your own .appup file, by writing one and placing it in
rel/<app>.appup
. This location is checked before generating a new
release, and will be used instead of autogenerating an appup file for
you.
This is even easier! Using the example from before:
cd /tmp/test
bin/test downgrade "0.0.1"
All done!
I'm starting this list to begin collating the various caveats around building releases. As soon as I feel like I have a firm grasp of all the edge cases, I'll formalize this in a better format perhaps as a "Preparing for Release" document.
- Ensure all dependencies for your application are defined in either the
:applications
or:included_applications
block of yourmix.exs
file. This is how the build process knows that those dependencies need to be bundled in to the release. This includes dependencies of your dependencies, if they were not properly configured. For instance, if you depend onmongoex
, andmongoex
depends onerlang-mongodb
, butmongoex
doesn't haveerlang-mongodb
in it's applications list, your app will fail in it's release form, becauseerlang-mongodb
won't be loaded. - If you are running into issues with your dependencies missing their
dependencies, it's likely that the author did not put the dependencies in
the
:application
block of theirmix.exs
. You may have to fork, or issue a pull request in order to resolve this issue. Alternatively, if you know what the dependency is, you can put it in your ownmix.exs
, and the release process will ensure that it is loaded with everything else.
If you run into problems, please create an issue, and I'll address ASAP.
You can find the source code for the example application here, and an example umbrella application here. Everything mentioned here should work out of the box with those projects. If it does not, please file a bug!