Memorax on-premise — guia do operador

O Memorax on-premise roda o Memorax na sua própria infraestrutura. Seus dados e o acesso ao seu código nunca ficam sob controle de um SaaS: a instância é single-tenant (uma organização), e a IA usa a sua própria chave (BYOK) — o fornecedor nunca tem acesso permanente ao seu git.

Este guia leva você de zero a usando: instalar → licenciar → configurar → primeiro acesso, e depois atualizar, diagnosticar e operar.

1. Requisitos

Um servidor Linux (a maioria dos clientes) com Docker Engine + Docker Compose v2 (docker compose).
openssl e curl (presentes na maioria das distros).
~4 vCPU / 8 GB RAM / 20 GB de disco como ponto de partida (ajuste conforme o volume de documentação).
Uma URL externa pela qual a instância será servida (ex.: https://memorax.suaempresa.com.br), normalmente atrás de um reverse-proxy com TLS (nginx, Caddy, Traefik, Cloudflare, etc.).
Uma chave de IA própria: OpenAI, Anthropic ou OpenRouter (embeddings exigem OpenAI ou OpenRouter).
Uma licença do Memorax (a Memorax te envia o blob).

HTTPS é fortemente recomendado. Em HTTP puro o cookie de sessão cai para SameSite=Lax (login só pelo navegador) e você perde a proteção de transporte. Sirva a instância atrás de um proxy TLS.

2. Instalação

Mais rápido — uma linha (baixa o bundle e instala):

curl -fsSL https://memoraxapp.com.br/get-onprem.sh | EXTERNAL_URL=https://memorax.suaempresa.com.br bash

Ou, passo a passo (baixa o bundle e roda o instalador — você fica com os arquivos para operar depois):

git clone https://github.com/memoraxapp/memorax-onprem.git
cd memorax-onprem
EXTERNAL_URL=https://memorax.suaempresa.com.br ./install.sh

(Alternativa sem git: baixe o .tar.gz em github.com/memoraxapp/memorax-onprem e extraia.)

Fixe a versão com MEMORAX_VERSION=v0.1.0 (env) para uma instalação reprodutível; o default é latest.

O install.sh:

verifica Docker/Compose/openssl/curl;
na 1ª vez, gera um .env com secrets aleatórios (BETTER_AUTH_SECRET, ENCRYPTION_KEY, senha do Postgres, credenciais do MinIO, WORKER_INTERNAL_TOKEN) — é idempotente: reexecuções preservam os secrets;
puxa as imagens da versão pedida do registry público (MEMORAX_VERSION, default latest) — você não precisa do código-fonte;
sobe a stack (perfil bundled: web + worker + Postgres/pgvector + Redis + MinIO embutidos).

Ao terminar, acesse a EXTERNAL_URL. Fixe uma versão no .env (ex.: MEMORAX_VERSION=v0.1.0) para reprodutibilidade — o latest é conveniente, mas muda com o tempo.

3. Primeiro acesso (o operador)

O primeiro usuário a logar vira o operador da instância (administrador). Os demais fazem auto-join na organização única.

Acesse EXTERNAL_URL → faça login (por padrão, link mágico por e-mail).
Sem transporte de e-mail configurado (ver §4.2), o link mágico sai apenas no log do servidor — útil para o primeiríssimo acesso. A URL fica na linha seguinte ao texto "Link mágico para …", então use -A1 (ou extraia direto a URL) e abra no navegador:
```
# mostra o texto + a URL (linha de baixo):
docker compose --profile bundled logs web | grep -A1 "Link mágico" | tail -2
# ou pegue só a URL:
docker compose --profile bundled logs web | grep -oE 'https?://[^ ]+/api/auth/magic-link/verify[^ ]*' | tail -1
```
O link é de uso único e expira em ~15 min; se precisar, peça outro na tela de login.
Depois de logar, você tem acesso a Admin (configurações da instância inteira).

4. Licença

A instância verifica a licença offline (sem rede — nada é enviado à Memorax). Sem licença válida ela degrada: leitura, busca e chat seguem funcionando, mas novas ingestões e a geração de documentação ficam bloqueadas.

Para ativar (ou renovar), escolha um caminho:

A. Pelo Admin (recomendado — sem reiniciar). Em Admin → cartão "Licença da instância", cole o blob recebido da Memorax no campo e salve. A licença passa a valer na hora no web e em ≤60s no worker — nenhum restart necessário.

B. Pela env. Cole o blob em MEMORAX_LICENSE no .env e reinicie:

docker compose --profile bundled up -d --force-recreate web worker

O blob salvo pelo Admin vence a env (a env fica como fallback). O estado da licença (Ativa / Expirada / Inválida / Ausente) aparece no mesmo cartão do Admin, com a validade. Ao expirar, você recebe um aviso; renove pelo mesmo processo.

5. Configuração

Tudo é feito no .env (reinicie os serviços afetados depois de mudar). As chaves principais:

5.1 IA (BYOK)

A IA usa a sua chave — a instância não fala com nenhum SaaS da Memorax para isso.

OPENAI_API_KEY=...        # embeddings exigem OpenAI OU OpenRouter
ANTHROPIC_API_KEY=...
OPENROUTER_API_KEY=...
EMBEDDING_MODEL=text-embedding-3-small

Você também pode configurar as chaves depois de subir, em Admin → Modelos.

5.2 E-mail (link mágico, convites)

Sem transporte, o link mágico sai só no log (bom para o 1º acesso). Para envio real:

EMAIL_TRANSPORT=resend            # ou: smtp
EMAIL_FROM=memorax@suaempresa.com.br
# Resend:
RESEND_API_KEY=...
# SMTP (relay interno):
SMTP_HOST=...
SMTP_PORT=587
SMTP_USER=...
SMTP_PASS=...
SMTP_SECURE=false                 # true para TLS implícito (porta 465)

5.3 Métodos de login

AUTH_MAGIC_LINK_ENABLED=true      # link mágico (precisa de transporte de e-mail)
AUTH_PASSWORD_ENABLED=false       # e-mail + senha local

Ligue os que fizer sentido (pelo menos um). Trocar exige reiniciar o web.

Com a senha local ligada, a tela de login mostra "Esqueci minha senha": o usuário recebe um link por e-mail e escolhe a nova senha. Depende do transporte de e-mail da seção 5.2 estar configurado — sem transporte, o link não sai e a única recuperação é o operador trocar a senha pelo banco.

5.4 Postgres / Redis / S3 gerenciados (externos)

Para usar serviços gerenciados em vez dos embutidos:

no .env, aponte DATABASE_URL (garanta a extensão vector no banco — o Postgres embutido já a traz), REDIS_URL e S3_ENDPOINT/AWS_*/S3_BUCKET para os externos;
suba sem o perfil bundled: docker compose up -d.
defina MEMORAX_BACKUP=off (o backup/PITR do banco passa a ser sua responsabilidade).

6. Usar o Memorax

Depois de licenciada e com uma chave de IA, a instância funciona como o Memorax que você conhece: ingerir fontes, documentar repositórios de código, chat com a wiki, sweep, etc.

Publicar uma wiki como site de documentação: publique um espaço pela UI; no on-prem a publicação é servida por caminho, em EXTERNAL_URL/publicado/{projeto}/... (público ou protegido, conforme você escolher).

7. Atualização

A atualização é orquestrada e com rede de proteção (há um breve downtime durante a migração — priorizamos segurança sobre zero-downtime):

MEMORAX_VERSION=v0.2.0 ./upgrade.sh

O upgrade.sh: puxa a nova versão → para o app → faz backup (pg_dump; pulável só no modo externo com PITR) → roda a migração dedicada → sobe os serviços novos → health-check. Se o health-check falhar, restaura o banco do backup e volta à versão anterior, e aborta.

A instância avisa o operador quando há uma versão nova disponível (banner; desligável com MEMORAX_UPDATE_CHECK=off — nenhuma chamada de saída é feita então).

8. Diagnóstico (para o suporte)

./diagnose.sh

Gera um arquivo local e redigido (diagnose-<data>.txt) com status dos serviços, versões, config sem secrets (senhas/chaves/tokens mascarados) e um trecho dos logs. Nada é enviado automaticamente — você revisa e manda para o suporte se quiser.

9. Backup e restauração

Backup do banco (Postgres embutido):
```
docker compose --profile bundled exec -T postgres pg_dump -U memorax memorax > backup.sql
```
(O upgrade.sh já faz isso automaticamente antes de migrar, em ./backups/.)

Restaurar (banco limpo):

docker compose --profile bundled exec -T postgres psql -U memorax -d postgres \
  -c "DROP DATABASE IF EXISTS memorax WITH (FORCE);" -c "CREATE DATABASE memorax;"
docker compose --profile bundled exec -T postgres psql -U memorax -d memorax < backup.sql

Objetos (uploads): ficam no volume do MinIO embutido (ou no seu S3 externo). Inclua os volumes Docker (memorax-onprem_*) na sua rotina de backup, ou use serviços externos com backup próprio.

10. Troubleshooting / FAQ

Sintoma	Causa provável	Ação
Login não completa / redireciona errado	`EXTERNAL_URL` não bate com o endereço real (atrás do proxy)	Ajuste `EXTERNAL_URL` para a URL que os usuários acessam e reinicie o `web`.
Cookie de sessão não persiste	Servindo em HTTP puro	Use HTTPS atrás de um proxy TLS.
Link mágico não chega	Sem `EMAIL_TRANSPORT` configurado	Configure Resend/SMTP (§5.2), ou pegue o link no log do `web`.
Novas ingestões/geração bloqueadas	Licença ausente/expirada (degrade)	Configure uma licença válida pelo Admin ou pela env (§4).
Migração falha no Postgres externo: `vector` ausente	Sem privilégio para criar a extensão	Pré-crie no banco (como superuser): `CREATE EXTENSION vector;`
Conflito de porta ao subir	Portas 3000/9000/9001 em uso	Defina `WEB_PORT`/`MINIO_PORT`/`MINIO_CONSOLE_PORT` no `.env`.
Upgrade abortou e reverteu	Health-check não passou	Veja `docker compose logs web`; corrija e rode o `upgrade.sh` de novo.

Logs:

docker compose --profile bundled logs -f web       # servidor
docker compose --profile bundled logs -f worker    # filas (ingestão, sweep, etc.)

Suporte: rode ./diagnose.sh e envie o arquivo gerado (já redigido) junto da descrição do problema.

Notas

A instância é single-tenant: uma organização, o 1º usuário é o operador.
A IA é BYOK: a instância chama a IA sob a sua chave; o código do cliente é enviado à IA pública do provedor escolhido (não é air-gap). O que se garante é que o fornecedor nunca tem acesso permanente ao seu git.
O app desktop não é oferecido on-prem; use pelo navegador.