Cicada

Gestor de Docker con API REST para homelabs, escrito en Elixir. En desarrollo activo.

Descripción

Cicada es una herramienta de gestión de contenedores Docker a través de una API REST. Está diseñado para facilitar la administración de entornos homelab y eventualmente incluirá capacidades de CI/CD automatizado.

Estado actual: En desarrollo - Solo endpoints de lectura disponibles

Características actuales

• API REST para consultar información de Docker
• Endpoints disponibles:
  • GET /api/networks - Lista todas las redes de Docker
  • GET /api/images - Lista todas las imágenes de Docker
  • GET /api/containers - Lista todos los contenedores de Docker
  • GET /api/volumes - Lista todos los volumenes
• Respuestas en formato JSON
• Comunicación directa con Docker Engine API

Tecnologías

• Elixir - Lenguaje de programación
• Jason - Codificación y decodificación JSON
• Plug Cowboy - Servidor HTTP
• ex_docker_engine_api - Cliente para Docker Engine API
• TailwindCSS - TailwindCSS v4 para estilo del dashboard
• HTMX - HTMX para reactividad en el dashboard

Requisitos

• Elixir >= 1.14
• Docker instalado y en ejecución
• Acceso al socket de Docker (/var/run/docker.sock)

Instalación

# Clonar el repositorio
git clone https://github.com/jclumbiarres/cicada.git
cd cicada

# Instalar dependencias
mix deps.get

# Compilar el proyecto
mix compile

Configuración

Asegúrate de que Docker esté en ejecución y accesible. Por defecto, Cicada se conecta al socket local de Docker.

# config/config.exs
import Config

config :cicada,
  docker_host: "unix:///var/run/docker.sock",
  port: 4000

Uso

Iniciar el servidor

mix run --no-halt

El servidor estará disponible en http://localhost:3000

Roadmap

Versión actual (v0.1)

• Endpoint GET /networks
• Endpoint GET /images
• Endpoint GET /containers
• Endpoint GET /volumes
• Cache Endpoints
• Respuestas JSON
• Dashboard web (Eex + HTMX) (Soporte de tailwindcss v4 y HTMX añadido, pequeño dashboard creado)

Próximas versiones

• Endpoints POST/PUT/DELETE para gestión completa de recursos
• Gestión de volúmenes
• Gestión de Docker Compose
• Sistema de autenticación
• WebSockets para logs en tiempo real
• CI/CD automatizado
• Pipeline de despliegue
• Webhooks para integración con Git
• Monitorización y métricas
• Soporte k3s/k8s

Estructura del proyecto

cicada/
├── config
│   ├── api.exs
│   ├── cache.exs
│   ├── config.exs
│   ├── docker.exs
│   └── tesla.exs
├── css
│   └── main.css
├── lib
│   ├── cicada
│   │   ├── api
│   │   │   ├── handlers
│   │   │   │   └── dashboard
│   │   │   │       └── layout.html.eex
│   │   │   ├── middleware
│   │   │   │   └── logger.ex
│   │   │   ├── router.ex
│   │   │   ├── static
│   │   │   │   ├── htmx.min.js
│   │   │   │   └── main.css
│   │   │   └── templates
│   │   ├── application.ex
│   │   └── docker
│   │       ├── client
│   │       │   └── client.ex
│   │       ├── containers
│   │       │   ├── api.ex
│   │       │   ├── containers.ex
│   │       │   └── model.ex
│   │       ├── images
│   │       │   ├── api.ex
│   │       │   ├── images.ex
│   │       │   └── model.ex
│   │       ├── networks
│   │       │   ├── api.ex
│   │       │   ├── model.ex
│   │       │   └── networks.ex
│   │       ├── utils
│   │       │   └── utils.ex
│   │       └── volumes
│   │           ├── api.ex
│   │           ├── model.ex
│   │           └── volumes.ex
│   └── cicada.ex
├── LICENSE
├── mix.exs
├── mix.lock
├── package.json
├── package-lock.json
├── README.md
└── test
    ├── cicada_test.exs
    └── test_helper.exs

Desarrollo

Ejecutar tests

mix test

Formato de código

mix format

Análisis estático

mix dialyzer

Contribuir

Las contribuciones son bienvenidas. Para contribuir:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Realiza tus cambios y haz commit (git commit -am 'Añade nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

Por favor, asegúrate de que tu código:

• Sigue las convenciones de estilo de Elixir
• Incluye tests cuando sea aplicable
• Está documentado apropiadamente

Licencia

Este proyecto está licenciado bajo AGPLv3 - ver el archivo LICENSE para más detalles.

Autor

Juan Carlos Lumbiarres - @jclumbiarres

Estado del proyecto

🚧 En desarrollo activo - La API está en sus primeras etapas. Actualmente solo soporta operaciones de lectura (GET). Las operaciones de escritura y características avanzadas están planificadas para futuras versiones.