ReleaseKit

Copy Markdown

ReleaseKit builds deployment-neutral artifacts from Mix OTP releases.

It produces two files:

  • a compressed OTP release tarball;
  • an ETF manifest describing the tarball, runtime command, environment hints, and optional health check.

Deployment tools such as HostKit can consume the manifest, but ReleaseKit does not know about systemd, users, Caddy, hosts, or filesystem layouts.

Installation

def deps do
  [
    {:release_kit, "~> 0.1", only: [:dev], runtime: false}
  ]
end

Usage

Build a production release artifact:

MIX_ENV=prod mix release_kit.artifact --out-dir _build/prod/artifacts

For a web service, include health-check metadata:

MIX_ENV=prod mix release_kit.artifact \
  --out-dir _build/prod/artifacts \
  --port 4000 \
  --health-path /

The output names are stable for deployment tooling:

_build/prod/artifacts/my_app-20260620-abcdef0.tar.gz
_build/prod/artifacts/my_app.etf

The manifest is an ETF-encoded map:

%{
  tool: "release_kit",
  format: :beam_release_artifact,
  format_version: 1,
  app: "my_app",
  release: "my_app",
  version: "20260620-abcdef0",
  mix_env: "prod",
  tarball: "/absolute/path/to/my_app-20260620-abcdef0.tar.gz",
  runtime: %{command: ["bin/my_app", "start"]},
  env: %{clear: %{}, secret: []},
  health_check: %{path: "/", port: 4000, url: "http://127.0.0.1:4000/"}
}

Application aliases

Projects can add their own shorter alias or prebuild steps:

defp aliases do
  [
    "release.artifact": ["assets.deploy", "release_kit.artifact"]
  ]
end

ReleaseKit deliberately does not run asset builders or delete generated files on its own. Keep those choices in the consuming application.