Getting Started

Copy Markdown View Source

This is the first-success path for the current 0.1.3 package line on Hex: install the runtime, gate one code path, and optionally mount the admin UI.

1. Add dependencies

Runtime only:

{:rulestead, "~> 0.1"}

Runtime plus admin UI:

{:rulestead, "~> 0.1"},
{:rulestead_admin, "~> 0.1"}

Repo GA shipped in v1.0.0 on 2026-05-21, but adoption today still starts from the 0.1.x sibling packages shown above.

2. Install and migrate

mix deps.get
mix rulestead.install
mix ecto.migrate

Phoenix first-hour path: Phoenix Integration Spine (supervision → config → Plug → first Rulestead.Runtime eval → lifecycle-honest flag create).

Lifecycle required at flag create: Every new flag must include owner_ref (host-owned team or service reference) and expected_expiration (review date). Rulestead does not maintain a team directory. See Flag Lifecycle and Create your first flag in the spine.

Evaluating first? Run the Adoption Lab (FleetDesk) to see Rulestead with realistic seeds and operator screens before installing into your app. Use docker compose up --build or scripts/demo/proof.sh.

3. Gate a code path

For the ordered Plug → snapshot runtime path, follow the Phoenix Integration Spine. Below is the payload-first contract for tests and simulations.

Build an explicit %Rulestead.Context{} and evaluate against a flag payload. This is the canonical contract documented in ../flows/evaluation.md:

context =
  Rulestead.Context.new(
    environment: "production",
    targeting_key: "user-123",
    attributes: %{plan: :pro}
  )

flag_payload = ... # from snapshot or store

with {:ok, result} <- Rulestead.evaluate(flag_payload, context) do
  if result.enabled? do
    render_v2(conn)
  else
    render_v1(conn)
  end
end

Snapshot runtime lookup

Phoenix apps with the snapshot cache typically use Rulestead.Runtime and conn.assigns[:rulestead_context] — see the Phoenix Integration Spine and evaluation.md. Projection helpers on Rulestead (enabled?/2, get_variant/2) accept flag payload + context, not a string key on %Plug.Conn{}.

4. Optionally mount the admin UI

If your host Phoenix app needs the operator UI:

import RulesteadAdmin.Router

scope "/" do
  pipe_through :browser

  rulestead_admin "/admin/flags", policy: MyApp.RulesteadPolicy
end

The host contract is intentionally narrow: provide the required policy: module, the documented session keys, and preserve the canonical ?env= selector. The package-local details are in ../../rulestead_admin/README.md.

5. Continue from here