Your first container

You have installed Kontena. This page takes you from an empty container list to something running, and then shows you where its logs, shell and details live.

Connect an engine#

The first time Kontena starts it opens a full-window wizard: Let's connect your container engine. It scans your machine, lists the container engines it found, and you pick the one to start with. Engines that are installed but not running are listed too, marked Not running, so a stopped Docker reads as stopped rather than as absent.

Found nothing? The wizard links to a guided Podman install. Kontena needs an engine underneath it — it manages containers, it does not run them itself.

You are not locked in. The backend switcher in the top bar swaps engines — and clusters — at any time, and Settings › Engines decides which backend Kontena opens on next launch.

Run something#

The Containers page opens empty on a fresh engine, with quick-start templates in the empty state. Either pick one of those or open the Run dialog yourself.

1. Choose an image. Type a reference like nginx:alpine. If the image is not on your machine, Kontena pulls it as part of running — you do not need to pull first.
2. Name it. Optional; the engine generates one if you leave it empty. A name you will recognise in a week is worth the five seconds.
3. Publish a port. Ports the image declares are pre-filled from its metadata — map container 80 to host 8080 and you can reach it at localhost:8080.
4. Add what it needs. Environment variables, volumes, a network, a restart policy. For popular images (postgres, mysql, mariadb, mongo, redis, rabbitmq, nginx, …) a recipe fills in the variables the image requires but never documents in its metadata. A required variable left empty blocks Run and says which one.
5. Check the preview, then run. The dialog shows the equivalent command line as you edit, so you can see exactly what is about to happen — and paste it into a terminal later if you want to.

The container appears in the list as it is created. The list is event-driven: it reflects what the engine reports, as it happens, without polling.

Pulling from a registry that wants an account first? Add the login under Settings › Registries, where the password goes into your operating system's keychain. That one login covers both directions — the same credential is what pushing an image back uses, so there is nothing further to configure when you start publishing your own.

Look inside it#

Open the container from the list for its detail page:

That last one is the quickest way to check your first container actually works — run nginx:alpine with 80 mapped to 8080, open Inspect, click the port.

Clean up#

Stop halts the container and keeps it, so you can start it again with the same settings. Remove deletes it. Neither touches the image, so running it again does not re-download anything. The Containers page can also prune everything stopped in one go.

Where next#

Edit this page on GitHub