Auto-hospedeiro - Primeiros passos

Este guia leva você de um servidor vazio para um Kanera em execução no qual você pode entrar.

Ele cobre as partes que cada implantação precisa: requisitos, capacidade, arquivo de ambiente, inicialização da pilha e confirmação de seu funcionamento. Peças opcionais – API pública, MCP, e-mail, armazenamento e backups – cada uma tem sua própria página, vinculada no final.

Requisitos

Você precisa de:

• Um servidor com Docker e Docker Compose.
• Um domínio apontando para o servidor.
• HTTPS na frente do Kanera, geralmente por meio de Caddy, Traefik, nginx ou um balanceador de carga em nuvem.
• Credenciais SMTP se desejar que Kanera envie e-mail.
• Um plano para fazer backup de dados PostgreSQL e arquivos carregados.

Capacidade de planejamento

Kanera é leve em escala de equipes pequenas. Seu arquivo composto não define limites rígidos de CPU ou memória, e o serviço de migração é encerrado após a inicialização. A pilha padrão executa PostgreSQL, Valkey, duas réplicas de API, um trabalhador, a API pública, MCP e nginx.

Use-os como pontos de partida e depois meça sua própria atividade simultânea, arquivos, integrações e janela de backup:

Equipe típica	Capacidade inicial	Disco local	Notas
Pessoal ou pouco usado	1 vCPU, 1 GiB de RAM	10GB	Usar API_REPLICAS=1 e deixe o perfil de monitoramento opcional desativado.
1 a 25 usuários ativos	1-2 vCPU, 2 GiB de RAM	20 GB	Confortável para atividades normais do quadro, notificações e integrações leves.
26 a 100 usuários ativos	2 a 4 vCPUs, 4 GiB de RAM	40 GB	Adiciona espaço para atividades simultâneas, uploads, tráfego de API, webhooks e cache de banco de dados.
Mais de 100 usuários ativos	Mais de 4 vCPUs, mais de 8 GiB de RAM	Mais de 80 GB	Faça testes de carga com dados representativos antes do lançamento, depois dimensione as réplicas de API e ajuste o PostgreSQL a partir do uso observado.

Estas são linhas de base de planejamento, não limites rígidos de usuários ou garantias de capacidade medida. A atividade simultânea é mais importante do que o número de contas registradas. O volume e a retenção de arquivos geralmente determinam mais os requisitos de disco do que o próprio Kanera. Mantenha backups de bancos de dados e arquivos carregados fora do disco principal do servidor e alerte sobre o crescimento do disco.

O perfil opcional de monitoramento Prometheus, Grafana, Loki, Alloy e exportador adiciona vários processos. O guia de implantação estima cerca de 0,7 a 1,5 GiB de memória adicional, dependendo do volume de log e do uso do painel. Faça um orçamento separadamente ou execute o monitoramento em outro host.

Para saber o que cada serviço faz e quais expor, consulte Serviços e roteamento.

Baixar Kanera

Kanera é enviado como imagens Docker pré-construídas. Cada liberar inclui um pronto para uso docker-compose.yml que os extrai, então você não precisa clonar o repositório ou construir nada.

No servidor, crie um diretório para Kanera e baixe o arquivo de composição e o arquivo de ambiente de exemplo da versão mais recente:

mkdir kanera && cd kanera
curl -fsSLo docker-compose.yml https://github.com/happendev/Kanera/releases/latest/download/docker-compose.yml
curl -fsSLo .env https://github.com/happendev/Kanera/releases/latest/download/env.example

O arquivo de composição fixa todas as imagens nessa versão, então nada muda até que você atualizar. Ele precisa do Docker Compose 2.23 ou mais recente (docker compose version).

Configurar o arquivo de ambiente

Abrir .env e substitua todos os espaços reservados. Defina os valores de produção necessários:

WEB_ORIGIN=https://kanera.example.com
COOKIE_DOMAIN=kanera.example.com
COOKIE_SECURE=true
KANERA_ENVIRONMENT=production

POSTGRES_PASSWORD=<openssl rand -hex 32>
JWT_SECRET=<openssl rand -hex 32>
MCP_INTERNAL_SECRET=<openssl rand -hex 32>
MFA_ENCRYPTION_KEY=<openssl rand -hex 32>
MEDIA_SIGNING_SECRET=<openssl rand -hex 32>
SECRETS_ENCRYPTION_KEY=<openssl rand -hex 32>

Mantenha esses segredos estáveis durante as reimplantações. Mudando JWT_SECRET desconecta os usuários. Mudando MFA_ENCRYPTION_KEY invalida autenticadores registrados e desafios de MFA. Mudando MEDIA_SIGNING_SECRET invalida URLs de mídia assinada existentes. MCP_INTERNAL_SECRET autentica o serviço MCP para a API. SECRETS_ENCRYPTION_KEY protege segredos de integração armazenados e deve ser distinto de JWT_SECRET.

O modo auto-hospedado é o padrão:

KANERA_DEPLOYMENT_MODE=self_hosted

Não defina variáveis de faturamento do Stripe hospedadas, a menos que você esteja executando uma implantação hospedada no estilo Kanera SaaS.

Veja Referência Ambiental para configurações de produção e env.full.example para cada valor de ajuste opcional e padrão.

Iniciar Kanera

docker compose up -d

Docker extrai as imagens e o serviço de migração configura o banco de dados uma vez antes api, workere public-api começar. O serviço MCP é iniciado após a verificação de funcionamento da API pública ser aprovada.

Verifique a implantação

Abra seu domínio da web em um navegador:

https://kanera.example.com

Verificações úteis:

docker compose ps
docker compose logs -f api
docker compose logs -f worker
docker compose logs -f public-api
docker compose logs -f mcp

Verificações de saúde:

curl https://kanera.example.com/api/health
curl https://api.kanera.example.com/health
curl https://mcp.kanera.example.com/health

As verificações públicas de API e MCP só se aplicam se esses serviços forem expostos.

Se algo não acontecer, trabalhe Problemas comuns em ordem e não por sintoma.

Configure o que você precisa

Nada abaixo é necessário para fazer login e usar os painéis. Adicione cada peça quando quiser:

Página	Capas
Referência Ambiental	Segredos necessários, URLs públicos, política de acesso, armazenamento, entrega, dimensionamento, retenção, monitoramento e configurações administrativas.
Serviços e roteamento	O que cada serviço faz, domínios recomendados, portas de publicação e confiança de proxy reverso.
E-mail e notificações	SMTP, push do navegador, destinos pessoais ntfy/Gotify/webhook e destinos de bate-papo.
Integrações e APIs	Expondo a API pública e MCP, OAuth para agentes de IA e cópia de anexos do Trello.
Armazenamento e backups	Armazenamento de upload local ou S3, backups de bancos de dados e arquivos e os segredos que vale a pena guardar.
Atualizações e dimensionamento	Atualizando para uma nova versão e contagens de réplicas.

Para obter a referência de implantação apoiada pela implementação, consulte DEPLOY.md no repositório Kanera.