Como instalar o Turso em uma VPS

Pré-requisitos

Comece com Ubuntu 22.04 ou 24.04, acesso SSH, IP público e pelo menos 1 GB de RAM. Use um domínio dedicado, como db.example.com, mas não exponha um protocolo de banco de dados diretamente à internet pública, a menos que a documentação oficial do servidor exija isso.

Consulte a documentação atual do Turso e do libSQL para auto-hospedagem antes de seguir este caminho. Os recursos do Turso gerenciado, o plano de controle da CLI e um servidor libSQL independente não são automaticamente intercambiáveis. Você precisa de backups criptografados fora do servidor e de um plano para migrações de esquema.

Etapa 1, conectando-se ao servidor

Atualize a VPS e crie um diretório privado para os dados:

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

Restrinja o SSH aos administradores. Se os clientes se conectarem pela rede, use uma rede privada ou VPN sempre que possível. Não coloque credenciais do banco de dados no histórico do shell.

Etapa 2, instalando o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu:

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

Confirme que o disco de dados é persistente e tem espaço livre suficiente. Bancos de dados no estilo SQLite podem crescer rapidamente quando logs write-ahead e backups são mantidos.

Etapa 3, executando o servidor oficial compatível com libSQL

Use a imagem ou o binário atual do servidor libSQL indicado na documentação do Turso/libSQL. Não tente adivinhar o nome da imagem ou uma tag de versão. Informe o valor verificado em .env:

LIBSQL_IMAGE=REPLACE_WITH_THE_CURRENT_OFFICIAL_IMAGE
LIBSQL_TOKEN=REPLACE_WITH_A_LONG_RANDOM_VALUE

Uma estrutura Compose mínima é:

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

Os nomes das variáveis, a porta do contêiner e o caminho dos dados precisam corresponder à versão oficial escolhida. Considere este bloco um exemplo de estrutura, não um substituto para o arquivo de implantação mantido pelo projeto. Só inicie depois de validá-lo com a documentação do projeto oficial:

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

Use um cliente compatível ou a CLI do Turso para criar um banco de dados de teste e executar uma migração de esquema. Confira se o banco de dados continua disponível após recriar o contêiner, antes de usá-lo em um aplicativo.

Etapa 4, configurando o proxy reverso

Se o servidor expuser uma API HTTP, encaminhe um domínio privado ou protegido pelo Caddy ou Nginx e encerre o TLS nesse proxy. Mantenha a porta do banco de dados vinculada ao localhost, a menos que você tenha um projeto de rede concreto. Adicione autenticação e limites de taxa conforme a documentação do servidor.

Não confunda uma API de banco de dados com uma API de aplicativo. Nunca permita que clientes públicos arbitrários gravem no banco de dados sem uma camada de autorização do aplicativo. Teste a renovação do certificado e confirme que os clientes validam o certificado do servidor.

Etapa 5, primeiro acesso e configuração inicial

Crie um banco de dados de teste, aplique uma migração e conecte-se a partir de um aplicativo pequeno usando o cliente libSQL compatível. Teste leituras, gravações, conexões simultâneas e uma reinicialização. Registre a URL do banco de dados e o token na configuração do servidor, nunca no código do navegador.

Verifique se o aplicativo lida com períodos de indisponibilidade do banco de dados. Uma VPS única representa um único domínio de falha, então novas tentativas e migrações idempotentes são importantes até para um projeto pequeno.

Manutenção

Faça backup dos arquivos do banco de dados seguindo o procedimento oficial de consistência e copie os backups para um armazenamento fora da VPS. Teste a restauração em um servidor limpo. Monitore o disco, os logs write-ahead, a latência e as conexões com falha.

Atualize o servidor somente depois de conferir a compatibilidade com o cliente libSQL e seu esquema. Mantenha o digest exato da imagem ou a versão do binário usados em produção. Se precisar da replicação gerenciada ou do plano de controle do Turso, use o serviço gerenciado em vez de presumir que este nó único oferece as mesmas garantias.