Container Apps

This page explains what Container Apps mean in the kopernik.us API and how they relate to machines, templates, and runtime settings.

For endpoint and schema details, see the Container App API reference. For console workflow guidance, see the Container Apps console guide.

What a container app is

A Container App is a single-machine workload managed by the API.

It combines:

a backing machine
a container image
runtime configuration such as environment variables, ports, bind mounts, and restart policy
optional template-driven defaults

This gives you a simpler deployment model than Kubernetes while still exposing machine-level controls when you need them.

Resource relationship

Container Apps are built on top of Machines.

When you create a container app, the API:

provisions a machine
configures storage and networking
pulls the requested image
starts and monitors a Docker container on that machine

Because of this relationship, container apps inherit many machine concerns such as region selection, VPC placement, SSH keys, and attached storage.

Two creation modes

Container apps can be created in two main ways.

Custom image

Use a custom image when you want to define the runtime directly.

Typical inputs include:

containerImage
optional registry credentials
environment variables
port mappings
bind mounts
restart policy

Template-based

Use a template when you want a curated app definition with fewer raw inputs.

Templates can define:

the image identity
required and optional environment properties
default port mappings
the container paths that store persistent data, and the storage each should have
the machine capacity the app needs to run well

Template-based creation still requires containerImage in the request, and that image must match the template image.

A template’s machineRequirements guide the choice of a machine type towards one the app is at home on. They are not enforced: a request naming a machine type below them is accepted, and the app may not function properly on it.

Persistence and bind mounts

Container apps often need persistent data.

Examples:

MySQL data files
OpenSearch data directories
application state stored on disk

The API supports this by combining:

machine-attached block storage volumes
runtime bind mounts from host paths into container paths

A template’s dataPaths are recommendations, not enforced requirements: each names one container path the image stores data in, and minSizeGb the storage that path should have. If you omit them, state may remain on the machine root disk and may be lost when the app is deleted or replaced.

Logs and runtime state

Container apps expose:

current container state
human-readable container status
log streams for stdout and stderr

Log responses return gzip-compressed, base64-encoded chunks and support cursor-based incremental reads.

Lifecycle

Create and delete operations return actions. See Actions and asynchronous operations for the execution model.