Eve Deploy and Debug

Use these steps to deploy and diagnose app issues quickly.

Environment Setup

• Get the staging API URL from your admin.

• Create and use a profile:

eve profile create staging --api-url https://api.eh1.incept5.dev eve profile use staging

Infrastructure Change Policy

Never run kubectl apply , helm install , or any direct Kubernetes resource creation against shared infrastructure. All infrastructure changes go through Terraform. Use the Eve CLI (eve env , eve env deploy ) to manage application deployments — the platform handles the underlying k8s resources.

Deploy Flow (Staging)

Create env if needed

eve env create staging --project proj_xxx --type persistent

Deploy (requires --ref with 40-char SHA or a ref resolved against --repo-dir)

eve env deploy staging --ref main --repo-dir .

When environment has a pipeline configured, the above triggers the pipeline.

Use --direct to bypass pipeline and deploy directly:

eve env deploy staging --ref main --repo-dir . --direct

Pass inputs to pipeline:

eve env deploy staging --ref main --repo-dir . --inputs '{"key":"value"}'

Deploy Polling Flow

When eve env deploy is called:

• Direct deploy (no pipeline): Returns deployment_status directly. Poll health endpoint until ready === true .

• Pipeline deploy: Returns pipeline_run_id . Poll GET /pipelines/{name}/runs/{id} until all steps complete, then check health.

Deploy is complete when: ready === true AND active_pipeline_run === null .

Observe the Deploy

eve job list --phase active eve job follow <job-id> # Real-time SSE streaming eve job watch <job-id> # Poll-based status updates eve job diagnose <job-id> # Full diagnostic eve job result <job-id> # Final result eve job runner-logs <job-id> # Raw worker logs

Real-Time Debugging (3-Terminal Approach)

Terminal 1: Pipeline/job progress

eve job follow <job-id>

Terminal 2: Environment health

eve env diagnose <project> <env>

Terminal 3: System-level logs

eve system logs

Debugging Workflows

Job Won't Start

• Check dependencies: eve job dep list <job-id>

• Check if blocked: eve job show <job-id> → look at blocked_by

• Verify environment readiness: eve env show <project> <env>

• Check orchestrator: eve system orchestrator status

Job Failed

• Get the error: eve job diagnose <job-id>

• Check logs: eve job follow <job-id> or eve job runner-logs <job-id>

• If build failure: eve build diagnose <build-id>

• If secret failure: eve secrets list --project <project_id>

Job Stuck Active

• Check if waiting for input: eve job show <job-id> → effective_phase

• Check thread messages: eve thread messages <thread-id>

• Check runner pod: eve system pods

System Issues

• API health: eve system health

• Orchestrator: eve system orchestrator status

• Recent events: eve system events

Common Error Messages

Error Cause Fix

401 Unauthorized

Token expired eve auth login

git clone failed

Missing credentials Set github_token or ssh_key secret

service not provisioned

Environment not created eve env create <env>

image pull backoff

Registry auth failed If using BYO/custom registry, verify REGISTRY_USERNAME

• REGISTRY_PASSWORD ; for managed apps use registry: "eve"

healthcheck timeout

App not starting Check app logs, verify ports in manifest

Build Failures

If a deploy pipeline fails at the build step:

eve build list --project <project_id> eve build diagnose <build_id> eve build logs <build_id> eve secrets list --project <project_id> # Required for BYO/custom registry: REGISTRY_USERNAME, REGISTRY_PASSWORD

Common build failures:

• Registry auth: For BYO/custom registry, verify REGISTRY_USERNAME and REGISTRY_PASSWORD secrets

• Dockerfile not found: Check build.context path in manifest

• Multi-stage build failure: BuildKit handles these correctly; Kaniko may have issues

• Workspace errors: Build context not available — check eve build diagnose

Worker Image Registry

Eve publishes worker images to the configured private registry with these variants:

Variant Contents

base

Node.js, git, standard CLI tools

python

Base + Python runtime

rust

Base + Rust toolchain

java

Base + JDK

kotlin

Base + Kotlin compiler

full

All runtimes combined

Version pinning: Use semver tags (e.g., v1.2.3 ) in production. Use SHA tags or :latest in development.

Platform Environment Variables

Eve automatically injects these into every deployed service container:

Variable Purpose

EVE_API_URL

Internal cluster URL for server-to-server calls

EVE_PUBLIC_API_URL

Public ingress URL for browser-facing apps (when configured)

EVE_SSO_URL

SSO broker URL for user authentication (when configured)

EVE_PROJECT_ID

Current project ID

EVE_ORG_ID

Current organization ID

EVE_ENV_NAME

Current environment name

Use EVE_API_URL for backend calls. Use EVE_PUBLIC_API_URL for browser/client-side code. Services can override any of these by defining them explicitly in their manifest environment section.

Access URLs

• URL pattern: {service}.{orgSlug}-{projectSlug}-{env}.{domain}

• Local dev default domain: lvh.me

• Ask the admin for the correct domain (staging vs production).

Environment-Specific Debugging

Environment How to Debug

Local (k3d) Direct service access via ingress, eve system logs

Docker Compose docker compose logs <service> , dev-only (no production use)

Kubernetes Ingress-based access, kubectl -n eve logs as last resort

Workspace Janitor

Production disk management for agent workspaces:

• EVE_WORKSPACE_MAX_GB — total workspace budget

• EVE_WORKSPACE_MIN_FREE_GB — trigger cleanup threshold

• EVE_SESSION_TTL_HOURS — auto-evict stale sessions

• LRU eviction when approaching budget; TTL cleanup for idle sessions

• K8s: per-attempt PVCs deleted on completion

Related Skills

• Local dev loop: eve-local-dev-loop

• Secrets: eve-auth-and-secrets

• Manifest changes: eve-manifest-authoring