Instalação

Este guia instala a Community Edition passo a passo, com os motivos por trás de cada etapa. É o mesmo fluxo do Início rápido, mais serviços gerenciados, segredos, armazenamento e proteção da instalação. Na stack do Compose incluída, a maioria das etapas não exige nenhuma ação: leia-as para saber o que acontece e o que mudar depois.

1. Clonar e configurar

git clone https://github.com/nodaroai/app.nodaro.ai.git nodaro
cd nodaro

Na stack do Compose da Community Edition, o .env é opcional. O arquivo do Compose inclui o Supabase, o MinIO e o Redis com padrões que funcionam. Crie um .env só para adicionar chaves de provedor, mudar a URL pública ou apontar o Nodaro para os seus próprios serviços gerenciados.

Para criar um, copie o exemplo feito para a stack do Compose:

cp .env.community.example .env

Os valores que você provavelmente vai definir:

PUBLIC_URL=http://localhost:3000        # your install's public address

# Only with a managed Supabase project instead of the bundled one:
SUPABASE_URL=https://YOUR-PROJECT.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
SUPABASE_ANON_KEY=eyJ...

# At least one model provider:
KIE_API_KEY=
REPLICATE_API_TOKEN=
ANTHROPIC_API_KEY=
ELEVENLABS_API_KEY=

O arquivo do Compose passa uma lista fixa de variáveis para o app. Uma variável que não está nessa lista precisa ser adicionada ao serviço nodaro no docker-compose.community.yml. A página Configuração lista todas as variáveis e diz quais delas o .env pode definir.

2. Gerar os segredos internos

O Nodaro usa dois segredos próprios:

Na stack do Compose incluída, pule esta etapa. O contêiner gera os dois na inicialização. Ele salva a chave de criptografia no volume app-data, em /data/nodaro/encryption-key, e a reutiliza em todas as inicializações seguintes. Faça backup desse volume junto com o banco de dados.

Na sua própria orquestração, como uma plataforma de hospedagem ou contêineres separados, defina os dois você mesmo:

echo "INTERNAL_ORCHESTRATOR_SECRET=$(openssl rand -hex 32)" >> .env
echo "NODARO_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

Guarde a NODARO_ENCRYPTION_KEY em segurança e nunca a altere: tudo o que ela criptografou fica ilegível com outra chave.

3. Aplicar as migrações do banco de dados

Na stack incluída, isso é automático. Na inicialização, o app aplica os arquivos de supabase/migrations/ antes de a API iniciar. Ele lembra quais arquivos já aplicou e os pula na inicialização seguinte. Ele se recusa a iniciar com um banco de dados migrado pela metade, e o log dele indica o arquivo que falhou.

Com um projeto gerenciado no Supabase, defina RUN_MIGRATIONS_ON_BOOT=false e aplique as migrações você mesmo. Veja Banco de dados.

4. Configurar o armazenamento de objetos

O MinIO incluído

Não há nada para configurar. O arquivo do Compose traz o MinIO com estes padrões:

O servidor web do app serve a mídia em /storage/, então o navegador e o backend leem a mesma URL. O bucket é criado na primeira inicialização, com acesso público de leitura. A mídia fica no volume minio-data.

Quando servir a instalação em um domínio real, defina R2_PUBLIC_URL=https://<your-domain>/storage/nodaro-assets. Mude as credenciais do MinIO, R2_ACCESS_KEY_ID e R2_SECRET_ACCESS_KEY, antes de expor a stack.

Cloudflare R2

O Cloudflare R2 é o recomendado para implantações reais, porque não cobra taxas de saída de dados.

1. Crie um bucket, por exemplo nodaro-assets, e defina R2_BUCKET_NAME com o nome dele.
2. Na aba Settings do bucket, ative o endereço público r2.dev ou associe um domínio personalizado. Copie essa URL para R2_PUBLIC_URL.
3. Em Manage R2 API tokens, crie um token com a permissão Object Read & Write neste bucket. Copie os valores dele para R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY e R2_ACCOUNT_ID.
4. Na stack do Compose, defina também o endpoint e o estilo de endereçamento:

R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
R2_FORCE_PATH_STYLE=false

Um valor vazio não limpa essas duas variáveis: para uma variável vazia, o arquivo do Compose volta aos padrões do MinIO. Fora da stack do Compose, deixe as duas sem definir, e o endpoint é derivado de R2_ACCOUNT_ID.

Na inicialização, o log mostra uma linha [storage] failed to create bucket, que é inofensiva. Os tokens do R2 não podem criar buckets, e o seu já existe.

Outros armazenamentos compatíveis com S3

Para AWS S3, Backblaze B2, DigitalOcean Spaces, Supabase Storage ou o seu próprio MinIO:

• Defina R2_ENDPOINT como a URL da API S3 do armazenamento.
• Defina R2_FORCE_PATH_STYLE=true para a maioria dos servidores self-hosted.
• Defina R2_PUBLIC_URL como a URL pública do bucket.
• Defina R2_REGION como a região do armazenamento, a menos que ele seja o Cloudflare R2 ou o MinIO.

O padrão de R2_REGION é auto, o valor próprio do Cloudflare R2, que o MinIO ignora. A AWS, o DigitalOcean Spaces (nyc3, fra1 e outros) e um Supabase local (local) rejeitam auto. Nesse caso, toda requisição falha com um erro de autorização ou de endpoint que não menciona a região.

Tornar a mídia legível publicamente

Há duas formas, e a maioria das instalações só precisa da primeira:

1. Uma política de bucket. É o padrão. Com um R2_ENDPOINT personalizado, o app cria o bucket na inicialização e dá a ele uma política de leitura anônima. O Cloudflare R2 não precisa dela: a configuração de bucket público dele já cobre isso.
2. Uma ACL por objeto, com STORAGE_OBJECT_ACL. Para armazenamentos que recusam uma política de bucket. O DigitalOcean Spaces é o caso comum: ele recusa uma política de bucket vinda de uma chave restrita a um único bucket. Defina STORAGE_OBJECT_ACL=public-read, e todo objeto que o app grava leva essa ACL.

Deixe STORAGE_OBJECT_ACL vazia, a menos que precise da segunda forma. Quando ela está vazia, nenhum cabeçalho de ACL é enviado. Quando ela está definida em um armazenamento cujas chaves não têm permissão para definir ACLs, todo upload falha. O Nodaro aceita as ACLs pré-configuradas padrão — private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read e bucket-owner-full-control — e recusa qualquer outro valor na inicialização.

5. Iniciar a stack

docker compose -f docker-compose.community.yml up

A imagem do app, ghcr.io/nodaroai/nodaro-community, é baixada pré-compilada. A primeira inicialização baixa cerca de 2,4 GB, em vez de compilar por 5 a 10 minutos, e as inicializações seguintes levam segundos. Os logs do Redis e do serviço nodaro aparecem lado a lado. Quando você vir esta linha, a API está no ar:

nodaro-1  | server listening on http://0.0.0.0:9000

O servidor web, no mesmo contêiner, a disponibiliza na porta 3000. Abra http://localhost:3000.

A tag latest acompanha a branch main. Para fixar uma versão e ter uma instalação reproduzível, defina NODARO_IMAGE no .env, por exemplo NODARO_IMAGE=ghcr.io/nodaroai/nodaro-community:v1.23.0. A página Atualização lista todas as tags.

Para, em vez disso, compilar a imagem a partir do código-fonte, rode docker compose -f docker-compose.community.yml build. Você só precisa disso quando altera o código. A URL pública, a porta, o domínio e as chaves do Supabase são lidos quando o contêiner inicia, então a imagem publicada passa a usá-los depois de uma reinicialização.

6. Fazer login pela primeira vez

Crie uma conta no app com um endereço de e-mail e uma senha. O serviço de login cria o usuário, e o Nodaro cria o perfil do usuário automaticamente. Na stack incluída, nenhum e-mail de confirmação é enviado.

Os usuários da Community Edition não têm restrições: não há registro de créditos nem painel de administração. Na Business edition, promova o seu primeiro administrador em seguida: veja Primeiro usuário e administrador.

Proteger a instalação antes de expô-la

Os padrões do Compose foram feitos para uso local e são públicos por definição. Antes que outras pessoas possam acessar a instalação:

node tools/generate-selfhost-keys.mjs >> .env

POSTGRES_PASSWORD=<new-password>
DATABASE_URL=postgres://postgres:<new-password>@db:5432/postgres

Aplique cada alteração com docker compose -f docker-compose.community.yml up -d e depois verifique /setup.