repository·main·Indexed 23 days ago
https://github.com/quenary/tugtainerA self-hosted application for automating the monitoring and updating of Docker containers with a web UI. Version 1.31.0 supports multiple hosts via agents, complex container dependency graphs, customizable update hooks, and notifications via Apprise and Jinja2. It includes a FastAPI backend with a public API and a dedicated agent for secure remote Docker access.
Tugtainer uses a hooks_executor to manage the lifecycle of shell commands during updates.
Key Components:
get_hooks_map(host_id, names): Retrieves a mapping of container names to their configured ContainerHooks from the database.run_hooks(client, container_name, hooks, hook_name): Executes the commands associated with a specific EHookName (e.g., PRE_UPDATE) sequentially using client.container.exec.Execution Logic:
run_hooks never raises an exception itself. Instead, it collects any exceptions raised by individual commands and returns them as a list[Exception].PRE_UPDATE hook fails) or simply report the error (for POST_UPDATE hooks).Container hooks allow you to run shell commands at specific points in a container's update or rollback lifecycle. The available hook types are:
pre_update: Before the update process begins.post_update: After the update process completes.pre_stop: Before the container is stopped.pre_rollback: Before the old container is restored during a rollback.post_rollback: After the old container is confirmed back up and running.Container update hooks (arbitrary shell commands run inside containers at specific lifecycle points) require two separate feature gates to be enabled:
ALLOW_HOOKS): A configuration flag on the Tugtainer backend. When false, the backend will not attempt to trigger hooks.ALLOW_EXEC): A configuration flag on the host agent. When false, the agent will refuse to execute shell commands inside containers via the /api/container/exec/ endpoint.Both must be true for hooks to actually run on a given host.
The hooks management panel in the container card is conditionally rendered based on the following criteria:
containersStore.hooksEnabled() must be true.protected (!containersStore.selected()?.protected).If these conditions are met, a new accordion panel labeled CONTAINERS.HOOKS.LABEL will appear.
Container update hooks allow you to run shell commands inside a container at specific points in its update lifecycle.
Hooks are categorized by the stage of the update process they target:
PRE_STOP: Runs before the container is stopped.PRE_UPDATE: Runs before the container is updated (if the container is part of the update plan).POST_UPDATE: Runs after a successful update and health check. Errors here are reported but do not change the update result.PRE_ROLLBACK: Runs when a container is unhealthy after an update, while the container is still running, before the rollback (stop/remove) begins. Errors here are reported but do not block the rollback.POST_ROLLBACK: Runs after a rollback is completed.PRE_STOP or PRE_UPDATE hook fails, the update process for that container is aborted. The container is not stopped or updated, and the error is added to the update plan's error list.POST_UPDATE or PRE_ROLLBACK hook fails, the error is logged and added to the error list, but the update/rollback process continues. This ensures that safety mechanisms (like rollbacks) are not blocked by hook failures.Tugtainer allows running shell commands inside a container at specific points in the update lifecycle. Commands are executed as sh -c "<command>" via the agent.
Available Hooks:
pre_update (Failure aborts the update)pre_stop (Failure aborts the update)post_update (Failure is report-only)pre_rollback (Failure is report-only)post_rollback (Failure is report-only)Security Requirements: This feature is disabled by default and requires two environment variables to be set:
ALLOW_HOOKS=true on the Tugtainer backend.ALLOW_EXEC=true on the Tugtainer-Agent for the specific host.The ContainerHooks schema allows you to define a list of shell commands to be executed inside a container at various stages of its update lifecycle. Each command is a raw shell string and is executed sequentially using sh -c "<command>".
Available Hook Points:
pre_update: Before the container is updated.post_update: After the container is updated.pre_stop: Before the container is stopped.pre_rollback: Before a rollback is performed.post_rollback: After a rollback is performed.Data Structure: In the database and API, hooks are represented as a dictionary where keys are the hook names and values are lists of command strings.
class ContainerHooks(BaseModel):
pre_update: list[str] = Field(default_factory=list)
post_update: list[str] = Field(default_factory=list)
pre_stop: list[str] = Field(default_factory=list)
pre_rollback: list[str] = Field(default_factory=list)
post_rollback: list[str] = Field(default_factory=list)The Tugtainer Backend uses the uv package manager for dependency management. Follow these steps to set up your local environment:
uv venv.source .venv/bin/activate.venv\scripts\activateuv sync --locked to install all locked dependencies.pre-commit install.uv venv
source .venv/bin/activate
uv sync --locked
pre-commit installYou can run the different components of the system using the following Python module commands:
python -m backend.devpython -m agent.devCtrl + Shift + B.python -m backend.dev
python -m agent.devTo use container update hooks (arbitrary shell commands run inside containers during the update lifecycle), you must enable two specific feature gates. Both must be set to true for hooks to execute on a host.
ALLOW_HOOKS environment variable to true. This enables the public API endpoints for managing hooks.ALLOW_EXEC configuration on the agent side. This allows the agent to execute arbitrary shell commands inside containers.By default, both are set to False for security.
.env.example file in the repository root.