# Cómo instalar Paperclip AI en un VPS Ubuntu y publicarlo con Cloudflare Tunnel En esta guía vamos a instalar **Paperclip AI** en un servidor Ubuntu, dejarlo funcionando como servicio del sistema y publicarlo de forma segura mediante **Cloudflare Tunnel**, sin abrir el puerto `3100` directamente a Internet. La idea es montar una instalación sencilla, práctica y segura: ```text Usuario ↓ https://paperclip.tudominio.com ↓ Cloudflare Tunnel ↓ http://127.0.0.1:3100 ↓ Paperclip AI en el VPS ``` Con esta arquitectura, Paperclip queda escuchando solo en `localhost`, y Cloudflare Tunnel se encarga de exponerlo mediante HTTPS usando un subdominio propio. --- ## Requisitos previos Necesitas: ```text Servidor Ubuntu 22.04 / 24.04 Dominio gestionado en Cloudflare Acceso SSH al servidor Usuario no root con permisos sudo Node.js 20 o superior ``` En este ejemplo usaremos: ```text Usuario Linux: moises Subdominio: paperclip.tudominio.com Puerto interno de Paperclip: 3100 ``` Sustituye estos valores por los tuyos. --- ## 1. Crear un usuario con permisos sudo Entra como `root` en el servidor y crea el usuario: ```bash adduser moises ``` Añádelo al grupo `sudo`: ```bash usermod -aG sudo moises ``` Comprueba que el usuario pertenece al grupo `sudo`: ```bash groups moises ``` Deberías ver algo parecido a: ```text moises : moises sudo ``` A partir de este punto, trabaja con el usuario normal: ```bash su - moises ``` Comprueba que estás usando el usuario correcto: ```bash whoami ``` Debe responder: ```text moises ``` --- ## 2. Instalar Node.js 22 Comprueba la versión actual de Node y npm: ```bash node -v npm -v ``` Paperclip necesita **Node.js 20 o superior**. Si tienes una versión inferior, instala Node.js 22 usando NodeSource: ```bash curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs ``` Verifica la instalación: ```bash node -v npm -v ``` Ejemplo de salida válida: ```text v22.22.2 10.9.7 ``` --- ## 3. Instalar y arrancar Paperclip Ejecuta Paperclip con el usuario normal, no con `sudo`: ```bash npx paperclipai onboard --yes ``` Es importante no usar `sudo`, porque Paperclip guarda su configuración en la carpeta del usuario: ```text /home/moises/.paperclip ``` Si lo ejecutas con `sudo`, podrías generar archivos propiedad de `root` y luego tener problemas de permisos. Si todo va bien, verás algo parecido a: ```text Mode embedded-postgres | static-ui Deploy local_trusted Bind loopback (127.0.0.1) Server 3100 UI http://127.0.0.1:3100 Database /home/moises/.paperclip/instances/default/db ``` La línea importante es: ```text Server listening on 127.0.0.1:3100 ``` Eso significa que Paperclip está funcionando, pero solo accesible desde el propio servidor. --- ## 4. Probar Paperclip mediante túnel SSH Desde tu ordenador local puedes crear un túnel SSH hacia el servidor: ```bash ssh -L 3100:127.0.0.1:3100 moises@IP_DEL_SERVIDOR ``` Después abre en tu navegador: ```text http://127.0.0.1:3100 ``` Si ves la interfaz de Paperclip, la instalación básica está correcta. --- ## 5. Crear un servicio systemd para Paperclip Ahora vamos a dejar Paperclip funcionando como servicio. Así arrancará automáticamente al reiniciar el servidor y se levantará de nuevo si se cae. Primero detén Paperclip si lo tienes ejecutándose en primer plano: ```text CTRL + C ``` Comprueba que el puerto quedó libre: ```bash ss -ltnp | grep ':3100' || echo "Puerto 3100 libre" ``` Crea el servicio: ```bash sudo tee /etc/systemd/system/paperclip.service > /dev/null <<'EOF' [Unit] Description=Paperclip AI After=network-online.target Wants=network-online.target [Service] Type=simple User=moises Group=moises WorkingDirectory=/home/moises Environment=HOME=/home/moises Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ExecStart=/usr/bin/npx --yes paperclipai run Restart=always RestartSec=5 [Install] WantedBy=multi-user.target EOF ``` Recarga systemd y activa el servicio: ```bash sudo systemctl daemon-reload sudo systemctl enable --now paperclip sudo systemctl status paperclip --no-pager ``` Debe aparecer algo como: ```text Active: active (running) ``` Prueba la salud de la API: ```bash curl http://127.0.0.1:3100/api/health ``` --- ## 6. Comandos útiles para Paperclip Ver estado: ```bash sudo systemctl status paperclip --no-pager ``` Reiniciar: ```bash sudo systemctl restart paperclip ``` Detener: ```bash sudo systemctl stop paperclip ``` Iniciar: ```bash sudo systemctl start paperclip ``` Ver logs en vivo: ```bash journalctl -u paperclip -f ``` --- ## 7. Instalar pnpm Aunque Paperclip puede arrancar con `npx`, algunas instrucciones de su documentación usan `pnpm`. Como estamos usando Node moderno, podemos activar `pnpm` mediante Corepack: ```bash sudo corepack enable corepack prepare pnpm@latest --activate pnpm -v ``` --- ## 8. Instalar cloudflared Ahora instalaremos `cloudflared`, el servicio que permitirá conectar nuestro VPS con Cloudflare Tunnel. Añade el repositorio oficial de Cloudflare: ```bash sudo mkdir -p --mode=0755 /usr/share/keyrings curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \ | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" \ | sudo tee /etc/apt/sources.list.d/cloudflared.list sudo apt-get update sudo apt-get install -y cloudflared cloudflared --version ``` --- ## 9. Autenticar cloudflared con Cloudflare Ejecuta: ```bash cloudflared tunnel login ``` El comando mostrará una URL. Abre esa URL en el navegador, inicia sesión en Cloudflare y selecciona el dominio que quieres usar. Cuando termine correctamente, verás algo parecido a: ```text You have successfully logged in. ``` --- ## 10. Crear el túnel Crea un túnel para Paperclip: ```bash cloudflared tunnel create paperclip-tonyhelper ``` El comando devolverá un ID parecido a: ```text Created tunnel paperclip-tonyhelper with id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX ``` Ahora crea el registro DNS del subdominio: ```bash cloudflared tunnel route dns paperclip-tonyhelper paperclip.tudominio.com ``` --- ## 11. Configurar el túnel Obtén el ID del túnel: ```bash TUNNEL_ID=$(cloudflared tunnel list | awk '/paperclip-tonyhelper/ {print $1; exit}') echo $TUNNEL_ID ``` Crea la configuración: ```bash sudo mkdir -p /etc/cloudflared sudo cp ~/.cloudflared/${TUNNEL_ID}.json /etc/cloudflared/${TUNNEL_ID}.json sudo tee /etc/cloudflared/config.yml > /dev/null <