Skip to main content

API

The Phobos API is a unified binary that includes both the API server and the web UI. It can be run locally or via Docker.

Docker images​

The recommended way to run Phobos is using the provided Docker images. Three images are published to the GitLab container registry:

ImageDescription
phobos-api/phobosUnified API + UI server
phobos-api/agentAgent for executing jobs
phobos-api/job-executorJob executor used by agents
tip

Use the provided Docker Compose setup to get started quickly.

Build from source​

Requirements​

Git clone the project to the local machine
git clone https://gitlab.com/infor-cloud/martian-cloud/phobos/phobos-api.git

Build the unified binary (API + UI)​

Build the Phobos binary with the embedded UI
cd <project-directory>
make build-phobos

This builds the frontend, embeds it into the Go binary, and produces the apiserver executable.

Build the API-only binary (no UI)​

Build the API binary without the UI
cd <project-directory>
make build-api

This uses the noui build tag to skip embedding the frontend.

Build Docker images​

Build the unified Phobos Docker image
make build-phobos-docker
Build the agent Docker image
make build-agent-docker
Build the job executor Docker image
make build-job-executor-docker

Database setup​

Start the PostgreSQL database
make db-start
Run database migrations
make migrate

Environment variables​

Admin​

PHOBOS_ADMIN_USER_EMAIL​

Email for the default API admin user.

PHOBOS_ADMIN_USER_PASSWORD​

Password for the default API admin user.

Database​

PHOBOS_DB_USERNAME​

The username for the PostgreSQL database.

PHOBOS_DB_NAME​

Name of the PostgreSQL database.

PHOBOS_DB_PASSWORD​

The password for the PostgreSQL database.

PHOBOS_DB_HOST​

Host address for the database.

PHOBOS_DB_PORT​

Port number for the database.

PHOBOS_DB_SSL_MODE​

SSL mode for the database connection.

PHOBOS_DB_MAX_CONNECTIONS​

Maximum number of database connections.

PHOBOS_DB_AUTO_MIGRATE_ENABLED​

Automatically run database migrations on startup.

Default: true

Authentication​

Phobos supports two authentication modes:

  • External OIDC provider — Uses PHOBOS_OAUTH_PROVIDERS_* to configure an external identity provider (e.g. Keycloak, Okta). This is the mode used in production deployments and the full-stack Docker Compose setup.
  • Built-in identity provider — Uses PHOBOS_ADMIN_USER_EMAIL and PHOBOS_ADMIN_USER_PASSWORD to create a local admin user. No external OIDC provider is needed. This is the mode used by the default Docker Compose setup.

OIDC

PHOBOS_OAUTH_PROVIDERS_0_ISSUER_URL​

Configured OIDC provider's issuer URL.

PHOBOS_OAUTH_PROVIDERS_0_CLIENT_ID​

Client ID for identity provider.

PHOBOS_OAUTH_PROVIDERS_0_USERNAME_CLAIM​

Supported username claim.

Default: sub

PHOBOS_OAUTH_PROVIDERS_0_SCOPE​

OAuth scopes used by the Phobos UI.

PHOBOS_OIDC_INTERNAL_IDENTITY_PROVIDER_CLIENT_ID​

Client ID for the internal OIDC identity provider.

Default: phobos

PHOBOS_TOKEN_ISSUER_URL​

Issuer URL for Phobos service account tokens. Defaults to the API URL.

PHOBOS_ASYMMETRIC_SIGNING_KEY_ROTATION_PERIOD_DAYS​

Number of days after which an asymmetric signing key should be rotated. Set to 0 to disable rotation.

Default: 0

PHOBOS_ASYMMETRIC_SIGNING_KEY_DECOMMISSION_PERIOD_DAYS​

Number of days after which a rotated asymmetric signing key should be decommissioned.

Default: 7

User sessions

PHOBOS_USER_SESSION_ACCESS_TOKEN_EXPIRATION_MINUTES​

Access token expiration time in minutes.

Default: 5

PHOBOS_USER_SESSION_REFRESH_TOKEN_EXPIRATION_MINUTES​

Refresh token expiration time in minutes.

Default: 720

PHOBOS_USER_SESSION_MAX_SESSIONS_PER_USER​

Maximum concurrent sessions per user.

Default: 20

Server​

PHOBOS_API_URL​

External URL where the Phobos API is accessible.

Default: http://localhost:9000

PHOBOS_UI_URL​

External URL for the Phobos UI. Defaults to the API URL.

PHOBOS_SUPPORT_URL​

URL to display for support links.

PHOBOS_HTTP_SERVER_PORT​

HTTP server port.

Default: 9000

PHOBOS_GRPC_SERVER_PORT​

gRPC server port.

Default: 9010

PHOBOS_EXTERNAL_GRPC_PORT​

External gRPC port when using a reverse proxy. Defaults to the gRPC server port.

PHOBOS_TLS_ENABLED​

Enable TLS for the API server.

Default: false

PHOBOS_TLS_CERT_FILE​

Path to the TLS certificate file.

PHOBOS_TLS_KEY_FILE​

Path to the TLS key file.

PHOBOS_CORS_ALLOWED_ORIGINS​

Comma-delimited list of allowed CORS origins. Defaults to the UI URL.

PHOBOS_HTTP_RATE_LIMIT​

HTTP requests per second allowed by the rate limiter.

Default: 60

PHOBOS_MAX_GRAPHQL_COMPLEXITY​

Maximum allowed GraphQL query complexity.

Default: 0 (unlimited)

PHOBOS_ASYNC_TASK_TIMEOUT​

Timeout in seconds for async background tasks.

Default: 100

PHOBOS_TEMPLATE_MAX_UPLOAD_SIZE​

Maximum upload size in bytes for pipeline templates.

Default: 131072

PHOBOS_PLUGIN_BINARY_MAX_UPLOAD_SIZE​

Maximum upload size in bytes for plugin binaries.

Default: 1073741824

Object store​

Configures where Phobos stores objects (pipeline templates, release artifacts, etc.):

  • aws_s3 — Amazon S3 or an S3-compatible service (e.g. Minio).

PHOBOS_OBJECT_STORE_PLUGIN_TYPE​

Object store plugin type: aws_s3.

aws_s3

PHOBOS_OBJECT_STORE_PLUGIN_DATA_BUCKET​

Name of the bucket where objects will be stored.

PHOBOS_OBJECT_STORE_PLUGIN_DATA_REGION​

Region where the object store is hosted.

PHOBOS_OBJECT_STORE_PLUGIN_DATA_AWS_ACCESS_KEY_ID​

AWS access key ID used to access the object store.

PHOBOS_OBJECT_STORE_PLUGIN_DATA_AWS_SECRET_ACCESS_KEY​

AWS secret access key used to access the object store.

PHOBOS_OBJECT_STORE_PLUGIN_DATA_ENDPOINT​

Custom endpoint URL (e.g. for Minio).

JWS provider​

Configures how JSON Web Signatures are generated for service account tokens:

  • memory — In-memory key generation. Suitable for development and single-instance deployments.
  • awskms — AWS Key Management Service. Recommended for production.

PHOBOS_JWS_PROVIDER_PLUGIN_TYPE​

JWS provider plugin type: memory or awskms.

Default: memory

awskms

PHOBOS_JWS_PROVIDER_PLUGIN_DATA_REGION​

AWS region where the KMS key is hosted. Required.

PHOBOS_JWS_PROVIDER_PLUGIN_DATA_KEY_SPEC​

KMS key spec (e.g. RSA_4096). Optional.

PHOBOS_JWS_PROVIDER_PLUGIN_DATA_ALIAS_PREFIX​

Prefix for the KMS key alias. Optional.

PHOBOS_JWS_PROVIDER_PLUGIN_DATA_TAGS​

Comma-separated key=value tags for the KMS key. Optional.

Job execution​

PHOBOS_INTERNAL_AGENTS_0_NAME​

Name of the internal agent.

PHOBOS_INTERNAL_AGENTS_0_JOB_DISPATCHER_TYPE​

Job dispatcher type: local, docker, kubernetes, or ecs.

PHOBOS_INTERNAL_AGENTS_0_JOB_DISPATCHER_DATA_*​

Key-value configuration for the job dispatcher plugin.

Observability​

PHOBOS_OTEL_TRACE_ENABLED​

Enable OpenTelemetry tracing.

Default: false

PHOBOS_OTEL_TRACE_TYPE​

Type of tracing exporter: otlp or xray.

PHOBOS_OTEL_TRACE_HOST​

Host to send trace data to.

PHOBOS_OTEL_TRACE_PORT​

Port to send trace data to.

Rate limiting​

Configures the backing store for API rate limiting:

  • memory — In-memory store. Suitable for single-instance deployments.
  • redis — Redis-backed store. Recommended for multi-instance deployments.

PHOBOS_RATE_LIMIT_STORE_PLUGIN_TYPE​

Rate limit store plugin type: memory or redis.

Default: memory

redis

PHOBOS_RATE_LIMIT_STORE_PLUGIN_DATA_REDIS_ENDPOINT​

Redis connection URL.

Email​

Configures the email provider for sending notifications:

  • smtp — Standard SMTP server.
  • ses — Amazon Simple Email Service.
  • plunk — Plunk email API.
  • empty — Disabled (no emails sent).

PHOBOS_EMAIL_CLIENT_PLUGIN_TYPE​

Email client plugin type: smtp, ses, plunk, or empty (disabled).

Footer text for emails sent by Phobos.

smtp

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_SMTP_HOST​

SMTP server hostname.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_SMTP_PORT​

SMTP server port.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_FROM_ADDRESS​

Sender email address.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_SMTP_USERNAME​

SMTP authentication username.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_SMTP_PASSWORD​

SMTP authentication password.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_DISABLE_TLS​

Disable TLS for the SMTP connection.

Default: false

ses

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_FROM_ADDRESS​

Sender email address.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_AWS_CONFIGURATION_SET_NAME​

AWS SES configuration set name.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_REGION​

AWS region for SES.

plunk

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_ENDPOINT​

Plunk API endpoint.

PHOBOS_EMAIL_CLIENT_PLUGIN_DATA_API_KEY​

Plunk API key.

Footer text for emails sent by Phobos.

Supported databases​

The Phobos API requires a database to store persistent information such as organizations, projects, users, etc. It currently supports PostgreSQL.

Open Telemetry (OTel) tracing​

The Phobos API supports Open Telemetry (OTel) tracing. To enable it, set the following environment variables:

PHOBOS_OTEL_TRACE_ENABLED​

Set to true to enable tracing.

PHOBOS_OTEL_TRACE_TYPE​

The tracing exporter type. Supported values are otlp and xray.

PHOBOS_OTEL_TRACE_HOST​

The hostname or IP address of the trace collector (e.g. localhost or jaeger).

PHOBOS_OTEL_TRACE_PORT​

The port of the trace collector (e.g. 4317 for OTLP gRPC).

Rate limit​

The Phobos API rate limits inbound HTTP requests for GraphQL queries and mutations. Environment variable PHOBOS_HTTP_RATE_LIMIT specifies the number of requests per second allowed by the rate limiter. The default is 60.

Resource limits​

The Phobos API limits the numbers of certain resources in order to avoid performance breakdown or other problems. The default values are intended to not be overly restrictive. The current active limit values can be seen via this GraphQL query:

Get the current resource limits
query {
  resourceLimits {
    id
    name
    value
  }
}

A specific limit's value can be modified via a GraphQL mutation similar to this:

Update a resource limit
mutation {
  updateResourceLimit(
    input: {
      name: "ResourceLimitAssignedManagedIdentitiesPerWorkspace"
      value: 45
    }
  ) {
    resourceLimit {
      id
      name
      value
    }
  }
}