Cómo instalar Turso en un VPS

Requisitos previos

Empieza con Ubuntu 22.04 o 24.04, SSH, IP pública y al menos 1 GB de RAM. Usa un hostname como db.example.com, pero no expongas directamente el protocolo de base de datos a internet salvo que la documentación oficial lo exija.

Lee la documentación actual de Turso y libSQL antes de elegir este camino. Las funciones de Turso gestionado, su CLI y un servidor libSQL independiente no son automáticamente intercambiables. Necesitas backups cifrados fuera del host y un plan para migraciones.

Paso 1, Conectarte a tu servidor

Actualiza el VPS y crea una carpeta privada para los datos:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl
mkdir -p /opt/libsql/data
cd /opt/libsql
chmod 750 /opt/libsql

Restringe SSH a administradores. Si los clientes conectan por red, usa una red privada o VPN cuando sea posible. No pongas credenciales en el historial de shell.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y Compose desde las instrucciones oficiales para Ubuntu:

docker --version
docker compose version
systemctl enable --now docker

Confirma que el disco es persistente y tiene espacio libre. Las bases SQLite pueden crecer con los write-ahead logs y los backups retenidos.

Paso 3, Ejecutar el servidor oficial compatible con libSQL

Usa la imagen o binario oficial actual de libSQL indicado por la documentación de Turso/libSQL. No adivines el nombre ni el tag. Guarda el valor verificado en .env:

LIBSQL_IMAGE=REPLACE_WITH_THE_CURRENT_OFFICIAL_IMAGE
LIBSQL_TOKEN=REPLACE_WITH_A_LONG_RANDOM_VALUE

La estructura mínima de Compose puede ser:

services:
  libsql:
    image: ${LIBSQL_IMAGE}
    restart: unless-stopped
    environment:
      SQLD_AUTH_JWT_KEY: ${LIBSQL_TOKEN}
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data:/var/lib/sqld

Los nombres de variables, el puerto y la ruta deben coincidir con el release oficial elegido. Este bloque muestra la estructura, no sustituye al archivo mantenido. Valídalo contra upstream antes de iniciar:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Usa el cliente compatible o Turso CLI soportado para crear una base de prueba y aplicar una migración. Comprueba que sobrevive a recrear el contenedor antes de conectarla a una aplicación.

Paso 4, Configurar el proxy inverso

Si el servidor expone una API HTTP, dirige un hostname privado o protegido mediante Caddy o Nginx y termina TLS allí. Mantén el puerto de base ligado a localhost salvo que tengas un diseño de red concreto. Añade auth y rate limits según la documentación.

No confundas una API de base de datos con una API de aplicación. No permitas que clientes públicos escriban libremente. Prueba renovación de certificados y validación por parte de los clientes.

Paso 5, Primer acceso y configuración inicial

Crea una base de prueba, aplica una migración y conecta una aplicación pequeña usando el cliente libSQL soportado. Prueba lecturas, escrituras, conexiones simultáneas y reinicios. Guarda URL y token en configuración de servidor, nunca en el navegador.

Comprueba que la aplicación soporta una indisponibilidad temporal. Un VPS único es un único dominio de fallo, por lo que los reintentos y migraciones idempotentes importan incluso en proyectos pequeños.

Mantenimiento

Haz backup siguiendo el procedimiento de consistencia oficial y copia los archivos fuera del VPS. Prueba restaurarlos en otro servidor. Monitoriza disco, write-ahead logs, latencia y conexiones fallidas.

Actualiza solo después de comprobar compatibilidad con el cliente y el schema. Conserva el digest de imagen o versión exacta. Si necesitas replicación o control plane de Turso, usa el servicio gestionado en lugar de asumir que este nodo ofrece las mismas garantías.