Como fazer self-host do NocoDB em 2026: conexões com bancos de dados, autenticação e persistência

Existem duas versões de “executar o NocoDB”: um container existe ou o serviço conclui sua função real. Apenas a segunda importa. Aqui, a comprovação consiste em conectar um banco de dados de origem descartável, criar uma grid e uma view filtrada, editar uma linha, adicionar um anexo e chamar a REST API.

O NocoDB atende a este propósito: uma interface de planilha sobre um banco de dados real. O deployment precisa preservar os componentes por trás desse comportamento; uma porta, um volume e um certificado são requisitos, não o resultado.

Delimite a fronteira de runtime do NocoDB

A saúde do processo e a saúde do produto são coisas distintas no NocoDB. A porta 8080 pode responder enquanto a transação voltada ao usuário ainda falha. O contrato de rede do NocoDB para produção é usar Postgres ou MySQL nos metadados, em vez de um arquivo local descartável. Mantenha endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao NocoDB uma credencial de serviço com escopo limitado.

Use este exercício de readiness após mudanças relevantes de configuração: conecte um banco de dados de origem descartável, crie uma grid e uma view filtrada, edite uma linha, adicione um anexo e chame a REST API. Mantenha verificações externas dispendiosas fora dos liveness probes para que uma indisponibilidade do provedor não cause um loop de reinicialização. O trabalho de capacity planning deve acompanhar a quantidade de linhas, o tráfego de anexos, a latência do banco de dados de metadados e o número simultâneo de usuários das grids — indicadores mais próximos da pressão real sobre o NocoDB do que as requisições de página.

Inicie o NocoDB com padrões observáveis

Inicie o NocoDB de modo que a rota permaneça privada até a conclusão do bootstrap.

docker run -d \
  --name nocodb \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v nocodb-data:/usr/app/data \
  -e NC_AUTH_JWT_SECRET=replace-with-a-long-random-value \
  nocodb/nocodb:latest

Se o processo entrar em loop, compare o usuário esperado pela image com o proprietário de cada caminho montado. Se permanecer ativo, teste a porta 8080 localmente e passe diretamente ao workflow: conecte um banco de dados de origem descartável, crie uma grid e uma view filtrada, edite uma linha, adicione um anexo e chame a REST API. Fixe a versão da image somente depois que essa verificação end-to-end for aprovada e registre a configuração exata junto ao serviço.

Domínios, headers de proxy e porta 8080

Escolha o hostname final do NocoDB antes que os usuários salvem callbacks ou configurações de cliente; em seguida, defina NC_PUBLIC_URL com o endereço HTTPS canônico. A rota da plataforma deve terminar o TLS uma única vez e apontar para a porta privada 8080.

Execute a transação de aceitação externamente. Se o cliente nunca chegar ao NocoDB, use o checklist de validação de SSL para verificar DNS e certificado. Se a requisição chegar ao NocoDB, mas o banco de dados de metadados estiver inacessível ou as URLs públicas apontarem para um host interno, pare de alterar redirects do proxy e inspecione a fronteira específica da aplicação.

Planeje o restore do NocoDB antes do lançamento

Defina o recovery point e o recovery time do NocoDB considerando o banco de dados de metadados, os anexos e quaisquer bancos de dados de origem externos. Monte /usr/app/data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Um volume nomeado resolve a persistência durante redeploys; ele não resolve comprometimentos nem a perda do servidor.

Monte um ambiente de restore limpo, use a mesma versão fixada da aplicação e comprove que bases, views, roles, anexos e mapeamentos de origem retornam sem alterar linhas no banco de dados conectado. Registre comandos, correções de ownership e o tempo decorrido. O guia de backup é um padrão útil: um backup só é confiável depois do restore, não depois do upload.

Decisões de segurança específicas do NocoDB

Feche a janela de bootstrap assim que existir o primeiro administrador confiável. A armadilha concreta do NocoDB é reutilizar um JWT secret fraco ou expor credenciais de bases a todos os editores; a fronteira mais segura é usar um JWT secret estável, limitar quem pode criar conexões com fontes de dados externas e revisar a exposição de views compartilhadas.

Gere NC_AUTH_JWT_SECRET como um valor longo e aleatório; a rotação normalmente invalida sessões ou tokens, portanto planeje o impacto para os usuários em vez de tratá-la como uma migração de encryption. A rede privada deve transportar as credenciais das dependências, e as roles dentro do NocoDB devem conceder apenas a ação útil mínima. Mantenha bodies sensíveis de requisições e respostas de provedores fora dos logs de rotina.

Verificações de capacidade e upgrade

Um container verde é necessário, mas não suficiente. O indicador de nível de serviço é a conclusão bem-sucedida de “conectar um banco de dados de origem descartável, criar uma grid e uma view filtrada, editar uma linha, adicionar um anexo e chamar a REST API”, enquanto os sinais prováveis de pressão são a quantidade de linhas, o tráfego de anexos, a latência do banco de dados de metadados e o número simultâneo de usuários das grids.

O change control é importante porque migrações de metadados podem afetar views e automations mesmo quando o banco de dados de origem subjacente permanece intocado. Preserve a image antiga, teste as migrações em um estado copiado e documente se o rollback é compatível depois da alteração do schema. Se o banco de dados de metadados estiver inacessível ou as URLs públicas apontarem para um host interno, diagnostique primeiro a fronteira que difere do ambiente funcional.

Um acceptance run de produção para o NocoDB

Antes da chegada dos usuários reais, crie uma release worksheet para o NocoDB. Ela deve indicar a image fixada, a porta 8080, a origem canônica, os caminhos persistentes e o responsável pelo Postgres ou MySQL usado nos metadados de produção, em vez de um arquivo local descartável. Anexe o resultado esperado desta transação: conectar um banco de dados de origem descartável, criar uma grid e uma view filtrada, editar uma linha, adicionar um anexo e chamar a REST API.

Use a worksheet depois de uma substituição normal e de um restore limpo. A recuperação só é aceita quando bases, views, roles, anexos e mapeamentos de origem retornam sem alterar linhas no banco de dados conectado. Colete também um resource trace curto cobrindo a quantidade de linhas, o tráfego de anexos, a latência do banco de dados de metadados e o número simultâneo de usuários das grids; mantenha-o junto à release para que futuras mudanças de capacidade sejam comparadas com o mesmo workload.

Inclua uma falha controlada: negue temporariamente à identidade de teste o acesso ao Postgres ou MySQL usado nos metadados de produção, em vez de um arquivo local descartável. Confirme que o NocoDB relata o problema na fronteira correta, restaure a condição válida e execute novamente a transação. Isso verifica a visibilidade dos erros, não apenas o sucesso, e impede que uma interface aparentemente saudável esconda um worker, callback ou conexão de banco de dados quebrado.

Onde o Dockup reduz o trabalho com o NocoDB

Para o NocoDB, o Dockup é mais útil na fronteira entre uma image e um serviço durável. Ele mantém a rota para a porta 8080, o TLS, os valores de secrets e o storage associados durante as substituições de containers, independentemente de o compute pertencer ao Dockup ou ao seu servidor conectado.

Finalize com o conhecimento da aplicação: defina NC_PUBLIC_URL como o endereço HTTPS canônico; conecte e teste o Postgres ou MySQL usado nos metadados de produção, em vez de um arquivo local descartável; e execute esta verificação: conecte um banco de dados de origem descartável, crie uma grid e uma view filtrada, edite uma linha, adicione um anexo e chame a REST API. Mantenha o resultado como uma verificação de deployment para que a próxima atualização da image seja avaliada pelo comportamento, e não pelo status do container.

Perguntas frequentes

O que o NocoDB precisa para um deployment de produção?

Exponha o container do NocoDB na porta 8080 por meio de uma única origem HTTPS. O requisito de rede de suporte é usar Postgres ou MySQL nos metadados de produção, em vez de um arquivo local descartável. Não considere o NocoDB pronto até conseguir conectar um banco de dados de origem descartável, criar uma grid e uma view filtrada, editar uma linha, adicionar um anexo e chamar a REST API.

Quais dados do NocoDB devem entrar em um backup?

Persista /usr/app/data e inclua o banco de dados de metadados, os anexos e quaisquer bancos de dados de origem externos no mesmo recovery manifest. Um restore limpo do NocoDB só é aprovado quando bases, views, roles, anexos e mapeamentos de origem retornam sem alterar linhas no banco de dados conectado.

O NocoDB exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do NocoDB e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do NocoDB: defina NC_PUBLIC_URL como o endereço HTTPS canônico. No NocoDB, o HTTPS protege credenciais ou conteúdo de usuários durante o tráfego e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do NocoDB?

Restaure o estado atual do NocoDB em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial porque migrações de metadados podem afetar views e automations mesmo quando o banco de dados de origem subjacente permanece intocado. Mantenha a image anterior do NocoDB até entender seus limites de migração de dados e rollback.