Docker

Docker daemon on the VPS and apps as Compose projects: image, private registry, repo or Compose, with optional HTTPS.

Category: Servers and infrastructure
Status: Available
Requirements: An active VPS with the docker feature available (Ubuntu 22.04 has it); At least 256 MB of free RAM and 1 GB of free disk, as measured; Being a member with access to the VPS to install; admin to uninstall
MCP tools (Read only): ver_catalogo_apps, ver_preflight_app, listar_apps_empresa, ver_app, ver_operacion_app
MCP tools (Write or modify): instalar_app, controlar_app, reintentar_operacion_app, refrescar_apps
MCP tools (Destructive): desinstalar_app

What can you do with it?

Docker on ArduMaker has two parts: the daemon, which is a capability of the VPS, and Docker apps, each one its own Compose project that the platform writes, starts, observes and removes.

Install the daemon in one click (or let the first app that needs it install it).
Deploy a public image, an image from a private registry with a token, or a GitHub repo with a Dockerfile.
Deploy an advanced Compose (as a JSON object) with several services.
Start, stop and restart the project, and publish it with HTTPS if it exposes a web port.
From the VPS Docker tab: list containers, see their logs, stop, restart or delete them, and see images, volumes and networks.

When should you use it?

An application already packaged as an image (a dashboard, an internal tool, a third-party service).
Several services started together with Compose.
For your own GitHub code with a non-Docker process, GitHub deploy is the better fit.

How does it work in ArduMaker?

The daemon

New VPS are born with the container permissions Docker needs, without being privileged. An older VPS that lacks them gets them when Docker is installed and needs a restart (the preflight warns with requiere_reinicio_vps). The daemon is installed with the docker.io package and fuse-overlayfs, with userns-remap enabled: container processes do not run as the VPS's real root.

A Docker app

The configuration and the preflight are validated (system feature, Docker possible on the host, memory and disk).
If the daemon is missing it is installed; if another installation is in progress, the operation waits and is retried.
/opt/ardumaker-apps/app<id>/docker-compose.yml is written (keeping a copy of the previous one) and validated with docker compose config; if it does not validate, the previous one is restored.
docker compose -p app<id> up -d --remove-orphans runs as a long step, so a heavy pull does not time out.
If there is a port, it is published with HTTPS and the link is verified.

Every container carries the ardumaker.app_id label and the project is named app<id>: the name is not chosen by the user and the platform never touches anything outside it. Redeploying is idempotent: the same file and up -d do not recreate what did not change.

What actually changes?

What	Where
Compose file	`/opt/ardumaker-apps/app<id>/docker-compose.yml`
Cloned code (repo mode)	`/opt/ardumaker-apps/app<id>/src`
Data with relative path	`/opt/ardumaker-apps/app<id>/datos`
Named volumes	Owned by the project (`data<i>` in simple mode)
Private registry token	Encrypted on the platform; the VPS runs `docker login` with the token on stdin

Docker app configuration

Mode	Keys
Image	`image`, `port`, `container_port`, `env` (hasta 50), `volumes`, `health_path`, `registry`
GitHub repo	`repo_id`, `branch`, `port`, `container_port`, `env`, `volumes`, `health_path`
Advanced Compose	`compose` (JSON object, not YAML) and optional `port`

image, compose and repo_id are mutually exclusive.
port is the VPS port (from 1024 and never a protected one); with port, container_port is required. "auto" picks a free one.
Ports are published only on 127.0.0.1: a container is never directly open to the internet.
env does not accept secret-like names (*_PASSWORD, *_TOKEN…): the configuration does not store secrets.

What a Compose rejects

Each service accepts an allowlist of keys (image, command, entrypoint, environment, ports, volumes, restart, depends_on, healthcheck, working_dir, user, expose, networks, mem_limit, cpus, labels, tmpfs, stop_grace_period, read_only, init). Rejections come with a code per path (compose.services.<service>.<key>):

Code	What triggers it
`privileged`	`privileged`, `devices`, `security_opt`, `userns_mode`
`network_mode_host`	`network_mode: host`
`pid_host`	Host `pid` or `ipc`
`cap_add`	Extra capabilities
`docker_socket`	Mounting `docker.sock`, `/run` or `/var/run`
`host_mount`	Absolute paths, `~` or `..` (only `./something` inside its own folder)
`puerto_publico`	Any port other than `127.0.0.1:H:C`

build, container_name, env_file, configs, secrets, extends and name are not accepted either, nor com.docker.* or ardumaker.* labels.

Uninstalling and data

Uninstalling runs docker compose down --remove-orphans, force-removes the containers labelled with the project and deletes the Compose file. Volumes and the ./datos folder stay, unless data deletion is requested: then down -v runs and the project folder is deleted. Nothing outside app<id> is touched.

Diagram

Internet: HTTPS on docker-<id> or a custom domain
VPS nginx: domain server block
`127.0.0.1:<port>`: only port published by the container
Compose project `app<id>`: containers labelled ardumaker.app_id
Volumes: persist until data deletion is requested

A published Docker app — Without port there is no URL: the app is managed from the Docker tab.

Expected result

The app shows in Apps with its observed state: running if all its containers run, stopped if all are stopped, degraded if mixed and missing if none is left. With port, the HTTPS URL appears only after the link answered without a 5xx error.

docker compose -p app<id> ps
docker ps --filter label=com.docker.compose.project=app<id>

Errors and troubleshooting

Error	Cause	Retry?
`requiere_docker`	The host does not support Docker	No
`requiere_reinicio_vps`	Container permissions are missing and the VPS must restart	After restarting
`recursos_insuficientes`	Less than 256 MB RAM or 1 GB disk free	After freeing resources
`docker_instalandose` / `docker_no_instalado`	The daemon is being installed or could not start	Yes
`compose_no_disponible` / `despliegue_fallido` / `baja_fallida`	Compose could not be prepared, pull or start failed, or `down` did not finish	Yes (`up -d` and `down` are idempotent)
`compose_invalido`	`docker compose config` rejected the file; the previous one was restored	No, it must be fixed
`puerto_ocupado`	Another app on the VPS publishes or declares that port	With another port
`config_invalida`	Disallowed key or secret in `env`; `fields` says which	After fixing the request

MCP access

Docker apps are operated over MCP with the Apps tools; the reference is at /mcp/docs and /mcp/servicios.

Read: ver_catalogo_apps, ver_preflight_app (validates the exact config before installing), listar_apps_empresa, ver_app, ver_operacion_app.
Modify: instalar_app with app_type: docker (requires idempotency_key), controlar_app (start, stop, restart), reintentar_operacion_app, refrescar_apps.
Destructive: desinstalar_app (admins only, confirm=true; volumes are deleted only with delete_data and confirm_delete_data).