Skip to main content

How to Deploy Applications

PhariaOS manages the lifecycle of “usecases”, which are full-stack, end-to-end AI applications. Each application exposes the necessary REST endpoints so AI skills can be consumed and, optionally, a custom user interface (UI) to interact with the implemented workflows.

PhariaOS relies on Kubernetes (K8s) to deploy usecases as K8s resources (a deployment with pod(s)). In order to trigger a deployment with PhariaOS, you need to provide your containerized application in a registry that is accessible by the credentials provided to PhariaOS during installation.

The PhariaOS API enables you to register a usecase and manage the lifecycle of usecase deployments. Alternatively, you can use the Pharia AI CLI, which calls to the PhariaOS API.

Creating a PhariaOS Usecase​

To register a new usecase using the PhariaOS API, make a POST request to the endpoint demonstrated in this example, with your user token provided as a Bearer token.

Example usecase POST request:

info

The name must be unique across this installation of PhariaOS. Any conflict will receive response status code 409 (Conflict).

curl --request POST \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases' \
  --header 'Authorization: Bearer <token>'
  --header 'Content-Type: application/json' \
  --data '{
  "description": "description of your usecase application",
  "name": "name of your usecase application"
}'

If the registration is successful, the response will indicate status code 201 (Created) and provide the usecase application UUID in the response body “id” field.

Example usecase POST response:

{
  "id": "ee7ab86f-bfde-450f-bb0e-1433e91a8d90",
  "name": "name of your usecase application",
  "description": "description of your usecase application",
  "createdAt": "2025-02-05T11:26:11Z",
  "deployment": null
}

The “deployment” field will be null until a successful deployment is triggered. After a successful deployment, the “deployment” field will include details of the latest request that resulted in a non-error.

Deploying a PhariaOS Usecase​

To deploy a usecase, you must provide the registry where the container image is located and the tag (version) of the image. The endpoint for deploying includes the target usecase application ID as a path parameter, as demonstrated below with additional configuration parameters.

Example usecase deployment POST request:

curl --request POST \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/deployments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
 "config": {
  "image": {
   "registry": "your.container.registry.de",
   "repository": "your/repository",
   "tag": "1.0.0"
  }
 }
}'

An accepted deployment request will return status code 202 (Accepted) and the deployment ID.

Example usecase deployment POST response:

{
  "id": "d132cff5-cfed-4f94-8133-50e37bda6b95"
}

Once triggered, the deployment follows this lifecycle. At any time, there will be at most one active deployment (status: deployed) of a usecase. All K8s resources associated with requests listed as superseded, undeployed, or error are cleaned from the cluster.

IMage
The Usecase deployment state flow.

The deployment ID can be used to request the status of a prior deployment request, including any errors encountered during deployment.

Example usecase deployment GET request:

curl --request GET \
  --url https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/deployments/d132cff5-cfed-4f94-8133-50e37bda6b95 \
  --header 'Authorization: Bearer <token>'

Example usecase deployment GET response:

{
  "id": "d132cff5-cfed-4f94-8133-50e37bda6b95",
  "status": "deployed",
  "createdAt": "2025-02-05T11:37:06Z",
  "message": ""
}

When the status is “error”, the “message” field will contain details about the failure.

Undeploying a PhariaOS Usecase​

To undeploy a running usecase, the usecase must be in the “deployed” state.

Example usecase deployment DELETE request:

curl --request DELETE \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/deployments \
  --header 'Authorization: Bearer <token>'

PhariaOS API Documentation​

For more information on usecase deployment tracking, troubleshooting, and other features provided by PhariaOS API, see the documentation at https://pharia-os-manager.<your.pharia-ai.domain.com>/redocs.

Consuming a PhariaOS Usecase​

The PhariaOS Applications Proxy enables you to access deployed usecase applications.

info

By default, the PhariaOS Applications Proxy is available at https://pharia-os-applications.<your.pharia-ai.domain.com>.

The request must begin with the application ID and is followed by the destination request endpoint provided by the application itself. For example, let’s assume your usecase exposes the execute endpoint. Then, you can call your usecase with the following request.

Example Applications Proxy POST request:

curl --request POST \
  --url 'https://pharia-os-applications.<your.pharia-ai.domain.com>/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/execute' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "question": "what is your favorite color?"
}'

A valid request and resource path will return the expected resource in the response.

If the request path does not resolve to an available application, the response status code will be 502 (BadGateway).

warning

The PhariaOS Applications Proxy server handles Cross-Origin Resource Sharing (CORS) requests. It is important that no application implements CORS policies when the Proxy is enabled, as this can result in duplicated CORS headers and CORS errors.

Deployed Application Monitoring​

Expose Metrics Endpoint​

Ensure that your application backend exposes the /metrics endpoint. This allows Prometheus to scrape and collect metrics effectively from your deployed applications.

Deploy Application with Monitoring Enabled​

If usecase monitoring is enabled in the PhariaOS configuration you can also provide the following in the “config” for your usecase deployment.

"config": {
  ...,
  "serviceMonitor": {
    "enabled": true,
    "scrapingInterval": "5s"
  }
}