Getting Started

Copy Markdown View Source

This is the first-success path for the current 0.1.0 package line: 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.

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