Quick start

Copy Markdown View Source

This guide takes you from an empty directory to a Helm-deployed Elixir release on a Kubernetes cluster, using the AWS plugin for the container registry.

It assumes you already followed 02-installation.md and have a working marea binary on your PATH (or in ./marea).

1. Create an umbrella

marea setup init-umbrella --name acme
cd acme

You now have an umbrella project with one sample app (acme_sample), Marea added as a dev dep, and ./marea linked into the project.

2. Initialise a release

./marea setup init-release --app acme_sample

This creates rel/, writes rel/env.sh.eex, and adds a releases/0 function to mix.exs with an acme_sample entry.

3. Write marea.yaml

Run marea setup init-marea to scaffold a marea.d/marea.yaml (Marea points you at this command on first run when no config is found). You can also create it by hand:

# marea.d/marea.yaml
plugins:
  - Marea.Plugins.Helm        # pulls in Docker + Build via plugin_deps
  - Marea.Plugins.K8s
  - Marea.Plugins.Aws

aws:
  default:
    profile: acme
    region: eu-west-1
    account_id: "123456789012"
    ecr:
      image_header: acme/

deploys:
  staging:
    helm:
      namespace: acme-staging
      kube_context: staging-cluster
      chart: acme
    releases:
      acme_sample:
        type: elixir
        helm:
          template: deployment.yaml
        domains:
          - acme.staging.example.com

The plugins: list controls which optional plugins are loaded for this project. The base plugins (Setup, Build, Run, Base) are loaded automatically; everything else is opt-in: Marea.Plugins.Docker (container builds, the docker: schema block, and the :elixir / :dockerfile_dir release types), Marea.Plugins.Helm (chart generation, helm.* schema, the :helm deploy type, and the build helm subcommand), docker.python (Python venv injected into the build image), Marea.Plugins.Aws, Marea.Plugins.K8s, or any plugin of your own. plugin_deps: resolves the obvious chains for you — listing Helm brings in Docker and Build transitively.

See 04-marea-yaml.md for the complete reference.

4. Add a deployment template

The Helm plugin generates a Helm chart for each deploy by walking releases: and rendering one template per release. The template name (deployment.yaml above) is resolved against marea.d/templates/ first, then against Marea's built-in templates.

Create marea.d/templates/deployment.yaml describing how a single release should run in Kubernetes. See plugins/helm.md for available assigns (@deploy, @name, @namespace, @values, @config_files, @secret_files).

5. Create the ECR repository

./marea aws ecr create

This shells out to aws ecr create-repository --repository-name acme/, using the profile, region, and image_header from marea.yaml. For repeated builds you'll also want a Docker login:

./marea aws ecr login-docker

6. Build and push the image

./marea build docker --deploy staging --release acme_sample

Marea will:

  1. Run mix release acme_sample --overwrite in your project.
  2. rsync the project into .marea/build/.
  3. Render a Dockerfile from the built-in dockerfile_v01 template (or your override in marea.d/templates/).
  4. Run docker build and tag the result acme_sample:<git-vsn> and acme_sample:latest.

7. Generate and apply the Helm chart

The combined build helm --upgrade command builds the image, pushes it to ECR, updates the deploy's values.yaml with the new image reference, and runs helm upgrade --install:

./marea build helm --deploy staging --release acme_sample --upgrade

If you only want to regenerate the chart without deploying:

./marea helm chart --deploy staging
./marea helm template
./marea helm upgrade

./marea helm template prints the rendered manifests so you can inspect them before applying.

8. Inspect deployment state

./marea helm list
./marea helm history
./marea helm values

If something went wrong:

./marea helm rollback --pos 1

9. Run locally without deploying

While iterating on code, you can run the project as a local IEx node or as a release:

./marea run local                                   # iex -S mix
./marea run release --deploy staging --release acme_sample

run local and run release end with a deferred command that replaces the parent shell, so they attach to your terminal as a normal iex session.

10. Subsequent commands

After this first run, Marea remembers the deploy and release in .marea/last_values. Most commands can be shortened:

./marea build docker
./marea build helm --upgrade
./marea helm history
./marea run release

Use --deploy / --release again only when you want to switch target.

Where to go next