# Container images

How kogut records a deploy when a container starts from a new image.

kogut records a deploy when a container of a service starts from a different image, such
as after `docker compose pull && docker compose up -d`, an automatic image update, or a
platform's redeploy button. It needs only the [agent](https://docs.kogut.dev/agent/installing/) on the host.

## What counts as a deploy

When a container runs an image id it did not run in the previous sample, kogut records a
deploy of the container's service. Compose containers are followed by Compose project and
service, so a container recreated under a new name is the same one, and replicas of one
Compose service make one deploy.

The deploy belongs to the service whose name is part of the container name, or to the
only service on the host. A container without a service, a restart, or a container
recreated from the same image records nothing. An image that changed while kogut was
stopped is not recorded.

## Version

The version is the image tag as written and the first 12 hex digits of the image digest,
such as `1.4.2@3f9c2e1aa0b1`, or `latest@3f9c2e1aa0b1` without a tag. The timeline shows
the deploy with source `agent` and the host it happened on.

## Deploys from CI

When CI announced a deploy of the service through the [API](https://docs.kogut.dev/deploys/api/) or
[GitHub](https://docs.kogut.dev/deploys/github/) in the 10 min before the agent sees the new image, kogut records
nothing more. When the announcement comes up to 10 min after, both deploys stay on the
timeline and only the announced one gets a [report](https://docs.kogut.dev/deploys/reports/).

The same image change seen on several hosts within 10 min is one deploy.

## Rollback hint

A deploy noticed from an image change is a [likely cause](https://docs.kogut.dev/incidents/correlation/)
like any other. Its evidence names the previous image:

> Deploy of api 1.4.3@4d2b9e81c0aa at 14:02, 5 min before the first failure\
> Previous image: `ghcr.io/acme/api@sha256:3f9c2e1aa0b1…`

To roll back, pin that reference in your Compose file or `docker run` command. An image
built on the host has no registry digest, so the line shows the image id.

The digest comes from `GET /images/{id}/json`, so a
[socket proxy](https://docs.kogut.dev/agent/permissions/#docker-socket-access) needs `IMAGES=1`. Without
it, the hint shows the image id.

> [!NOTE]
> Update agents first. Older agents do not report image ids, so kogut records no deploys
> from their hosts.