Ports & configuration

The PORT contract

Phelix sets the PORT environment variable. Applications managed by Phelix should listen on the port provided by PORT rather than hardcoding a port.

phelix build api --port 4000

This starts your application with PORT=4000, so it should listen on :4000. If the process runs but nothing listens on the requested port, Phelix reports a port-validation failure and suggests phelix doctor.

port := os.Getenv("PORT")if port == "" {    port = "3000"} log.Fatal(http.ListenAndServe(":"+port, router))

Three port concepts

With blue-green deployment, each instance receives its own PORT; the proxy owns the single public port. A failed new deployment never touches the currently active instance.

Project configuration

phelix.yaml is the project-level Phelix configuration file, stored in the current project directory. It removes the need to repeat the application name, port, health checks, and deployment strategy on every command. phelix init detects the project type (Go/Rust) and generates it:

# Phelix project configuration.# CLI flags override these values (e.g. --port).name: my-appport: 8080watching: disablehealth:    endpoints:        - name: default          path: /health          interval: 10s          retries: 3          mode: autodeploy:    strategy: classic

An example combining health checks, blue-green deployment, and Git webhooks:

name: apiport: 3000watching: enable health:  endpoints:    - name: readiness      path: /ready      interval: 5s      retries: 3      mode: http     - name: liveness      path: /health      interval: 10s      retries: 3      mode: auto deploy:  strategy: blue-green webhook:  enabled: true  branch: main  secret_env: PHELIX_WEBHOOK_SECRET

The configuration file is fully optional. Projects without phelix.yaml keep working exactly as before - every existing flag and prompt is unchanged.

Field reference

Resolution order

phelix build (and the other project-aware commands) resolve values in this order:

CLI argument/flag  →  phelix.yaml  →  Phelix default  →  interactive prompt

With the full example above, running phelix build resolves automatically - no prompts:

Application: apiPort:        3000

Partial configurations work: a file with only name: prompts for the port (in a TTY) or uses the default 8080; a file with only port: prompts for the name. No file at all means today's behavior (prompt or explicit args).

Explicit flags always win:

phelix build --port 8080        # uses port 8080 even though the config says 3000phelix build my-custom-name     # uses my-custom-name even though the config has a name

Health endpoints

Endpoints declared in phelix.yaml are applied to the app's persisted health configuration on every phelix build / phelix rebuild, so:

• phelix health list <app> and phelix health status <app> show them.
• Zero-downtime deploys use the first endpoint's path/mode as the deploy health tier (same as phelix health set).
• The phelix health set/add/remove commands keep working: a health: block in the config replaces the persisted endpoints at the next build/rebuild, while apps without a health: block keep whatever was set via the commands.

Deployment strategies

deploy.strategy selects which existing deployment path phelix rebuild uses - it does not introduce a new deployment system.

deploy:  strategy: classic          # normal stop → rebuild → start

deploy:  strategy: blue-green       # zero-downtime blue-green (same as --blue-green)

deploy:  strategy: rolling          # zero-downtime rolling (same as --replicas N)  replicas: 3

deploy:  strategy: canary           # one-shot canary share, then promotion  rollout:    canary: 5%               # traffic share for the canary (default 10%)    duration: 2m             # verification window before promotion (default 30s)

deploy:  strategy: progressive      # step-by-step traffic increase  rollout:    steps:      - traffic: 5%        duration: 2m      - traffic: 25%        duration: 5m      - traffic: 50%        duration: 5m      - traffic: 100%        # the final promotion step (required)    verification:      interval: 5s           # health/metrics poll cadence (default 5s)      max_error_rate: 5      # absolute canary error-rate cap, percent (default 5)      max_error_delta: 2     # canary minus baseline, percentage points (default 2)      max_p95_factor: 3      # canary p95 at most N × baseline p95 (default 3)

The rollout behavior behind canary and progressive is documented in Canary & progressive rollouts.

Explicit flags still override the config (--blue-green, --replicas, --canary, --port), and --strategy overrides it for a single rebuild without editing the file - the same one-off override the dashboard sends for a remote rebuild.

When nothing names a strategy, a rebuild keeps the one the app is already deployed with (from deploy.json) instead of falling back to classic: demoting a live blue-green/rolling app tears its instances down and drops its deployment state, so it has to be asked for - strategy: classic here, or --strategy classic for one rebuild. A rollout runs on the blue-green topology, so an app whose last deploy was canary/progressive inherits blue-green when nothing names a strategy; put strategy: canary or progressive in phelix.yaml to make rollouts the app's default.

phelix rollback needs no configuration: it inspects the recorded deploy state and automatically uses classic or zero-downtime rollback to match how the app was actually deployed. phelix proxy is required for blue-green/rolling/canary, exactly as with the flags.

Validation

The configuration is validated before it can affect a build or deploy - an invalid file fails the command with a CONFIGURATION_ERROR instead of being ignored:

Configuration error: invalid deploy.strategy "foobar"Hint: expected one of: classic, blue-green, rolling, canary, progressive

Validated: YAML syntax, port range, strategy name, replicas (≥ 1, rolling only), endpoint names (required, unique), paths (must start with /), durations (10s, 1m, ...), modes (auto, http, tcp-only, none), and the rollout plan: traffic percentages (whole numbers, 25 or "25%"), each step within 1-100, strictly increasing shares ending at the 100% promotion, non-negative durations, canary within 1-99, and verification thresholds (positive interval, error rates within 0-100, p95 factor ≥ 1).

phelix init

Detects the project type (Go/Rust) and creates phelix.yaml with the application name, port, watching: disable, a default health endpoint, and the classic deploy strategy. Prompts interactively in a TTY; fully scriptable with flags. Never modifies application source code. If a hardcoded listen port is detected, prints a warning and points to phelix doctor.

phelix init --name api --port 3000 --yes

phelix doctor

Diagnoses whether the current project is Phelix-compatible: project detection, toolchain, build tools, phelix.yaml, and - most importantly - whether the application listens on PORT instead of a hardcoded port.

$ phelix doctor Phelix Doctor ✓ Project detected        go (/home/me/api)✓ go toolchain            go1.27 linux/amd64✓ Build tools             ready✓ phelix.yaml             found✓ Application name        api✓ Configured port         4000✗ PORT configuration      hardcoded :3000 Summary:  6 passed  1 failed

Exits non-zero when a critical check fails. Inconclusive detection (no listener found, no PORT usage) is reported as a warning, not a false failure. Diagnostic only - never rewrites source code.