Tugtainer is a self-hosted app for automating updates of your docker containers

Please be aware that the application is distributed as-is and is not recommended for use in a production environment.

And don't forget about regular backups of important data.

Automatic updates are disabled by default. You can enable only what you need.

Table of contents:

• main features
• deploy
• private registries
• custom labels
• notifications
• auth
• api
• env
• check and update
• screenshots
• contributing

Main features:

• Web UI with authentication
• Multiple hosts support
• Socket proxy support
• Crontab scheduling
• Notifications to a wide range of services
• Per-container config (check only or auto-update)
• Automatic/manual check and update
• Automatic/manual image pruning
• Linked containers support (compose and custom)
• Private registries support
• Basic container control (start, stop, etc.)
• Container detailed info (inspect, logs)

Deploy:

• Quick start

  Use docker-compose.app.yml or the following docker commands.

  # create volume
  docker volume create tugtainer_data
  
  # pull image
  docker pull ghcr.io/quenary/tugtainer:1
  
  # run container
  # AGENT_SECRET is required. Set a strong, unique shared secret.
  docker run -d -p 9412:80 \
      --name=tugtainer \
      --restart=unless-stopped \
      -e AGENT_SECRET="" \
      -v tugtainer_data:/tugtainer \
      -v /var/run/docker.sock:/var/run/docker.sock:ro \
      ghcr.io/quenary/tugtainer:1

Important

Keep in mind that you cannot update an agent or a socket-proxy from within the app because they are used to communicate with the Docker CLI. Avoid including these containers in a docker-compose that contains other containers you want to update automatically, as this will result in an error during the update. To keep them updated, you can activate "check" only to receive notifications, and recreate them manually or from another tool, such as Portainer.

• Remote hosts

  [!IMPORTANT] Agent host URLs that resolve to private or reserved networks are blocked by default (SSRF protection). If your remote agent is on a LAN or Docker network, allow it on the primary instance via AGENT_ALLOW_NETWORKS (e.g. 192.168.0.0/24) and/or AGENT_ALLOW_ENDPOINTS (e.g. 10.0.0.5:9413). See .env.example for details. By default, only the built-in agent endpoint 127.0.0.1:8001 is allowed when AGENT_ENABLED=true.

  To manage remote hosts from one UI, you have to deploy the Tugtainer Agent. To do so, you can use docker-compose.agent.yml or the following docker commands.

  After deploying the agent, in the UI follow Menu -> Hosts, and add it with the respective parameters. The Agent secret field should match the AGENT_SECRET you've provided for the agent container.

  Backend and agent use HTTP to communicate, so you can use a reverse proxy for HTTPS.

  # pull image
  docker pull ghcr.io/quenary/tugtainer-agent:1
  
  # run container
  # AGENT_SECRET is required. Set a strong, unique shared secret.
  docker run -d -p 9413:8001 \
      --name=tugtainer-agent \
      --restart=unless-stopped \
      -e AGENT_SECRET="" \
      -v /var/run/docker.sock:/var/run/docker.sock:ro \
      ghcr.io/quenary/tugtainer-agent:1

• Socket proxy

  You can use Tugtainer and Tugtainer Agent without mounting the Docker socket directly.

  docker-compose.app.yml and docker-compose.agent.yml use this approach by default.

  Manual setup:

  • Deploy socket-proxy e.g. https://hub.docker.com/r/linuxserver/socket-proxy
  • Enable at least CONTAINERS, IMAGES, POST, INFO, PING for the check feature, and NETWORKS for the update feature;
  • Set the env var DOCKER_HOST="tcp://my-socket-proxy:port" on the Tugtainer(-agent) container(s);

Private registries

To use private registries, you have to mount docker config to Tugtainer or Tugtainer Agent, depending on where the container with the private image is located.

• Create the config using one of the methods on the host machine
  • Log into the registry docker login <registry>
  • Manually

    {
      "auths": {
        "<registry>": {
          "auth": "base64 encoded 'username:password_or_token'"
        }
      }
    }

• Mount the config to the Tugtainer (Agent) as a read-only volume -v $HOME/.docker/config.json:/root/.docker/config.json:ro or in a docker-compose file.
• That's all you need to do, Docker CLI will take care of the rest.

Custom labels:

• dev.quenary.tugtainer.protected=true

  This label indicates that the container cannot be stopped. This means that even if there is a new image for the container, it cannot be updated from the app. This label is primarily used for tugtainer itself and tugtainer-agent, as well as for socket-proxy in the provided docker-compose files.

• dev.quenary.tugtainer.depends_on="my_postgres,my_redis"

  This label is an alternative to the docker compose label. It allows you to declare that a container depends on another container, even if they are not in the same compose project. List of container names, separated by commas.

Hooks:

You can configure shell commands to run inside a container at points of the update lifecycle: pre_update, post_update, pre_stop, pre_rollback, post_rollback. Each command runs as sh -c "<command>" inside the target container via the agent.

Tugtainer has no built-in database/service-specific backup logic — writing the actual backup/notification commands (e.g. pg_dump) and managing where their output goes is entirely up to you.

This feature is off by default and requires two things to be true at once:

• ALLOW_HOOKS=true on the Tugtainer backend (feature gate — hides the UI form and stops the backend from ever calling the agent's exec endpoint when false).
• ALLOW_EXEC=true on the Tugtainer-Agent for the specific host you want to run hooks on (defense in depth — an agent that hasn't opted in refuses to execute commands even if asked).

Failure semantics:

• A failing pre_update or pre_stop hook aborts that container's update — the container is left running as-is, same as any other pre-flight check failure.
• post_update, pre_rollback and post_rollback hook failures are report-only (logged) and never block anything — by the time these run, either the update already succeeded or a rollback is already underway and must complete regardless.
• pre_rollback runs while the failed container is still alive, right before Tugtainer stops it to roll back.

The hooks form is hidden in the UI for protected containers (see Custom labels), since protected containers are never updated by the app.

Notifications:

The app uses Apprise to send notifications and Jinja2 to generate their content. You can view the documentation for each of them for more details.

Jinja2 custom filters:

• any_worthy - checks that at least one of the items has result equal to "available", "updated", "rolled_back" or "failed"

Jinja2 context schema:

{
  "hostname": "Tugtainer container hostname",
  "results": [
    {
      "host_id": 0,
      "host_name": "string",
      "items": [
        {
          "container": {
            "id": "string",
            "image": "string",
            "...other keys of 'docker container inspect' in snake_case": {},
          },
          "local_image": {
            "id": "string",
            "repo_digests": [
              "digest1",
              "digest2",
            ],
            "...other keys of 'docker image inspect' in snake_case": {},
          },
          "remote_image": {
            "...same schema as for local_image": {},
          },
          "local_digests": [
            "list of platform specific image digests",
          ],
          "remote_digests": [
            "list of platform specific image digests",
          ],
          "result": "not_available|available|available(notified)|updated|rolled_back|failed|None"
        }
      ],
      "prune_result": "string",
    }
  ]
}

"result" options:

• "not_available": No new image found.
• "available": New image available for the container.
• "available(notified)": New image available for the container, but it was in the previous notification. The app preserves digests of new images, so if another new image has appeared, the result will still be "available".
• "updated": Container successfully recreated with the new image.
• "rolled_back": The app failed to recreate the container, but was able to restore it with the old image.
• "failed": The app failed to recreate the container.

The notification is sent only if the body is not empty. For instance, if there are only containers with "available(notified)" results, the body will be empty (with the default template), and the notification will not be sent.

If you want to restore the default template, it's here

Auth

The app uses password authorization by default. The password is stored in a file in encrypted form.

Alternatively, you can use an OpenID Connect provider instead of a password.

Auth cookies are not domain-specific and not HTTPS-only. All of this can be configured using env variables.

API

The backend API is served under the /api base path.

• Swagger UI: /api/docs
• Redoc UI: /api/redoc

Public endpoints

• GET /api/public/health
• GET /api/public/version
• GET /api/public/summary (requires ENABLE_PUBLIC_API=true)
• GET /api/public/update_count (requires ENABLE_PUBLIC_API=true)
• GET /api/public/is_update_available (requires ENABLE_PUBLIC_API=true)

Env:

Most environment variables are optional. AGENT_SECRET is required for backend-agent communication. See .env.example for a list of vars with descriptions.