Intermediário PaperclipAI Paperclip Tutorial

PaperclipAI - Instalação e Configuração em Docker para Produção

21 de abril de 2026

Tutorial completo para implantar o PaperclipAI em ambiente de produção usando Docker, configurar banco de dados PostgreSQL, cache Redis e criar o usuário administrador inicial de forma segura.

PaperclipAI - Instalação e Configuração em Docker para Produção

O que você vai aprender na instalação do PaperclipAI com Docker

Como configurar um ambiente Docker Compose com PaperclipAI, PostgreSQL e Redis

A configurar corretamente volumes persistentes e variáveis de ambiente críticas

A iniciar a aplicação em modo de produção com autenticação obrigatória

A criar o primeiro usuário administrador (CEO) via linha de comando

A acessar a interface, configurar chaves de API e bloquear cadastros não autorizados

Pré-requisitos para instalar PaperclipAI com Docker

Conta no GitHub para acessar o repositório oficial, se necessário

Conhecimento básico de terminal/CLI e conceitos de Docker

Acesso a um servidor (VPS, local ou cloud) com recursos suficientes para rodar os contêineres

Chaves de API de serviços de LLM (OpenAI, Anthropic, etc.) para configurar após a instalação

Ferramentas necessárias para configurar PaperclipAI

Docker Engine e Docker Compose

Git (opcional, para clonar o repositório)

Um navegador web moderno

Passo a passo para instalar PaperclipAI com Docker em produção

Passo 1: Preparar o ambiente e o arquivo docker-compose.yml

Crie um diretório dedicado para o projeto (ex: paperclip-prod) e, dentro dele, um arquivo chamado docker-compose.yml. Este arquivo define os três serviços necessários: a aplicação PaperclipAI, o banco de dados PostgreSQL e o cache Redis. A configuração abaixo já inclui as definições de volumes e rede recomendadas.

YAML

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: paperclip-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: seu_senha_forte_aqui
      POSTGRES_DB: paperclip
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - paperclip-net

  redis:
    image: redis:7-alpine
    container_name: paperclip-redis
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - paperclip-net

  paperclip:
    image: ghcr.io/paperclipai/paperclip:latest
    container_name: paperclip-app
    restart: unless-stopped
    depends_on:
      - postgres
      - redis
    environment:
      # CONFIGURAÇÕES CRÍTICAS:
      PAPERCLIP_DEPLOYMENT_MODE: authenticated
      DATABASE_URL: postgresql://paperclip:seu_senha_forte_aqui@postgres:5432/paperclip
      REDIS_URL: redis://redis:6379
      # (Configurações adicionais, como NODE_ENV, podem ser adicionadas aqui)
    ports:
      - "3000:3000"
    volumes:
      # REGRA DE OURO: Mapeie APENAS para /paperclip/
      - paperclip_data:/paperclip
    networks:
      - paperclip-net

volumes:
  postgres_data:
  redis_data:
  paperclip_data:

networks:
  paperclip-net:
    driver: bridge

Passo 2: Configurar variáveis de ambiente e iniciar os containers

Primeiro, edite o arquivo docker-compose.yml e substitua seu_senha_forte_aqui por uma senha segura e complexa para o PostgreSQL. A variável PAPERCLIP_DEPLOYMENT_MODE=authenticated já está definida, garantindo que o acesso à aplicação exija autenticação. Agora, inicie os containers em segundo plano:

BASH

docker compose up -d

Espere alguns instantes e verifique se todos os serviços estão saudáveis com:

BASH

docker compose ps

A saída deve mostrar os três containers com status Up.

Passo 3: Bootstrapping - Criar o primeiro usuário administrador (CEO)

Como a aplicação está em modo authenticated e não possui tela de registro público, é necessário criar o primeiro usuário via linha de comando. Execute o comando de bootstrap dentro do container da aplicação. Note o uso de gosu node, essencial para executar como o usuário não-root correto.

BASH

docker exec -it paperclip-app gosu node pnpm paperclipai auth bootstrap-ceo

Este comando gerará um link de convite único no terminal. Copie este URL completo. A saída será semelhante a:

✅ Convite de CEO criado com sucesso. 👉 Utilize o seguinte link para finalizar o cadastro: http://localhost:3000/auth/accept-invite?token=eyJhbGciOiJ...

Passo 4: Acessar a interface e completar a configuração

Abra o link copiado no passo anterior em seu navegador.

Complete o formulário de registro para criar sua conta de administrador (CEO).

Após o login, navegue até a seção de configurações (Settings) ou API Keys no painel administrativo.

Insira as chaves de API dos provedores de LLM que você deseja utilizar (ex: OpenAI, Anthropic, Google Gemini). Sem essas chaves, a funcionalidade principal de IA não irá funcionar.

Passo 5: Bloqueio de segurança pós-instalação

Para evitar que novos usuários se cadastrem sem um convite explícito (após você ter criado sua equipe), é altamente recomendável desabilitar o cadastro aberto. Adicione a seguinte variável de ambiente ao serviço paperclip no seu docker-compose.yml:

YAML

  paperclip:
    ...
    environment:
      PAPERCLIP_DEPLOYMENT_MODE: authenticated
      DATABASE_URL: ...
      REDIS_URL: ...
      PAPERCLIP_AUTH_DISABLE_SIGN_UP: "true" # Adicione esta linha
    ...

Em seguida, aplique a alteração reiniciando o container da aplicação:

BASH

docker compose up -d --force-recreate paperclip

A partir de agora, apenas usuários com links de convite gerados por um administrador (via interface ou comando) poderão se cadastrar.

Dicas e variações para configurar PaperclipAI com Docker

Persistência é Fundamental: Os volumes definidos (postgres_data, redis_data, paperclip_data) são essenciais. Sem eles, todos os dados (conversas, configurações, vetores) serão perdidos ao remover os containers. Faça backup regular desses volumes.

Erro Comum de Permissão: Se encontrar erros de permissão ao escrever no volume /paperclip, nunca force o uso do usuário root no container. A aplicação foi projetada para rodar como node. Verifique se o comando gosu node foi usado em qualquer execução interativa, como feito no Passo 3.

Customização de Porta: Para expor a aplicação em uma porta diferente da 3000, altere o mapeamento no serviço paperclip no docker-compose.yml (ex: "8080:3000").

Usando um Proxy Reverso (Nginx/Caddy): Em produção, é comum colocar o PaperclipAI atrás de um proxy reverso com SSL. Nesse caso, você pode remover o mapeamento de porta "3000:3000" e conectar o container do proxy à rede paperclip-net.

Atualização: Para atualizar para a versão mais recente da imagem, execute:

bash docker compose pull paperclip docker compose up -d --force-recreate paperclip

Conclusão da instalação do PaperclipAI em Docker

Você agora tem uma instância completa do PaperclipAI rodando em produção usando Docker. A stack com PostgreSQL para dados, Redis para cache e a aplicação Node.js/React está configurada com segurança, autenticação obrigatória e cadastro controlado por convite. O próximo passo é explorar a documentação oficial do PaperclipAI para configurar agentes, conectar fontes de dados e integrar com suas ferramentas de trabalho. Navegue pelas configurações do painel administrativo para ajustes finos e adicione os membros da sua equipe através do sistema de convites.