Práctica guiada: Instalación de Cypht en Ubuntu Server con Docker

1. Introducción

En esta práctica vamos a instalar Cypht en una máquina Ubuntu Server.

Cypht es una aplicación web que permite consultar varias cuentas de correo desde una única interfaz. A diferencia de otros clientes webmail más clásicos, Cypht está pensado para actuar como un agregador de cuentas de correo, por lo que resulta especialmente útil cuando queremos gestionar varias direcciones desde el navegador.

Durante la práctica utilizaremos Docker y Docker Compose, ya que esto nos permite instalar Cypht junto con su base de datos de una forma más limpia, controlada y fácil de mantener.

---

2. Objetivos de la práctica

Al finalizar esta práctica, el alumno será capaz de:

• Crear una máquina virtual Ubuntu Server.
• Instalar Docker en Ubuntu Server.
• Usar Docker Compose para desplegar varios servicios.
• Instalar Cypht junto con MariaDB.
• Acceder a Cypht desde un navegador web.
• Comprender el funcionamiento básico de un servicio web desplegado con contenedores.
• Solucionar errores habituales relacionados con permisos de Docker.

---

3. Escenario de la práctica

Vamos a crear el siguiente entorno:

Navegador del alumno
        |
        v
http://IP_DEL_SERVIDOR:8085
        |
        v
Ubuntu Server
        |
        +-- Contenedor Cypht
        |
        +-- Contenedor MariaDB

Cypht será la aplicación web y MariaDB almacenará la configuración y los datos necesarios.

---

4. Requisitos previos

Para realizar esta práctica necesitamos:

• Una máquina virtual con Ubuntu Server 24.04 o similar.
• Acceso a Internet desde la máquina virtual.
• Un usuario con permisos de sudo.
• Al menos:
  • 2 CPU
  • 4 GB de RAM recomendados
  • 25 GB de disco como mínimo
• Conocimientos básicos de terminal Linux.

---

5. Configuración recomendada de la máquina virtual

Si se trabaja con Proxmox, VirtualBox, VMware o similar, se recomienda crear la máquina con estos valores:

Recurso	Valor recomendado
Sistema operativo	Ubuntu Server 24.04
CPU	2 cores
RAM	4 GB
Disco	25 GB mínimo
Red	NAT o adaptador puente
Acceso	Consola o SSH

Importante:
Con 1 CPU y 2 GB de RAM la instalación puede funcionar, pero el sistema irá justo. Para trabajar cómodamente con Docker, Cypht y MariaDB, se recomienda usar 2 CPU y 4 GB de RAM.

---

Parte 1: Preparación del sistema

Paso 1. Actualizar el sistema

sudo apt update

Entramos en la máquina Ubuntu Server y actualizamos los repositorios:

Después actualizamos los paquetes instalados:

sudo apt upgrade -y

---

Paso 2. Instalar herramientas necesarias

Instalamos algunos paquetes que necesitaremos para añadir el repositorio oficial de Docker:

sudo apt install -y ca-certificates curl gnupg

---

Parte 2: Instalación de Docker

Paso 3. Crear el directorio para las claves de Docker

Ejecutamos:

sudo install -m 0755 -d /etc/apt/keyrings

Este directorio se usará para guardar la clave GPG del repositorio oficial de Docker.

---

Paso 4. Descargar la clave GPG de Docker

Ejecutamos:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Después damos permisos de lectura a la clave:

sudo chmod a+r /etc/apt/keyrings/docker.gpg

---

Paso 5. Añadir el repositorio oficial de Docker

Ejecutamos el siguiente comando completo:

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Actualizamos de nuevo los repositorios:

sudo apt update

---

Paso 6. Instalar Docker y Docker Compose

Instalamos Docker:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Comprobamos que Docker se ha instalado correctamente:

docker --version

Y comprobamos Docker Compose:

docker compose version

Si los comandos muestran una versión, la instalación ha sido correcta.

---

Paso 7. Comprobar el estado del servicio Docker

Ejecutamos:

sudo systemctl status docker

Si aparece como active (running), Docker está funcionando.

Podemos salir de esa pantalla pulsando:

q

Si Docker no estuviera activo, lo arrancamos con:

sudo systemctl enable --now docker

---

Parte 3: Preparación de Cypht

Paso 8. Crear la carpeta de trabajo

Crearemos la instalación en /opt/cypht.

sudo mkdir -p /opt/cypht

Cambiamos el propietario de la carpeta para poder trabajar cómodamente con nuestro usuario:

sudo chown -R $USER:$USER /opt/cypht

Entramos en la carpeta:

cd /opt/cypht

---

Paso 9. Crear el archivo docker-compose.yml

Creamos el archivo:

nano docker-compose.yml

Dentro pegamos el siguiente contenido:

services:
  db:
    image: mariadb:10
    container_name: cypht-db
    restart: unless-stopped
    volumes:
      - ./data/mysql:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: Cambia_Esta_Clave_Root
      MYSQL_DATABASE: cypht
      MYSQL_USER: cypht
      MYSQL_PASSWORD: Cambia_Esta_Clave_Cypht
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-ucypht", "-pCambia_Esta_Clave_Cypht"]
      interval: 10s
      timeout: 5s
      retries: 5

  cypht:
    image: cypht/cypht:2.8.0
    container_name: cypht
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8085:80"
    environment:
      AUTH_USERNAME: admin
      AUTH_PASSWORD: Cambia_Esta_Clave_Admin

      DB_CONNECTION_TYPE: host
      DB_DRIVER: mysql
      DB_HOST: db
      DB_NAME: cypht
      DB_USER: cypht
      DB_PASS: Cambia_Esta_Clave_Cypht

      SESSION_TYPE: DB
      USER_CONFIG_TYPE: DB
    volumes:
      - ./data/log/nginx:/var/log/nginx
      - ./data/log/php:/var/log/php
      - ./data/log/supervisord:/var/log/supervisord
      - ./data/fonts:/usr/local/share/cypht/site/fonts

Guardamos el archivo en nano:

Ctrl + O
Enter
Ctrl + X

---

Paso 10. Cambiar las contraseñas

Antes de arrancar los contenedores, debemos modificar las siguientes claves:

Cambia_Esta_Clave_Root
Cambia_Esta_Clave_Cypht
Cambia_Esta_Clave_Admin

Podemos editar el archivo de nuevo:

nano docker-compose.yml

Por ejemplo:

MYSQL_ROOT_PASSWORD: Root_1234_segura
MYSQL_PASSWORD: Cypht_1234_segura
AUTH_PASSWORD: Admin_1234_segura
DB_PASS: Cypht_1234_segura

Importante:
La contraseña MYSQL_PASSWORD y la contraseña DB_PASS deben coincidir, porque una define la contraseña del usuario de la base de datos y la otra es la contraseña que usará Cypht para conectarse a esa base de datos.

---

Parte 4: Arranque de Cypht

Paso 11. Levantar los contenedores

Desde la carpeta /opt/cypht, ejecutamos:

sudo docker compose up -d

La opción -d significa que los contenedores se ejecutarán en segundo plano.

---

Paso 12. Comprobar que los contenedores están funcionando

Ejecutamos:

sudo docker ps

Deberíamos ver dos contenedores:

• cypht
• cypht-db

Ejemplo de salida esperada:

CONTAINER ID   IMAGE              PORTS                  NAMES
xxxxxxxxxxxx   cypht/cypht:2.8.0  0.0.0.0:8085->80/tcp   cypht
xxxxxxxxxxxx   mariadb:10         3306/tcp               cypht-db

---

Paso 13. Ver los logs si algo falla

Si algún contenedor no aparece o hay problemas, revisamos los logs:

sudo docker compose logs -f

Para salir de los logs:

Ctrl + C

También podemos ver solo los logs de Cypht:

sudo docker compose logs -f cypht

O solo los de MariaDB:

sudo docker compose logs -f db

---

Parte 5: Acceso desde el navegador

Paso 14. Obtener la IP del servidor

Ejecutamos:

ip a

Buscamos la dirección IP de la tarjeta de red principal. Suele aparecer en interfaces como:

ens18
ens33
eth0
enp0s3

Ejemplo:

inet 192.168.1.80/24

En este caso, la IP sería:

192.168.1.80

---

Paso 15. Entrar en Cypht desde el navegador

Desde el ordenador anfitrión o desde otro equipo de la misma red, abrimos:

http://IP_DEL_SERVIDOR:8085

Por ejemplo:

http://192.168.1.80:8085

El usuario será:

admin

La contraseña será la que hayamos puesto en:

AUTH_PASSWORD

---

Parte 6: Apertura del puerto en el firewall

Paso 16. Comprobar si UFW está activo

Ejecutamos:

sudo ufw status

Si aparece como inactive, no hace falta abrir nada.

Si aparece como active, abrimos el puerto 8085:

sudo ufw allow 8085/tcp

Comprobamos de nuevo:

sudo ufw status

---

Parte 7: Añadir cuentas de correo en Cypht

Paso 17. Datos necesarios para configurar una cuenta

Para añadir una cuenta de correo en Cypht necesitamos conocer los datos del servidor de correo.

Normalmente necesitaremos:

Dato	Ejemplo
Servidor IMAP	mail.midominio.com
Puerto IMAP	993
Seguridad IMAP	SSL/TLS
Usuario	usuario@midominio.com
Contraseña	Contraseña del correo
Servidor SMTP	mail.midominio.com
Puerto SMTP	587
Seguridad SMTP	STARTTLS

---

Paso 18. Añadir una cuenta IMAP

Dentro de Cypht:

1. Entramos con el usuario admin.
2. Accedemos a la configuración.
3. Buscamos la sección de cuentas o servidores IMAP.
4. Añadimos los datos de la cuenta.
5. Guardamos la configuración.

Ejemplo de configuración IMAP:

Servidor IMAP: mail.midominio.com
Puerto: 993
Seguridad: SSL/TLS
Usuario: usuario@midominio.com
Contraseña: ********

---

Paso 19. Añadir una cuenta SMTP

Para poder enviar correos también debemos configurar SMTP.

Ejemplo:

Servidor SMTP: mail.midominio.com
Puerto: 587
Seguridad: STARTTLS
Usuario: usuario@midominio.com
Contraseña: ********

Nota:
En algunos proveedores de correo puede ser necesario activar el acceso por aplicaciones externas o generar una contraseña específica de aplicación.

---

Parte 8: Comandos básicos de administración

Ver contenedores activos

sudo docker ps

---

Ver todos los contenedores, incluso los detenidos

sudo docker ps -a

---

Parar Cypht

cd /opt/cypht
sudo docker compose down

---

Arrancar Cypht de nuevo

cd /opt/cypht
sudo docker compose up -d

---

Reiniciar los contenedores

cd /opt/cypht
sudo docker compose restart

---

Ver logs

cd /opt/cypht
sudo docker compose logs -f

---

Actualizar imágenes

cd /opt/cypht
sudo docker compose pull
sudo docker compose up -d

---

Parte 9: Error habitual de permisos con Docker

Problema

Puede aparecer este error:

unable to get image 'mariadb:10': permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Este error significa que el usuario actual no tiene permisos para comunicarse con Docker.

---

Solución rápida

Ejecutar el comando con sudo:

sudo docker compose up -d

---

Solución permanente

Añadimos nuestro usuario al grupo docker:

sudo usermod -aG docker $USER

Después reiniciamos la máquina:

sudo reboot

Cuando vuelva a arrancar, comprobamos:

docker ps

Si ya no aparece el error, podremos usar Docker sin sudo.

Importante:
Añadir un usuario al grupo docker le da mucho poder sobre el sistema. En un servidor real, esto debe hacerse solo con usuarios de confianza.

---

Parte 10: Comprobaciones finales

Al terminar la práctica, debemos comprobar:

Comprobación	Resultado esperado
Docker está instalado	docker --version muestra una versión
Docker Compose funciona	docker compose version muestra una versión
Los contenedores están activos	sudo docker ps muestra cypht y cypht-db
Cypht responde en navegador	Se puede acceder a http://IP:8085
El usuario admin funciona	Podemos iniciar sesión
El puerto está abierto	El navegador conecta correctamente
Se puede añadir una cuenta IMAP	La cuenta aparece en Cypht