Setup Plugin

Copy Markdown View Source

Project-scaffolding commands. Use this plugin to create a fresh umbrella with Marea wired up, or to bootstrap a release inside an existing project.

Always loaded (part of @base_plugins).

Commands

marea setup
├── init-marea                   (bootstrap marea.d/ in the current project)
├── init-umbrella   --name <project>
└── init-release    --app  <umbrella-app>

marea setup init-marea

Bootstraps Marea in the current project: creates a marea.d/ directory with configs/ and secrets/ subdirectories and a stub marea.d/marea.yaml.

> marea setup init-marea
Created marea.d/marea.yaml and subdirs (configs/, secrets/)

Aborts if a config already exists at any of the discovery paths (marea.yaml, config/marea.yaml, marea.d/marea.yaml). This is the command Marea points you at on first run when no config is found — see Installation → First run. Unlike every other command, setup init-marea (and the other setup commands) run without an existing marea.yaml.

marea setup init-umbrella --name <project>

Creates a new umbrella project named <project> next to the current directory and wires Marea into it.

Steps performed:

  1. mix new <project> --umbrella
  2. mix new <project>_sample --sup inside <project>/apps/
  3. Add a {:marea, path: "<abs-path-to-marea-source>", runtime: false, only: :dev} entry to <project>/mix.exs (idempotent — does nothing if :marea is already listed). The path is the absolute location of the marea source checkout you ran this from, since marea is consumed from source (it is not published to hex).
  4. mix deps.get && mix compile inside the new umbrella.
  5. Symlink the shipped Marea binary into the new umbrella as <project>/marea.

After this command, cd <project> and start writing marea.yaml.

marea setup init-release --app <app>

Bootstraps a Mix release in the current project, using the named umbrella app as the entry point.

Steps performed:

  1. If rel/ doesn't exist, run mix release.init.
  2. Write rel/env.sh.eex from the embedded priv/templates/rel/env.sh.eex template — this is the Marea-flavoured env script that resolves RELEASE_NODE from NODE_NAME / NODE_HOST / RELEASE_COOKIE. If rel/ already exists, you'll be asked before overwriting.
  3. Use Igniter to:
    • Add releases: releases() to the project keyword in mix.exs.
    • Add or extend releases/0 with <app>: [applications: [<app>: :permanent]].

Other plugins can override the file content by implementing Marea.Plugins.Base.marea_init_release_file/1 with the :env_sh_eex argument.

Implementation notes

  • init-umbrella invokes mix new for both the umbrella and the sample app via Lib.cmd!/3. They run with prefix: :build, so if you set cmd_prefix.build in marea.yaml (e.g. running builds inside a Linux container), the bootstrap commands honour it too.
  • init-release uses Igniter to mutate mix.exs in a structured way: it walks the AST to find the project module, the project/0 function, and releases/0, rather than doing string substitution. This makes it safe to re-run after manually editing mix.exs.

Source