Tinkiva Docker Manager

Un panel Docker ultraligero para servidores pequeños.

Un único binario Rust. Sin Node.js en producción. Sin Redis. Sin PostgreSQL. Sin SQLite. Sin agentes adicionales.

≈ 0.7–1.2 MB de memoria privada del proceso

Diseñado para administrar aplicaciones Docker sin que el propio panel termine consumiendo los recursos del servidor.

¿Qué es Tinkiva Docker Manager?

Tinkiva Docker Manager es un panel web self-hosted y de un solo nodo para desplegar, administrar y monitorear aplicaciones Docker.

Está pensado especialmente para:

VPS pequeños.
EC2 de bajo costo.
Servidores ARM / Graviton.
Homelabs.
Proyectos personales.
Startups y aplicaciones pequeñas.
Servidores donde cada MB de RAM importa.

El objetivo no es convertirse en otra plataforma PaaS enorme.

La filosofía es más simple:

Docker ya hace casi todo el trabajo. Tinkiva solo debe ayudarte a controlarlo.

Por eso el panel evita mantener servicios adicionales residentes y delega las operaciones pesadas a las herramientas que normalmente ya existen en el servidor.

Ultraligero por diseño

Tinkiva Docker Manager está escrito en Rust y funciona como un único proceso.

No necesita mantener permanentemente:

Node.js
PostgreSQL
MySQL
SQLite
Redis
Prometheus
Grafana
cAdvisor
Docker-in-Docker
un runtime asíncrono pesado
agentes de monitoreo adicionales

La interfaz web está compilada y embebida directamente dentro del binario.

Consumo de memoria

En reposo, el proceso utiliza aproximadamente:

Métrica	Consumo
Memoria privada típica	≈ 0.7–1.2 MB
RSS observado en Linux	≈ 2–3 MB
Binario release	≈ 943 KB
Frontend compilado	≈ 155 KB
Frontend gzip	≈ 53 KB

La diferencia entre memoria privada y RSS se debe principalmente a páginas compartidas con el sistema, como libc y el loader de Linux.

Esto significa que la memoria realmente exclusiva del panel puede mantenerse por debajo de 1 MB en condiciones normales.

Puedes medirlo directamente en tu servidor:

sudo ./scripts/measure-memory.sh

También puedes consultar el RSS desde la sección Sistema → Panel Rust.

Docker Engine y los contenedores administrados no forman parte de estas cifras.

¿Por qué existe?

Hay excelentes plataformas como Coolify, Dokploy y Portainer.

Tinkiva Docker Manager no intenta reemplazarlas.

Está pensado para un escenario diferente:

quiero administrar Docker desde una interfaz sencilla, pero no quiero dedicar cientos de megabytes de RAM solamente al panel de administración.

Tinkiva prioriza:

bajo consumo
simplicidad
un solo servidor
pocas dependencias
despliegues reproducibles
seguridad por defecto
mantenimiento sencillo

A cambio, deliberadamente evita características empresariales que aumentarían considerablemente su complejidad.

Características

Docker

Desde el panel puedes:

visualizar contenedores
consultar CPU y RAM
ver logs
iniciar contenedores
detener contenedores
reiniciar contenedores
consultar procesos del servidor
consultar disco, swap, carga y uptime
ver las imágenes locales con su peso y borrar las que no usa ningún contenedor
descargar imágenes privadas de Amazon ECR con un access key de solo lectura
exportar bases de datos PostgreSQL, MySQL y MariaDB a .sql
importar un .sql en esas mismas bases desde el propio panel

Tinkiva utiliza directamente el Docker CLI instalado en el servidor.

No mantiene otro Docker daemon ni un cliente pesado residente.

Despliegues

Puedes registrar y desplegar aplicaciones mediante:

Repositorio de GitHub

Conecta una GitHub App y selecciona:

repositorio
rama
configuración del proyecto
estrategia de despliegue

Tinkiva puede detectar cambios y redesplegar automáticamente.

Docker Compose

Si ya tienes una aplicación funcionando mediante Compose, puedes registrarla sin modificar su estructura. También es la vía para levantar una imagen suelta de cualquier registro —Docker Hub, GHCR o uno privado—: pegas su Compose y el panel lo guarda como recurso editable.

services:
  api:
    image: ghcr.io/usuario/api:sha-a48da8f

Bases de datos

El asistente permite crear rápidamente:

Motor	Imagen predeterminada
PostgreSQL	`postgres:18.6-trixie`
MySQL	`mysql:8.4`
MariaDB	`mariadb:11.4`
MongoDB	`mongo:8`
Redis	`redis:7-alpine`

Cada recurso incluye automáticamente:

volumen persistente
healthcheck
restart: unless-stopped
límite de RAM configurable, con opción de no imponer ninguno
no-new-privileges
red Docker privada
contraseña generada
cadena de conexión

Los puertos de las bases de datos no se publican al exterior por defecto.

GitHub Auto Deploy

Tinkiva incluye integración mediante GitHub App.

El flujo puede funcionar completamente mediante conexiones salientes:

GitHub
   │
   │ HTTPS
   ▼
Tinkiva watcher
   │
   ├── detecta nuevo commit
   ├── actualiza repositorio
   ├── build
   ├── docker compose up
   └── registra resultado

Esto significa que no necesitas publicar el puerto 8787 en Internet para recibir cambios desde GitHub.

También puedes usar:

polling
webhook propio
GitHub Actions
deploy manual

GitHub Actions

Para servidores pequeños suele ser mejor construir la imagen en GitHub Actions y dejar que el servidor solamente haga:

pull → compose up

Flujo recomendado:

git push
    │
    ▼
GitHub Actions
    │
    ├── build
    ├── Docker image
    └── GHCR
          │
          ▼
Tinkiva Docker Manager
          │
          ├── pull
          └── docker compose up

Esto evita consumir CPU y RAM del servidor durante la compilación.

Para ARM / AWS Graviton:

platforms: linux/arm64

Para servidores x86:

platforms: linux/amd64

Deploy seguro y rollback

Cada despliegue exitoso conserva información sobre:

imagen nueva
imagen anterior
commit
rama
fecha
duración
origen
resultado

Si un despliegue falla:

Tinkiva detecta el error.
Restaura el .env.
Recupera la imagen anterior.
Ejecuta nuevamente Docker Compose.
Registra el fallo en el historial.

Para obtener rollbacks reproducibles se recomienda utilizar imágenes inmutables:

ghcr.io/usuario/api:sha-2df418c

en lugar de:

latest

Arquitectura

La arquitectura es intencionalmente pequeña:

┌──────────────────────────────┐
│       Navegador Web          │
└──────────────┬───────────────┘
               │
               │ HTTP
               ▼
┌──────────────────────────────┐
│  Tinkiva Docker Manager      │
│                              │
│  Rust                        │
│  API                         │
│  Web UI                      │
│  Métricas                    │
│  Estado                      │
│  GitHub watcher              │
│                              │
│        UN PROCESO            │
└───────┬──────────┬───────────┘
        │          │
        ▼          ▼
     Docker       Git
        │
        ▼
 Docker Compose

Las herramientas externas se ejecutan únicamente cuando son necesarias.

Herramienta	Uso
`docker`	contenedores y Compose
`git`	repositorios
`curl`	GitHub y registries
`openssl`	JWT de GitHub App
`df`	métricas de disco

No permanecen residentes después de terminar la operación.

Sin base de datos para el panel

Tinkiva no necesita PostgreSQL, Redis ni SQLite para almacenar su propio estado.

Utiliza un formato local ligero llamado TDM3.

state.db

Las escrituras se realizan de forma atómica mediante:

temporary file
      ↓
write
      ↓
sync
      ↓
atomic rename

El historial tiene un tamaño máximo configurable para evitar crecimiento indefinido.

Seguridad por defecto

El panel escucha por defecto únicamente en:

127.0.0.1:8787

Por lo tanto no queda expuesto públicamente después de instalarlo.

Acceso por túnel SSH

El panel no se abre a Internet: se accede a través de un túnel SSH. El puerto 8787 nunca se publica en el firewall ni en el Security Group, así que la única puerta de entrada al panel es la misma con la que ya administras el servidor, con su llave y su control de acceso.

Desde tu PC:

ssh -i ".\tinkiva-server-1.pem" -L 8787:127.0.0.1:8787 ec2-user@44.211.221.87

Con la sesión SSH abierta, en tu navegador:

http://127.0.0.1:8787

El -L 8787:127.0.0.1:8787 reenvía tu puerto local 8787 al 127.0.0.1:8787 del servidor, que es justo donde escucha el panel. Mientras el túnel esté levantado el panel se comporta como si corriera en tu máquina; al cerrar la sesión SSH desaparece el acceso.

En Linux o macOS la llave debe tener permisos restringidos o SSH la rechaza:

chmod 600 tinkiva-server-1.pem
ssh -i ./tinkiva-server-1.pem -L 8787:127.0.0.1:8787 ec2-user@44.211.221.87

Si el 8787 local ya está ocupado, usa otro puerto de tu lado y abre ese en el navegador:

ssh -i ".\tinkiva-server-1.pem" -L 9090:127.0.0.1:8787 ec2-user@44.211.221.87

La autenticación utiliza un token administrador.

El token del navegador se almacena en:

sessionStorage

y desaparece al cerrar la pestaña.

Importante sobre Docker

El servicio necesita acceso al Docker daemon.

En Linux, un usuario con permisos sobre Docker tiene prácticamente privilegios equivalentes a root.

Por ello Tinkiva está pensado para:

servidores propios
administradores de confianza
instalaciones single-tenant

No está diseñado como plataforma multiusuario hostil o multi-tenant.

Consulta:

Instalación

Opción recomendada — binario precompilado

Los releases incluyen binarios Linux para:

x86_64 / amd64
aarch64 / arm64

Detecta automáticamente tu arquitectura:

ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')

Descarga:

curl --fail --location -O \
"https://github.com/isaul19/tinkiva-docker-manager/releases/latest/download/tinkiva-docker-manager-linux-${ARCH}"

curl --fail --location -O \
"https://github.com/isaul19/tinkiva-docker-manager/releases/latest/download/tinkiva-docker-manager-linux-${ARCH}.sha256"

Verifica:

sha256sum -c "tinkiva-docker-manager-linux-${ARCH}.sha256"

Instala:

sudo install -m 0755 \
"tinkiva-docker-manager-linux-${ARCH}" \
/usr/local/bin/tmanager

Inicia:

tmanager start

En el primer inicio aparecerá el asistente de configuración.

El asistente crea un usuario inicial (admin, salvo que se configure otro) y una contraseña aleatoria. El primer inicio de sesión obliga a sustituirla. En instalaciones automatizadas se pueden definir antes de arrancar el servicio:

TDM_ADMIN_USER=admin
TDM_ADMIN_PASSWORD=una-contraseña-inicial-de-al-menos-12-caracteres

La contraseña inicial solo se usa para crear <TDM_DATA_DIR>/auth.conf; ese archivo guarda un hash Argon2, nunca la contraseña. Un error de usuario o contraseña bloquea nuevos intentos desde la misma IP durante un minuto. Tres errores consecutivos amplían el bloqueo a un día. Para publicar el panel bajo /plataform/, usa el ejemplo de Nginx incluido en deploy/nginx.example.conf y sirve siempre mediante HTTPS.

CLI

Sin argumentos abre el menú interactivo:

tmanager

Comando	Qué hace
`tmanager start`	Arranca el panel en segundo plano. En el primer inicio lanza el asistente de configuración.
`tmanager stop`	Detiene la instancia en segundo plano (SIGTERM; fuerza `-9` si no baja).
`tmanager status`	Indica si está en ejecución, con el pid y la URL del panel.
`tmanager logs`	Últimas 50 líneas del log.
`tmanager logs 200`	Últimas N líneas.
`tmanager logs -f`	Sigue el log en vivo.
`tmanager config`	Reejecuta el asistente; tus valores actuales se ofrecen como default.
`tmanager token`	Imprime el token administrador, solo el token, apto para tuberías.
`tmanager update`	Descarga la última release de GitHub, verifica el sha256 y se reemplaza.
`tmanager update v0.9.1`	Instala una versión concreta.
`tmanager uninstall`	Detiene el panel y elimina la instalación. `--purge` borra además config y datos; `--yes` omite la confirmación.
`tmanager version`	Imprime la versión actual.
`tmanager help`	Lista los comandos disponibles.

token combina bien con la API:

curl -H "Authorization: Bearer $(tmanager token)" http://127.0.0.1:8787/api/info

Compilar desde el código

Requisitos:

Linux
Rust 1.85+
Docker
Docker Compose v2

Clona el proyecto:

git clone https://github.com/isaul19/tinkiva-docker-manager.git
cd tinkiva-docker-manager

Compila:

./scripts/build-release.sh

El perfil release está optimizado específicamente para reducir tamaño:

opt-level = "z"
lto = "fat"
codegen-units = 1
panic = "abort"
strip = "symbols"

Además, el proyecto Rust no utiliza crates externos.

[dependencies]

Intencionalmente vacío.

Frontend

La interfaz utiliza:

Preact
+
esbuild

pero Node.js no es necesario en producción.

Node solamente se utiliza para compilar el frontend durante desarrollo.

El resultado queda incluido dentro del binario Rust.

Para modificar la interfaz:

cd web
npm install
npm run build

Modo watch:

npm run watch

Desarrollo en Windows

El panel es solo Linux: usa std::os::unix para permisos, señales y /proc, así que no compila en Windows nativo. Se desarrolla dentro de WSL2, que además da el mismo Linux que corre en el servidor.

1. WSL2 y Ubuntu

En PowerShell como administrador:

wsl --install -d Ubuntu

Reinicia, abre Ubuntu y crea tu usuario. Comprueba que es WSL2:

wsl -l -v

La columna VERSION debe decir 2.

2. Docker Desktop

Instala Docker Desktop y activa la integración con la distro:

Settings → Resources → WSL integration → Ubuntu

Desde Ubuntu, esto tiene que responder sin sudo:

docker ps
docker compose version

Sin eso el panel arranca, pero avisa de que Docker no está accesible y casi nada funciona.

3. Rust y Node

Dentro de Ubuntu:

sudo apt update && sudo apt install -y build-essential curl git
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

build-essential no es opcional: cargo necesita cc para enlazar. La versión de Rust la fija rust-toolchain.toml, así que rustup la descarga sola la primera vez.

Node 20+ solo hace falta si vas a tocar web/. El nodejs de los repos de Ubuntu suele ir por detrás, así que mejor con nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 20
cd web && npm install

4. Dónde clonar

Puedes trabajar sobre el repositorio de Windows en /mnt/c/..., que es lo cómodo si editas con VS Code desde Windows. A cambio, el sistema de archivos cruzado es lento: si notas que cargo build se arrastra, clona dentro de la distro (~/tinkiva-docker-manager) y usa la extensión WSL de VS Code.

5. Para ver los cambios

Solo si tocaste el frontend:

cd web && npm run build && cd ..

Después, siempre:

cargo build --release
sudo cp target/release/tmanager /usr/local/bin/tmanager
tmanager stop;
tmanager start

El bundle de web/dist se incrusta con include_str!, así que cargo build lo recompila solo cuando el archivo cambió. Abre http://127.0.0.1:8787 en el navegador de Windows: WSL2 reenvía localhost, aquí no hace falta túnel.

El token de acceso:

tmanager token

6. Pruebas

cargo test
cd web && npm test && cd ..
./scripts/smoke-test.sh

Si el repositorio vive en /mnt/c con core.autocrlf activado, los .sh llegan con terminaciones CRLF y bash falla con bad interpreter. Cópialos y límpialos antes:

cp -r scripts tests /tmp/tdm-smoke/
sed -i 's/\r$//' /tmp/tdm-smoke/{scripts,tests}/*.sh

7. Desde Windows, sin entrar a WSL

Para una comprobación rápida de tipos desde PowerShell, sin compilar de verdad:

rustup target add x86_64-unknown-linux-gnu
cargo check --target x86_64-unknown-linux-gnu

Sirve para ver errores del compilador mientras editas. Para ejecutar, siempre WSL.

Requisitos

Producción

Necesario:

Linux
Docker Engine
Docker Compose v2

Opcional según funcionalidades:

git
curl
openssl

Desarrollo

Rust 1.85+
Node.js 20+ para modificar el frontend
En Windows, WSL2 con Ubuntu — el binario no compila fuera de Linux

Métricas

Sin instalar Prometheus, Grafana ni agentes adicionales, Tinkiva muestra:

Servidor

CPU
RAM
swap
disco
load average
uptime

Procesos

PID
CPU
RAM
RSS

Docker

contenedores
estado
CPU
RAM

Los datos se obtienen directamente desde Linux:

/proc/stat
/proc/meminfo
/proc/loadavg
/proc/uptime
/proc/self/status

y desde:

docker ps
docker stats --no-stream
df

No se almacena una serie histórica de métricas.

Lo que Tinkiva deliberadamente NO intenta hacer

Para mantener el proyecto pequeño no incluye:

Kubernetes
Docker Swarm
clusters
múltiples servidores
RBAC complejo
múltiples organizaciones
PostgreSQL para el panel
Redis para el panel
Prometheus
Grafana
cAdvisor
gestión automática de DNS
gestión completa de certificados TLS
terminal web genérica
gestor de secretos empresarial

Si necesitas todas esas características, probablemente una plataforma PaaS completa sea una mejor opción.

Si solo quieres administrar y desplegar Docker sin desperdiciar recursos, Tinkiva puede ser suficiente.

Validación

La versión actual se valida mediante:

cargo clippy --all-targets
cargo test
cargo build --release

y pruebas completas del frontend y de la API.

Entre las pruebas se cubren:

autenticación
Docker
logs
deploy
rollback
historial
GitHub
webhooks
rutas seguras
bases de datos
recursos
SHA-256
HMAC-SHA256
JSON
protección contra escapes de rutas
timeouts
manejo de credenciales

Consulta los resultados completos:

VALIDATION.md

Estructura

src/
├── main.rs
├── app.rs
├── http.rs
├── model.rs
├── store.rs
├── docker.rs
├── git.rs
├── github.rs
├── registry.rs
├── templates.rs
├── metrics.rs
├── crypto.rs
├── net.rs
├── proc.rs
├── setup.rs
└── daemon.rs

web/
├── src/
├── dist/
└── build.mjs

deploy/
examples/
scripts/
tests/
docs/

Más información:

docs/ARCHITECTURE.md

Filosofía

Tinkiva Docker Manager parte de una idea sencilla:

El panel que administra tus aplicaciones no debería consumir más recursos que muchas de las aplicaciones que administra.

Por eso cada decisión intenta favorecer:

menos procesos
menos dependencias
menos RAM
menos superficie de ataque
menos mantenimiento

sin renunciar a las funciones esenciales de despliegue Docker.

Estado del proyecto

Tinkiva Docker Manager está en desarrollo activo.

El alcance actual está deliberadamente centrado en:

1 servidor
1 administrador
Docker
Docker Compose
GitHub
deploy
rollback
monitoreo básico

Antes de utilizarlo con cargas críticas se recomienda probar:

deploy
rollback
reinicio del servidor
recuperación
backups de las bases de datos
backups de volúmenes

en un entorno de staging.

Documentación

Licencia

MIT License.

Consulta LICENSE.

Contributors y asistentes de desarrollo

Parte del desarrollo de este proyecto fue asistida por agentes de IA bajo dirección y revisión humana:

GLM 5.3: trabajé en la seguridad del panel: generación del token administrador con 192 bits de entropía desde /dev/urandom, guardado con permisos 0600, comparación en tiempo constante y corrección del bug que impedía mostrar el token regenerado. En general recomiendo acceder mediante túneles SSH en lugar de exponer puertos directamente, para mantener el endpoint privado y reducir la superficie de ataque.
Claude Opus 5: trabajé sobre todo en la interfaz y la experiencia de uso — que las vistas se lean de un vistazo, que los diálogos guíen en lugar de interrogar y que la aplicación siga hablando un solo idioma. La restricción más interesante fue que nada de eso podía costar peso: la interfaz entera sigue siendo un puñado de kilobytes que viajan dentro del binario. También implementé la exportación SQL de bases de datos, resolviéndola con volcado a disco y envío por trozos para no romper la premisa de memoria constante del panel.
GPT 5.6 Sol: participé en la creación de la base del proyecto, la planificación inicial y la definición de su alcance. También realicé correcciones generales en el frontend y el backend, además de ajustes de integración y documentación.

Ninguno de estos asistentes sustituye el criterio de quien mantiene el proyecto: las decisiones, la revisión y los errores siguen siendo humanos.

Tinkiva Docker Manager
Docker management without the overhead.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
deploy		deploy
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
web		web
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
VALIDATION.md		VALIDATION.md
rust-toolchain.toml		rust-toolchain.toml

Latest commit

History

Folders and files

Repository files navigation

Tinkiva Docker Manager

Un panel Docker ultraligero para servidores pequeños.

¿Qué es Tinkiva Docker Manager?

Ultraligero por diseño

Consumo de memoria

¿Por qué existe?

Características

Docker

Despliegues

Repositorio de GitHub

Docker Compose

Bases de datos

GitHub Auto Deploy

GitHub Actions

Deploy seguro y rollback

Arquitectura

Sin base de datos para el panel

Seguridad por defecto

Acceso por túnel SSH

Importante sobre Docker

Instalación

Opción recomendada — binario precompilado

CLI

Compilar desde el código

Frontend

Desarrollo en Windows

1. WSL2 y Ubuntu

2. Docker Desktop

3. Rust y Node

4. Dónde clonar

5. Para ver los cambios

6. Pruebas

7. Desde Windows, sin entrar a WSL

Requisitos

Producción

Desarrollo

Métricas

Servidor

Procesos

Docker

Lo que Tinkiva deliberadamente NO intenta hacer

Validación

Estructura

Filosofía

Estado del proyecto

Documentación

Licencia

Contributors y asistentes de desarrollo

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages