📥 Guía de Instalación: ClipCascade

Name: ClipCascade
Author: Sathvik-Rao

ClipCascade es una utilidad open source ligera que sincroniza automáticamente el portapapeles entre múltiples dispositivos sin necesidad de pulsación manual. Ofrece sincronización en tiempo real con cifrado end-to-end, soporte para Windows, macOS, Linux y Android, y opciones de auto-alojamiento completo.

🔗 Enlaces Contextuales

📸 Capturas de Interfaz

Windows	macOS	Android	Linux GUI	Linux CLI

✨ Características Principales

🚀 Sincronización Instantánea – El contenido del portapapeles se actualiza en tiempo real en todos los dispositivos conectados. Simplemente copia y aparece.
🔒 Autenticación Segura – Garantiza que solo usuarios autorizados puedan sincronizar datos del portapapeles.
🛡️ Cifrado End-to-End – Protege el contenido del portapapeles con seguridad criptográfica avanzada y técnicas de hash.
🔄 Modos de Sincronización Doble:

☁️ Sincronización Basada en Servidor – Sincronización confiable basada en la nube mediante un servidor centralizado.
🔗 Sincronización Peer-to-Peer – Conexión directa dispositivo-a-dispositivo para latencia ultra-baja y dependencia mínima del servidor.

💻 Compatibilidad Multiplataforma – Funciona perfectamente en Windows, macOS, Linux y Android.
📄📷📁 Portapapeles Universal – Sincroniza texto, imágenes y archivos sin esfuerzo entre dispositivos.
📦 Opción de Auto-Alojamiento – Despliega tu propia instancia segura usando una imagen Docker o archivo JAR independiente.
👥 Soporte Multiusuario – Aísla los datos del portapapeles por usuario con autenticación individual.

🦾 Auto-Alojamiento en Hardware Físico (Linux)

Este documento proporciona instrucciones paso a paso para instalar ClipCascade en sistemas Debian/Ubuntu, Fedora y Arch-based. Aunque los comandos están específicamente adaptados para estas distribuciones, puedes adaptar el proceso para otras distribuciones de Linux con modificaciones menores.

Pasos de Instalación:

Verificar actualizaciones e instalar paquetes requeridos

Debian/Ubuntu:
sudo apt update && sudo apt install -y python3-pip python3-venv libgtk-3-dev
Fedora:
sudo dnf update && sudo dnf install -y python3-pip python3-virtualenv gtk3-devel
Arch:
sudo pacman -Syu && sudo pacman -S python-gtk3 pip

Instalar GTK 3.0 para monitorización de portapapeles y soporte GUI

Debian/Ubuntu:
sudo apt install -y libgtk-3-0
Fedora:
sudo dnf install -z gtk3
Arch:
sudo pacman -S gtk3

Instalar extensiones de soporte GNOME tray (si el icono de bandeja no está disponible)

Para usuarios de GNOME, instala la extensión del menú de aplicaciones si el icono de bandeja no aparece:

Debian/Ubuntu/Fedora:
sudo apt install -y gnome-shell-extension-appindicator
Arch:
sudo pacman -S gnome-shell-extension-appindicator

Instalar dependencias de Python

Debian/Ubuntu/Fedora:
sudo pip3 install clipcascade
Arch:
sudo pacman -S clipcascade

Ejecutar la Aplicación

GUI:
clipcascade --gui
CLI:
clipcascade --xmode true

Ejecutar la Aplicación en Segundo Plano (si es necesario)

GUI:
gsettings set org.gnome.desktop.session idle-delay 0
CLI:
clipcascade --daemonize

Añadir ClipCascade al Script de Inicio (si es necesario)

Ejemplo para ~/.config/autostart/clipcascade.desktop:

[Desktop Entry]
Type=Application
Name=ClipCascade
Exec=clipcascade --gui
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true

🐳 Auto-Alojamiento Usando Docker

Puedes alojar ClipCascade en tu servidor usando Docker con docker-compose o un simple comando docker run.

Opción 1: Usando Docker Compose

# 🔑 Credenciales de administrador predeterminadas:
# Username: admin
# Password: admin123
# ⚠️ IMPORTANTE: Asegúrate de cambiar las credenciales de administrador predeterminadas inmediatamente después del primer login.

services:
  clipcascade:
    image: sathvikrao/clipcascade:latest
    ports:
      - "8080:8080"
    restart: always
    volumes:
      - ./cc_users:/database # Persistencia para datos de usuario
    environment:
      - CC_MAX_MESSAGE_SIZE_IN_MiB=1 # Tamaño máximo del mensaje en MiB (ignorado si el modo P2P está habilitado)
      - CC_P2P_ENABLED=false # Habilita o deshabilita el modo peer-to-peer(P2P)
      # - CC_ALLOWED_ORIGINS=https://clipcascade.example.com # Define orígenes CORS permitidos para seguridad
      # - CC_SIGNUP_ENABLED=false # Habilita o deshabilita registro de usuarios propio

Ejecuta el contenedor Docker usando Docker Compose:

docker-compose up -d

Accede a la página de monitorización web en http://localhost:8080. Al iniciar sesión por primera vez, actualiza las credenciales predeterminadas (admin/admin123) para seguridad.

Opción 2: Usando Docker Run

docker run -d \
  --name clipcascade \
  -p 8080:8080 \
  -e CC_MAX_MESSAGE_SIZE_IN_MiB=1 \
  -v ./cc_users:/database \
  sathvikrao/clipcascade

⚙️ Detalles Avanzados

🗄️ Configuración del Servidor:

Importante: Aviso de Seguridad – Cambia las credenciales predeterminadas inmediatamente después del primer login.
Credenciales de Administrador Predeterminadas: admin/admin123
Punto Final de Verificación de Salud: /health
Verificador de Actualización Integrado – Notifica sobre nuevas versiones disponibles.
Variables de Entorno:

CC_MAX_MESSAGE_SIZE_IN_MiB: Tamaño máximo del mensaje en MiB
CC_P2P_ENABLED: Habilita/deshabilita modo P2P
CC_ALLOWED_ORIGINS: Define orígenes CORS permitidos para seguridad
CC_SIGNUP_ENABLED: Habilita/deshabilita registro de usuarios propio

🔒 Configuración de Cifrado End-to-End para Datos del Portapapeles:

ClipCascade utiliza cifrado end-to-end con acceso zero-knowledge para proteger los datos del portapapeles. El cifrado se aplica automáticamente a todos los mensajes sincronizados.

🖥️📱 Aplicaciones Cliente

Extra Config/Configuración Avanzada (Desktop/Mobile):

Desktop (Específico):
clipcascade --config /path/to/config.json
Android (Específico):
clipcascade --android-config /path/to/android-config.json

⇄ Configuración de Proxy Inverso:

Nota: Configura un proxy inverso (nginx, Apache) para HTTPS y redirección correcta.

# Ejemplo nginx.conf
server {
    listen 443 ssl;
    server_name clipcascade.tudominio.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🔓 Reglas de Desvío de Proxy SSO:

Puntos finales HTTP(S): /api/*, /login, /register
Puntos finales de handshake WebSocket: /ws/*

🔧 Uso

ClipCascade sincroniza automáticamente el portapapeles entre dispositivos. Simplemente copia en un dispositivo y aparece en todos los demás.

⚠️ Errores Habituales y Soluciones

Error: 'No module named Crypto'

Solución: pip3 install pycryptodome

Error: 'ModuleNotFoundError: No module named tkinter'

Solución: sudo apt install python3-tk (Debian/Ubuntu) o sudo dnf install python3-tkinter (Fedora)

Error: 'gtk_widget_get_scale_factor: assertion failed'

Solución: Asegúrate de tener GTK 3.0 instalado correctamente y reinicia la aplicación

Error: 'g-exec-error-quark'

Solución: Verifica que las rutas de ejecución estén correctas y que los permisos sean adecuados

Error: libavformat no encontrado

Solución: sudo apt install libavformat-dev (Debian/Ubuntu) o sudo pacman -S libavformat (Arch)

🔒 Seguridad y Best Practices

Cambia las credenciales predeterminadas inmediatamente después del primer login
Configura CC_ALLOWED_ORIGINS para limitar el acceso CORS
Habilita CC_SIGNUP_ENABLED=false en producción para evitar registros no autorizados
Usa variables de entorno para almacenar credenciales, no archivos de texto plano
Configura un proxy inverso con HTTPS para conexiones seguras
Habilita el modo P2P (CC_P2P_ENABLED=true) para reducir la dependencia del servidor

🔄 Actualización y Rollback

Actualizar ClipCascade:

# Para Docker Compose
docker-compose pull
docker-compose up -d

# Para Docker Run
docker pull sathvikrao/clipcascade:latest
docker restart clipcascade

Copias de Seguridad:

# Backup de datos de usuario
tar -czvf cc_users_backup.tar.gz ./cc_users

# Restaurar desde backup
tar -xzf cc_users_backup.tar.gz -C /ruta/al/datos/

📦 Versionado

Las versiones siguen el formato semántico: MAJOR.MINOR.PATCH (ej. 3.2.0).

Historial de Releases:

v3.2.0 (04 May 2026): Mejoras P2P, corrección de race conditions, WebSocket ping/pong, Wayland clipboard watch en Linux, pasteboard locking en macOS.
v3.1.0 (07 Aug 2025): Actualización a Java 21 para servidor, reducción de uso de memoria en Android, mejoras de rendimiento.
v3.0.0: Introducción del modo P2P, mejoras de seguridad y rendimiento.

🛠️ TODO Pendiente

Mejorar soporte para Wayland en Linux
Añadir más opciones de configuración de seguridad
Optimizar rendimiento P2P

💬 Soporte y Contribuciones

GitHub Issues: https://github.com/Sathvik-Rao/ClipCascade/issues
Discusiones: https://github.com/Sathvik-Rao/ClipCascade/discussions
Repositorio Oficial: https://github.com/Sathvik-Rao/ClipCascade
Docker Hub: https://hub.docker.com/r/sathvikrao/clipcascade

📜 Licencia

ClipCascade está licenciado bajo GPL-3.0.

⚠️ Limitaciones y Advertencias

La información técnica es una estimación automática y debe validarse antes de un despliegue de producción.
Revisar la documentación oficial, persistencia de datos, secretos, copias de seguridad y proxy HTTPS antes de producción.
Verificar compatibilidad con Wayland en entornos Linux modernos.

Fecha de verificación: 2026-10-05

Fuentes verificadas

https://github.com/Sathvik-Rao/ClipCascade/blob/main/README.md

Instalar ClipCascade - Guía Completa de Auto-Alojamiento

📥 Guía de Instalación: ClipCascade

🔗 Enlaces Contextuales

📸 Capturas de Interfaz

✨ Características Principales

🦾 Auto-Alojamiento en Hardware Físico (Linux)

Pasos de Instalación:

🐳 Auto-Alojamiento Usando Docker

Opción 1: Usando Docker Compose

Opción 2: Usando Docker Run

⚙️ Detalles Avanzados

🗄️ Configuración del Servidor:

🔒 Configuración de Cifrado End-to-End para Datos del Portapapeles:

🖥️📱 Aplicaciones Cliente

⇄ Configuración de Proxy Inverso:

🔓 Reglas de Desvío de Proxy SSO:

🔧 Uso

⚠️ Errores Habituales y Soluciones

🔒 Seguridad y Best Practices

🔄 Actualización y Rollback

Actualizar ClipCascade:

Copias de Seguridad:

📦 Versionado

Historial de Releases:

🛠️ TODO Pendiente

💬 Soporte y Contribuciones

📜 Licencia

⚠️ Limitaciones y Advertencias

Fuentes verificadas

Fuentes verificadas