Instalação

Guia completo para instalar o Koda CRM no seu servidor.

Pré-requisitos

Antes de começar, certifique-se de ter:

Um servidor Linux (Ubuntu 22.04 recomendado)
Acesso SSH ao servidor
Docker instalado
Um domínio apontando para o servidor
Portas 80 e 443 abertas

Como verificar se tem Docker


docker --version
# Deve mostrar algo como: Docker version 24.0.0

Se não tiver Docker, instale:


curl -fsSL https://get.docker.com | sh

Passo 1: Acessar o Servidor

Conecte-se ao seu servidor via SSH:


ssh usuario@seu-servidor.com

Substitua usuario pelo seu nome de usuário e seu-servidor.com pelo IP ou domínio do servidor.

Passo 2: Baixar o Koda


# Criar pasta do projeto
mkdir -p /opt/koda
cd /opt/koda
 
# Baixar os arquivos
# (Os arquivos serão fornecidos junto com a licença)

Passo 3: Configurar o Sistema

3.1 Criar arquivo de configuração


cp .env.example .env

3.2 Editar o arquivo .env

Abra o arquivo com um editor de texto:


nano .env

3.3 Preencher as configurações

O arquivo .env tem várias seções. Preencha cada uma:

Configuração do Site


DOMAIN=crm.seudominio.com
ACME_EMAIL=seu-email@dominio.com
NEXT_PUBLIC_SITE_URL=https://crm.seudominio.com

DOMAIN: O domínio onde o CRM ficará acessível
ACME_EMAIL: Seu email (usado para o certificado SSL)
NEXT_PUBLIC_SITE_URL: URL completa do site

Configuração do Banco de Dados

Gere senhas seguras com o comando abaixo e preencha:


# Gerar senhas (execute e copie o resultado)
openssl rand -base64 24


DB_USER=koda
DB_PASSWORD=cole-a-senha-gerada-aqui
DB_NAME=koda
DB_ROOT_PASSWORD=cole-outra-senha-gerada-aqui
NEXTAUTH_SECRET=cole-outra-senha-gerada-aqui
NEXTAUTH_URL=https://crm.seudominio.com

Importante: Anote essas senhas em local seguro. Você não conseguirá recuperá-las depois.

3.4 Salvar e sair

Pressione Ctrl + X
Pressione Y para confirmar
Pressione Enter para salvar

Passo 4: Iniciar o Sistema


# Construir as imagens da aplicação
docker compose -f docker-compose.yml -f docker-compose.multitenant.yml build \
  migrate web docs api worker telegram-bot platform-web tenant-provisioner
 
# Aplicar as migrações da mesma versão das imagens
docker compose -f docker-compose.yml -f docker-compose.multitenant.yml run --rm migrate
 
# Iniciar os serviços pelo Traefik
docker compose -f docker-compose.yml -f docker-compose.multitenant.yml up -d \
  --no-build --force-recreate web docs api worker platform-web tenant-provisioner waha traefik

Esse comando vai:

Construir as imagens da aplicação
Aplicar as migrações do Prisma
Criar o banco de dados
Configurar o servidor web
Configurar o servidor de email (backup)

Para uma atualização posterior a partir do código local, repita essa mesma sequência. Quando as imagens já tiverem sido publicadas pela CI, pule o build, execute o migrate e use up -d --no-build com o mesmo KODA_VERSION. Não use docker-compose.dev.yml para o acesso pelo Traefik; esse arquivo é apenas para desenvolvimento com portas diretas.

Em uma instalação multi-tenant, o job migrate atualiza somente a base principal configurada em DATABASE_URL. Antes de iniciar imagens que exigem um schema novo, entre no painel administrativo e use Atualizar schema para o sistema afetado (ou a atualização global, após backup e canário). Aguarde a fila concluir no tenant-provisioner; cada base de empresa precisa receber a mesma migração antes de Web e API da nova versão atenderem usuários.

Acompanhar o progresso


docker compose -f docker-compose.yml -f docker-compose.multitenant.yml logs -f

Quando aparecer algo como Started, o sistema está rodando. Pressione Ctrl + C para sair do log.

Passo 5: Verificar se Funcionou

Acesse o sistema no navegador:


https://crm.seudominio.com

Se aparecer a tela de login, a instalação foi bem-sucedida!

Passo 6: Criar sua Conta de Administrador

6.1 Acessar a página de registro

Acesse:


https://crm.seudominio.com/signup

6.2 Preencher o formulário

Nome completo: Seu nome
Email: Seu email
Senha: Uma senha forte (mínimo 8 caracteres)

6.3 Clicar em “Criar Conta”

Pronto! Você já pode fazer login e começar a usar o sistema.

Passo 7: Configurar o WhatsApp

7.1 Criar conta no Meta for Developers

Acesse developers.facebook.com
Crie uma conta de desenvolvedor
Crie um novo aplicativo
Adicione o produto “WhatsApp”

7.2 Configurar no Koda

Faça login no Koda
Acesse Configurações → WhatsApp
Preencha as credenciais do Meta
Configure o webhook

7.3 Testar

Envie uma mensagem para o número do WhatsApp configurado e veja se aparece no painel.

Passo 8: Configurar HTTPS

O Koda usa Let’s Encrypt para obter certificados SSL automáticos. Após a instalação:

Aguarde alguns minutos
Acesse https://crm.seudominio.com
Verifique se o cadeado aparece na barra de endereços

Se o HTTPS não funcionar:

Verifique se o DNS está apontando corretamente
Aguarde até 30 minutos para a primeira configuração
Consulte a seção de Solução de Problemas

Configurações Opcionais

Bot Telegram

Para usar o bot do Telegram:

Crie um bot com @BotFather
Copie o token recebido
Adicione ao arquivo .env:
```
TELEGRAM_BOT_TOKEN=seu-token-aqui
```
O runner legado usa polling e não deve ser iniciado junto com o webhook da API. Para produção, configure uma URL pública HTTPS e use o webhook da API. Para uma migração/local explícita, inicie o profile legado:
```
docker compose --profile legacy-telegram -f docker-compose.yml up -d telegram-bot
```

Backup Automático

O backup já viene configurado por padrão. Os backups são feitos diariamente às 2:00 AM e ficam salvos por 30 dias.

Para alterar a retenção, edite o arquivo .env:


BACKUP_RETENTION_DAYS=30

Próximos Passos

Agora que o sistema está instalado:

Guia do Usuário — Aprenda a usar o sistema
Configurações — Configure o perfil, a equipe e as integrações
Perguntas Frequentes — Tire suas dúvidas

Precisa de Ajuda?

Email: suporte@koda.com.br
WhatsApp: (11) 99999-0000
Horário: Segunda a sexta, das 9h às 18h