06 — SurrealDB: instalação nativa e serviço systemd

Instala o binário oficial do SurrealDB diretamente no Ubuntu, sem Docker, e configura uma instância persistente que inicia automaticamente com o servidor.

O banco executa como usuário Linux dedicado, exige autenticação e escuta somente em 127.0.0.1:8000.

Execute um bloco por vez no servidor. Não compartilhe a saída do arquivo /etc/surrealdb/surrealdb.env: ele contém a senha root do banco.

Resultado esperado

/usr/local/bin/surreal               # CLI e servidor
/etc/surrealdb/surrealdb.env         # configuração e credencial, modo 640
/var/lib/surrealdb/data/             # dados persistentes SurrealKV
/etc/systemd/system/surrealdb.service

Decisões desta instalação:

• instalação nativa no Ubuntu, sem Docker;
• processo executado pelo usuário de serviço surrealdb, sem login interativo;
• backend surrealkv em /var/lib/surrealdb/data;
• autenticação ativa com usuário root do banco;
• senha aleatória fora do Git e da linha de execução do processo;
• bind somente em 127.0.0.1:8000;
• nenhuma regra adicional no UFW;
• serviço systemd habilitado para iniciar em todo boot;
• backup, restore, atualização e rollback continuam em etapa posterior.

1. Confirmar que não existe uma instalação anterior

if command -v surreal >/dev/null 2>&1; then
  command -v surreal
  surreal version
else
  echo 'SurrealDB ainda não instalado'
fi
systemctl show surrealdb.service \\
  --property=LoadState,ActiveState,SubState,UnitFileState \\
  --no-pager 2>/dev/null || true
pgrep -a surreal || echo 'Nenhum processo SurrealDB em execução'
ss -lntp | grep ':8000' || echo 'Nenhum listener na porta 8000'

Se o binário, serviço, processo ou listener já existir, não prossiga antes de registrar sua versão, configuração, armazenamento e origem. Nunca aponte dois backends diferentes para o mesmo diretório de dados.

2. Instalar pelo script oficial

Como root, execute:

curl -sSf https://install.surrealdb.com | sh

O instalador detecta o sistema e a arquitetura, baixa o binário compatível e tenta instalá-lo em /usr/local/bin/surreal. Instalações feitas em datas diferentes podem receber versões diferentes; registre sempre a versão observada no servidor.

3. Verificar o binário

printf '\\n=== CAMINHO ===\\n'
command -v surreal
printf '\\n=== VERSÃO ===\\n'
surreal version
printf '\\n=== ARQUIVO ===\\n'
ls -l "$(command -v surreal)"
file "$(command -v surreal)"
printf '\\n=== AJUDA DO SERVIDOR ===\\n'
surreal start --help | sed -n '1,160p'
surreal start --help | \\
  grep -E 'SURREAL_(BIND|PATH|USER|PASS|LOG|NO_IDENTIFICATION_HEADERS)'

Antes de continuar, confirme na ajuda instalada as opções correspondentes a SURREAL_BIND, SURREAL_PATH, SURREAL_USER, SURREAL_PASS, SURREAL_LOG e SURREAL_NO_IDENTIFICATION_HEADERS.

4. Criar o usuário e os diretórios do serviço

getent group surrealdb >/dev/null || groupadd --system surrealdb
id -u surrealdb >/dev/null 2>&1 || useradd \\
  --system \\
  --gid surrealdb \\
  --home-dir /var/lib/surrealdb \\
  --shell /usr/sbin/nologin \\
  surrealdb
install -d -m 0750 -o surrealdb -g surrealdb /var/lib/surrealdb
install -d -m 0750 -o root -g surrealdb /etc/surrealdb
getent passwd surrealdb
stat -c '%a %U:%G %n' /var/lib/surrealdb /etc/surrealdb

Esperado:

• usuário surrealdb sem shell interativo;
• dados pertencentes a surrealdb:surrealdb;
• configuração pertencente a root:surrealdb;
• ambos os diretórios com modo 750.

5. Criar a configuração protegida

O bloco gera uma senha hexadecimal aleatória de 256 bits e a grava no arquivo lido pelo serviço. A senha não é impressa no terminal.

umask 077
SURREALDB_ROOT_PASSWORD="$(openssl rand -hex 32)"
{
  printf 'SURREAL_BIND=127.0.0.1:8000\\n'
  printf 'SURREAL_PATH=surrealkv:///var/lib/surrealdb/data\\n'
  printf 'SURREAL_USER=root\\n'
  printf 'SURREAL_PASS=%s\\n' "$SURREALDB_ROOT_PASSWORD"
  printf 'SURREAL_LOG=info\\n'
  printf 'SURREAL_NO_IDENTIFICATION_HEADERS=true\\n'
} > /etc/surrealdb/surrealdb.env
unset SURREALDB_ROOT_PASSWORD
chown root:surrealdb /etc/surrealdb/surrealdb.env
chmod 640 /etc/surrealdb/surrealdb.env
umask 022
stat -c '%a %U:%G %n' /etc/surrealdb/surrealdb.env
sed -E 's/^(SURREAL_PASS=).+$/\\1[REDACTED]/' /etc/surrealdb/surrealdb.env

Esperado: arquivo 640 root:surrealdb e senha exibida somente como [REDACTED]. Copie a credencial para o cofre de segredos por um canal privado; ela não pertence a config/project.local.env, ao Git ou ao histórico do shell.

O caminho usa três barras porque é absoluto:

surrealkv:///var/lib/surrealdb/data.

6. Criar a unidade systemd

Crie /etc/systemd/system/surrealdb.service com este conteúdo:

[Unit]
Description=SurrealDB database server
Documentation=https://surrealdb.com/docs
After=network.target
[Service]
Type=simple
User=surrealdb
Group=surrealdb
EnvironmentFile=/etc/surrealdb/surrealdb.env
ExecStart=/usr/local/bin/surreal start
Restart=on-failure
RestartSec=5s
TimeoutStopSec=120s
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/surrealdb
RestrictSUIDSGID=true
[Install]
WantedBy=multi-user.target

Proteja e valide a unidade antes de ativá-la:

chown root:root /etc/systemd/system/surrealdb.service
chmod 644 /etc/systemd/system/surrealdb.service
systemd-analyze verify /etc/systemd/system/surrealdb.service

O systemd-analyze verify deve terminar sem erros.

7. Habilitar e iniciar o serviço

systemctl daemon-reload
systemctl enable --now surrealdb.service
systemctl show surrealdb.service \\
  --property=LoadState,ActiveState,SubState,UnitFileState,NRestarts \\
  --no-pager
journalctl -u surrealdb.service -n 50 --no-pager
ss -lntp | grep '127.0.0.1:8000'
ufw status verbose

Critérios:

• LoadState=loaded;
• ActiveState=active;
• SubState=running;
• UnitFileState=enabled;
• NRestarts=0 após a primeira inicialização estável;
• listener somente em 127.0.0.1:8000;
• nenhum erro de storage, autenticação ou permissão nos logs;
• nenhuma regra pública para a porta 8000 no UFW.

8. Fazer o smoke test autenticado

Carregue a credencial somente no shell atual, faça uma consulta pequena e remova as variáveis em seguida:

set -a
source /etc/surrealdb/surrealdb.env
set +a
printf 'RETURN "surrealdb-ok";\\n' | surreal sql \\
  --endpoint http://127.0.0.1:8000 \\
  --namespace main \\
  --database main \\
  --auth-level root \\
  --hide-welcome
unset SURREAL_BIND SURREAL_PATH SURREAL_USER SURREAL_PASS SURREAL_LOG
unset SURREAL_NO_IDENTIFICATION_HEADERS

Esperado: resposta contendo surrealdb-ok, sem erro de conexão ou autenticação. Não execute esse bloco com tracing de shell (set -x).

9. Validar reinício do serviço

systemctl restart surrealdb.service
systemctl show surrealdb.service \\
  --property=ActiveState,SubState,NRestarts \\
  --no-pager
journalctl -u surrealdb.service -n 30 --no-pager
ss -lntp | grep '127.0.0.1:8000'

Repita o smoke test autenticado da seção 8. O serviço deve voltar sem intervenção manual e usar o mesmo diretório persistente.

10. Validar inicialização após reboot

Faça este teste somente depois de todas as verificações anteriores passarem:

systemctl reboot

Depois que o SSH voltar, reconecte e execute:

systemctl show surrealdb.service \\
  --property=LoadState,ActiveState,SubState,UnitFileState,NRestarts \\
  --no-pager
journalctl -u surrealdb.service -b -n 50 --no-pager
ss -lntp | grep '127.0.0.1:8000'

O capítulo só está concluído quando o serviço aparecer como enabled, active e running no novo boot. Repita também o smoke test da seção 8 para confirmar autenticação e acesso ao banco depois do reboot.

Critérios de conclusão

• binário surreal instalado e versionado;
• usuário Linux surrealdb sem login criado;
• SurrealKV persistente em /var/lib/surrealdb/data;
• autenticação ativa e credencial protegida fora do Git;
• serviço executado como surrealdb, não como root;
• bind restrito a 127.0.0.1:8000;
• unit surrealdb.service habilitada e ativa;
• smoke test autenticado aprovado;
• restart do serviço aprovado;
• reboot do servidor aprovado com retorno automático do serviço;
• porta 8000 não exposta pelo UFW.

Estado da instância de referência

Pendente de execução no servidor. Após a validação, registrar aqui:

• data e versão instalada;
• caminho, ownership e arquitetura do binário;
• usuário, diretórios e permissões do serviço;
• estados systemd antes e depois do reboot;
• bind observado;
• smoke test autenticado;
• confirmação de que a porta 8000 não foi liberada no UFW.

Não marcar as etapas 19 e 20 do índice como concluídas antes de validar todos os itens correspondentes. Nunca registrar a senha.

Próximo passo

Documentar e testar backup, restore, atualização e rollback. O hardening final de capabilities e a política de produção permanecem como gate separado.

Referências oficiais

• Instalação no Linux
• Configuração self-hosted
• Variáveis de ambiente
• Comando surreal start
• Comando surreal sql
• Autenticação