Container configuration

Prerequisites: Containerization guide

Container Configuration is Step 2 of the application submission wizard. Here you define the technical details of every container your application needs: resources, networking, environment variables, health checks, and storage.

There are two ways to do it: configure everything in the visual UI, or upload a Docker Compose file. Both methods produce identical results, and this page covers both.

Why this step exists

The platform needs precise, structured information about each container to generate valid Kubernetes resources. This step captures everything the manifest generator needs:

• What image to pull and from where
• What port to expose and whether it's public
• How much CPU and memory to allocate
• What environment variables to inject (and how to handle sensitive ones)
• How to health-check the container
• What persistent volumes to attach

Choosing a workflow

The workflows are equivalent. You can start in the UI, download the YAML, edit it, and re-upload it without losing any configuration.

UI workflow

Step 1: Open Container Configuration

Navigate to Step 2 of the submission wizard. You'll see an empty container panel with a + button.

Step 2: Add containers

Click the + button to add a new container. Each container appears as its own tab. Add one tab per service in your application.

Tip: Add your database container first, then your backend, then your frontend. This matches the recommended deployment order.

Step 3: Configure basic information

For each container tab, fill in:

Container Name

• Lowercase, alphanumeric, hyphens only
• Max 63 characters
• Must be unique within the application
• Examples: wordpress, api-backend, postgres-db

Purpose

• Frontend: user-facing web interface
• Backend: API or application server
• Database: data storage (MySQL, PostgreSQL, MongoDB, etc.)
• Cache: in-memory cache (Redis, Memcached)
• Message Queue: message broker (RabbitMQ, etc.)

Docker Image URL

• Full image reference with a specific tag
• Examples: nginx:1.27, postgres:16.4, myregistry.com/myapp:v2.1.0

Container Port

• The port your application listens on inside the container
• This is the internal port, not the host port
• Examples: 80, 3000, 5432, 6379

Protocol

• TCP: most applications (HTTP, database connections)
• UDP: streaming or specific use cases

Public Access

• true: the container is accessible from the internet via an Ingress and HTTPS URL
• false: the container is only reachable from other containers in the same namespace

Only one container per single-app submission should be public. Set databases and caches to private.

Step 4: Set resource limits

Memory Allocation (GB) Values are in gibibytes (GB). The minimum is 1; the form rejects values below 1.

CPU Allocation (decimal cores) 0.5 is half a core, 1 is one full core. The minimum is 0.5 (500 millicores); the form rejects values below 0.5.

Start conservatively and increase if needed. Over-allocating resources affects the pricing shown to business users: the Review step shows your aggregated GB (Base) and vCPU (Base) totals.

Step 5: Configure environment variables

Click Add Environment Variable to define each variable your container needs.

For each variable:

Type quick reference:

Step 6: Configure health checks

Expand Health Check and toggle it on. Health checks are strongly recommended for all public-facing containers.

See Health checks for type-specific guidance.

Step 7: Configure volumes

Expand Container Volumes and click Add Volume for each persistent storage requirement.

See Volumes and storage for sizing guidance.

Step 8: Reorder containers

Drag and drop the container tabs to set deployment order. Recommended order:

1. Databases and caches
2. Backend services
3. Frontend services

Step 9: Configure the AI Assistant (optional)

Each application has a permanent AI Assistant tab in the container configuration step, alongside your container tabs. The tab is always visible and cannot be removed. Its content is just the on/off toggle plus, when enabled, a small form for the skills source and advanced options.

• Leave the toggle off to ship a standard application with no AI Assistant. Nothing is added to your manifest or your bill.
• Switch the toggle on to opt into the platform-synthesized agent sidecar. The full agent service (env vars, volumes, healthcheck) is generated at deploy time; you only provide the minimum input on this tab.

See Magneto Agent / AI Assistant for the full field reference and how the synthesized sidecar interacts with your other containers.

Step 10: Download the configuration (recommended)

Before completing the wizard, click Docker Compose Download to export your configuration as a docker-compose.yml file. The file contains your full configuration with all x-clouve-* metadata and can be re-uploaded later to restore or modify the configuration. Keep it under version control in your repository.

YAML upload workflow

Step 1: Prepare your file

Create or obtain a clv-docker-compose.yml file following the format described in the Containerization guide. Validate it before uploading:

yamllint docker-compose.yml

Step 2: Upload

In the Container Configuration step, expand Docker Compose Upload. Either:

• Drag and drop your .yml or .yaml file onto the upload area, or
• Click Upload to browse for the file

Step 3: Review the import

After upload, the UI populates all container tabs from your file. Review each tab and check that:

• Container names match
• Environment variable types are correctly assigned
• Health check enabled/disabled state is correct
• Volume sizes are correct
• Resource limits look right

Step 4: Adjust if needed

If anything was imported incorrectly, edit it through the UI. Then download the updated YAML before continuing.

Round-trip fidelity

The platform guarantees round-trip fidelity: if you download a configuration, make no changes, and re-upload it, you get exactly the same configuration back. This applies to:

• All container fields
• Environment variable types
• Health check enabled/disabled state (uses strict equality: enabled: true means enabled, enabled: false means disabled, missing means disabled)
• Volume sizes and descriptions

Health check preservation detail:

UI: enabled ON  → Download → enabled: true  → Upload → UI: enabled ON  ✓
UI: enabled OFF → Download → enabled: false → Upload → UI: enabled OFF ✓
File missing enabled field            → Upload → UI: enabled OFF (safe default)

Auto-detection for existing Docker Compose files

If you upload a standard Docker Compose file without x-clouve-* metadata, the platform makes reasonable guesses:

Always review auto-detected values before submitting. They are starting points, not authoritative.

Field validation reference

Frequently asked questions

Can I use a plain Docker Compose file without x-clouve-* fields? Yes. The platform auto-detects basic configuration, but you should review and correct the imported values.

Do the x-clouve-* fields break regular docker-compose up? No. Extension fields (prefixed with x-) are part of the Docker Compose specification, and the standard docker-compose CLI silently ignores them.

What happens if I upload a file multiple times? Each upload fully replaces the current configuration. Download your current configuration first if you want to preserve it.

Can I mix UI edits with file uploads? Yes. Upload a file, edit through the UI, then download the updated YAML. The download always reflects the current UI state.

How do I delete a container? Click the X on the container tab. At least one container must remain.

Is there a limit on the number of containers? There is no hard limit, but consider resource costs and management complexity. Most applications use 2 to 5 containers.

Next steps

• Environment variables covers every variable type in detail
• Health checks covers health check patterns for different container types
• Volumes and storage covers volume sizing and mount path conventions
• Bundles covers multi-app marketplace listings