Tribes

Tribes is a Phoenix + Ash web app with built-in Nostr relay integration, cluster sync, and runtime plugin support.

Local development

Use just as the preferred local workflow interface:

devenv shell -- just help
devenv shell -- just test
devenv shell -- just check-assets

Test profiles:

• just test runs the default Tribes host tests with tribes_ui loaded and external plugin runtimes disabled.
• just test-no-ui runs the host tests against the lightweight test org.tribe-one.caps.ui@1 provider instead of tribes_ui.
• just test-with-plugins runs host tests with all configured plugins loaded, plugin migrations applied, and live metrics tests included. It expects local dev services, including VictoriaMetrics on 127.0.0.1:18428, to already be running. Plugin OTP children stay disabled in this host test profile; use plugin test <plugin-dir> or supertest for runtime behavior.

To start your Phoenix server:

• Run mix setup to install and setup dependencies
• Start Phoenix endpoint with mix phx.server or inside IEx with iex -S mix phx.server

Then visit localhost:4000.

Quality checks

• Main project checks:

  mix precommit
  

• Nix plugin validation checks (explicit, separate from mix precommit):

  nix-build default.nix -A pluginValidation
  nix-build nix/tests.nix
  

We keep Nix checks separate so the regular Elixir precommit flow stays fast and works in non-Nix contexts.

Plugin development

When developing an external plugin against a local tribes checkout, use the host-side plugin helper from inside the tribes devenv:

devenv shell -- plugin validate ../tribes-plugin-aether
devenv shell -- plugin test ../tribes-plugin-aether
devenv shell -- plugin precommit ../tribes-plugin-aether

The helper runs the plugin's own Mix commands inside the host dev environment, points the host plugin manager at the host manifest and built-in plugins, and reuses the host database/services. Treat plugin test as the normal external plugin test entrypoint; raw mix test in a plugin repo is guarded. Use mix raw_test / mix raw_precommit only for unusual manual debugging when the same host env and plugin-manager paths are set.

E2E tests

There is a Docker-based multi-node e2e suite driven by:

• compose.e2e.yaml
• scripts/run_e2e.sh
• scripts/e2e_runner.exs

Run the full suite with:

./scripts/run_e2e.sh

Requirements:

• Docker with docker compose
• Nix, if you want the script to build and load the e2e images for you

If you already have compatible images loaded locally, you can skip the Nix build step:

SKIP_BUILD=1 ./scripts/run_e2e.sh

The script starts three Postgres containers, migrates three Tribes nodes, boots the cluster, runs the HTTP/admin assertions, and then tears the environment down automatically.

See docs/E2E_TESTS.md for the detailed architecture and scenario coverage.

Plugin/Nix packaging

• default.nix is the primary packaging entrypoint for deployments.
• nix/plugins.nix is a helper library for plugin graph resolution/validation.
• plugins.json is a convenience source list for this repository.

See nix/README.md for full details and examples.

Deployment notes

A deployment can import default.nix and either:

1. Use this repo's plugins.json, or
2. Provide pluginConfigs directly from the deployment's own Nix config.

This allows operators to keep plugin pinning in their infra repo while reusing Tribes' validator/assembler.

Nix flake packages

flake.nix now exposes deployment-oriented packages:

• .#tribesRelease — host release (mixRelease)
• .#tribesWithPlugins — host release assembled with validated plugins
• .#dockerImage — OCI image tagged tribes:latest (with plugins)

Build/load images locally:

nix build .#dockerImage --no-link --print-out-paths
# then: docker load < <path>

Run Docker e2e:

scripts/run_e2e.sh

By default this runs the core three-node Tribes suite and then the ../tribes-plugin-supertest Docker suite. Use --without-supertest to run only the core suite.

Learn more

• Phoenix: https://www.phoenixframework.org/
• Phoenix guides: https://hexdocs.pm/phoenix/overview.html
• Plugin spec: docs/PLUGINS.md
• Roadmap: docs/ROADMAP.md
• Historical MVP execution snapshot: docs/stale/MVP_PLAN.md
• Historical MVP2 snapshot: docs/stale/MVP2.md