Skip to content

Command Palette

Search for a command to run...

Version 1.2.0

Workspaces

Deploy a monorepo as one unit: build every service in dependency order, deploy them one at a time, and keep the whole mesh inspectable and recoverable.

What a workspace is

A monorepo usually means stitching a per-service build script together by hand: build the shared library first, then the services that use it, then deploy each one and hope nobody forgets a step. Workspace support makes the monorepo itself the deploy unit. One command builds every service, one command deploys them in dependency order, and one command shows the state of the whole mesh.

Phelix detects a workspace from the repository: a phelix.workspace.yaml at the root, a go.work file, or a Cargo workspace ([workspace] members in the root Cargo.toml). Each service inside it stays a normal Phelix application with its own phelix.yaml, so strategies, health checks, environment snapshots, and versioning work per service exactly as they do for a standalone app.

Declaring a workspace

A phelix.workspace.yaml at the repository root names the services and their depends_on edges. The dependency graph decides the order for every workspace command: services with no dependency build first, dependents after them. Services that rely only on Go workspace or Cargo workspace detection need no file at all; use phelix.workspace.yaml when you want to state the deployment order explicitly.

Run phelix doctor in the repository root to confirm the workspace is detected and every service resolves before the first build.

Build the whole workspace

Terminal
phelix build --all

phelix build --all --concurrency 4

phelix build --all --port-base 9000

--all builds the workspace instead of the single app in the current directory. Levels of the dependency graph build in sequence; the services inside one level build in parallel, bounded by --concurrency. A service whose phelix.yaml declares no port gets the next free port from --port-base upward. Each service records its own numbered version and Build Report, exactly like a standalone build.

Deploy in dependency order

Terminal
phelix deploy --all

phelix deploy --all --auto-rollback

phelix deploy --all --json

phelix deploy --all --build-timeout 45m

The deploy walks the depends_on graph and brings up one service at a time, so a backend is serving before the services that call it deploy against it. The first failure halts the whole mesh: services already deployed keep their new versions, services not yet reached keep theirs, and nothing downstream of the failure starts against a broken dependency. With --auto-rollback, the failing service is restored to its previous version before the halt, so the mesh stays serving while you investigate.

FlagDefaultPurpose
--allfalseWorkspace mode; deploy without --all prints help
--auto-rollbackfalseRestore the failing service's previous version, then halt
--build-timeout30mDeadline for one service's compiler invocation
--port-base8080First port assigned to services that declare none
--jsonfalseOne machine envelope for the whole run

One status table

Output
$ phelix status --workspace

WORKSPACE  3 services · 2 strategies

SERVICE   STATUS     VERSION   HEALTH      PORT   STRATEGY
api       active     v12       http ok     9000   blue-green
worker    active     v8        tcp ok      9001   classic
edge      active     v5        http ok     9002   rolling

phelix status --workspace prints one overview instead of one status call per app: the derived lifecycle status, current version, health state, port, and deploy strategy for every service in the mesh.

Roll everything back

Terminal
phelix rollback --all

A workspace rollback undoes the mesh in reverse dependency order, so dependents roll back before the services they call. Each service returns to its own previous version, not to one shared version number. The command is deliberately exclusive: it cannot be combined with --to, --list, --dry-run, --verify, or --request-key.