Preparing Container Images

Prepare, build, and push an agent container image for hosted deployments.

Use the guidelines in this topic for preparing Docker images.

Supported Container Image Architecture

For images, the Generative AI service supports 64-bit x86 architecture, code name amd64. When building container images, use linux/amd64 as the platform type.

For example,

docker buildx build --platform linux/amd64 -t myimage:latest

Code Preparation

The Docker container must meet the following requirements to run in the Hosted Deployment environment.

Host and port

The container must listen on host 0.0.0.0.
The container must listen on port 8080.

HTTP response content type

The container must expose an HTTP-based service that implements REST-style request and response endpoints using methods such as GET, PUT, POST, DELETE, and PATCH with user-defined paths.

The platform decides whether a request expects a streaming response by inspecting the Accept header.

If the Accept header includes text/event-stream, the endpoint must return a Server-Sent Events (SSE) response with content type text/event-stream.
Otherwise, the endpoint must return a standard JSON response with content type application/json.

This setup supports an endpoint for both streaming and non-streaming interactions in a consistent and backward-compatible manner.

Readiness Endpoint

The Docker container must expose a readiness endpoint to verify that the application is fully initialized and ready to handle requests.

Path: /ready
Purpose: Indicates whether the container is ready to receive traffic
Response Format: HTTP status code only
Content Type: application/json
Success Status Code: 200 OK (application is ready)

If the container isn't ready, the endpoint must return a non-200 status code to prevent traffic routing.

Liveness Endpoint

The Docker container must expose a liveness endpoint to verify that the application is running correctly and doesn't require a restart.

Path: /health
Purpose: Detects whether the container is alive and functioning
Response Format: HTTP status code only
Content Type: application/json
Success Status Code: 200 OK (application is healthy)

If the application enters a deadlock or unrecoverable state, the endpoint must return a non-200 status code so the platform can restart the container automatically.

Image Architecture

The service supports amd64.

Note

We recommend that you to use base images provided by Oracle Container Registry. The images on that site pass vulnerability scanning.

Reserved environment variables

The following environment variables are reserved for system use. Don't define them in the container code:

PORT
K_SERVICE
K_CONFIGURATION
K_REVISION
OCI_RESOURCE_PRINCIPAL_VERSION
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM
OCI_RESOURCE_PRINCIPAL_RPST
KUBERNETES_*

Image Architecture

The image must be built for the linux/amd64 platform, as shown in the following example.

File access

The container file system is read-only, except for the /tmp directory, which is writable. If your application needs to write files locally, write them to /tmp.

Other restrictions

Custom entry point commands aren't supported. Define the entry command in the Docker file by using CMD or ENTRYPOINT.
Volume mapping isn't supported. Containers must be stateless, because local file data isn't preserved during redeployment or node replacement.

Project Structure

project_directory/
├── main.py # Your main agent code
├── requirements.txt # Dependencies for your agent
├── Dockerfile # Dockerfile for building the image
├── .dockerignore # Files not included in the image
└── __init__.py # Makes the directory a Python package

Build Container Image

The following example shows a Dockerfile in the project directory.

Dockerfile

FROM container-registry.oracle.com/os/oraclelinux:9-slim

ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

WORKDIR /app

RUN microdnf update -y && \
    microdnf install -y \
      python3.11 \
      python3.11-pip \
      ca-certificates \
      iputils \
      shadow-utils \
    && microdnf clean all \
    && rm -rf /var/cache/dnf /var/cache/yum

COPY requirements.txt .
RUN python3.11 -m pip install --no-cache-dir --upgrade pip setuptools wheel && \
    python3.11 -m pip install --no-cache-dir -r requirements.txt

COPY . .

RUN useradd --create-home --uid 1000 appuser && chown -R appuser:appuser /app

USER appuser

EXPOSE 8080

CMD ["python3.11", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Build the Docker image for the linux/amd64 platform.

docker buildx build --platform linux/amd64 -t my_agent:v1 .

Push Image to Registry

Create a container registry. See Overview of Container Registry.

Use docker CLI to push docker images to the container registry.

Step 1: Sign in to container registry Example code:

docker login kix.ocir.io

Step 2: Tag the image using container registry URL and namespace. Example code:

docker tag my_agent:v1 ap-osaka-1.ocir.io/{your_tenancy_namespace}/my_agent:v1

Step 3: Push image Example code:

docker push ap-osaka-1.ocir.io/<your_tenancy_namespace>/my_agent:v1

Oracle Cloud Infrastructure Documentation