docs/quick-start.md # Início rápido: instalação mínima do Welley O caminho mais curto para ter uma instância do Welley rodando em um único host Linux, em qualquer nuvem ou no seu próprio hardware. Ele usa apenas as flags que a CLI realmente exige. Todo o resto fica no padrão. O que você recebe: a plataforma, o pipeline de RAG, Nginx, Redis e um contêiner de PostgreSQL **incluído**, com um certificado Let's Encrypt emitido durante a instalação. Não há banco de dados gerenciado, CDN, telemetria nem integração com o Slack (para esses itens, veja os guias da AWS EC2 e da DigitalOcean). ## 1\. Pré-requisitos **Um host Linux** - Ubuntu 24.04 LTS (ou uma distribuição atual equivalente). - 2 vCPU, 4 GB de RAM e 60 GB de disco como ponto de partida. - Um endereço IPv4 público que não mude. - Portas TCP de entrada **80** e **443** abertas para a internet, e a **22** aberta para você. A porta 80 é necessária durante a instalação, para o desafio do certificado, e depois para a renovação semanal. - Um usuário que não seja root, com `sudo`. O guia executa tudo com esse usuário, chamado abaixo de ``. **DNS** Dois registros, ambos apontando para o IP público do host: | Registro | Finalidade | | --- | --- | | `` | o próprio site | | `storage.` | uploads e arquivos estáticos, porque esta configuração não tem CDN | Crie os dois antes de começar: a CLI verifica se ambos os nomes apontam para este host e interrompe o processo se não apontarem. **Registros DNS de e-mail** O domínio do endereço informado em `--smtp-from` precisa de registros de autenticação de e-mail. Sem eles, Gmail, Outlook e outros grandes provedores costumam descartar mensagens para quem nunca recebeu nada de você. Isso vale para todos os convites e confirmações de cadastro, e o e-mail nem chega à pasta de spam, embora seu provedor de SMTP o informe como enviado. | Registro | Tipo | Valor | | --- | --- | --- | | `` | TXT | SPF, por exemplo `v=spf1 include: ~all`. Use o valor exato indicado pelo seu provedor de SMTP | | `_dmarc.` | TXT | DMARC, por exemplo `v=DMARC1; p=none; rua=mailto:dmarc@` | | `._domainkey.` | TXT ou CNAME | DKIM, gerado pelo seu provedor de SMTP quando você verifica o domínio | Um domínio pode ter apenas um registro SPF. Se ele já tiver um, adicione seu provedor a ele em vez de criar um segundo. O comando `create` avisa se faltar SPF ou DMARC, mas não para. Ele não consegue verificar o DKIM, porque o nome do seletor é específico do seu provedor. Não pule o DKIM. Muitos provedores, entre eles o Amazon SES, enviam por padrão usando o domínio deles como remetente do envelope. Assim, o SPF verifica o domínio do provedor, não o seu, então ele não conta para o DMARC, e só o DKIM pode fazer o DMARC passar. Confira o status do DKIM no console do seu provedor. No Amazon SES, ele fica em _Verified identities_, depois _``_, depois _DKIM_, e precisa estar como _Successful_. O SES Easy DKIM publica três registros CNAME com o nome `._domainkey.`. **Credenciais SMTP** Host, usuário, senha e um endereço de remetente, de qualquer provedor. A plataforma precisa deles para a confirmação por e-mail e a recuperação de senha, e a CLI se recusa a instalar sem eles. Os padrões assumem envio por STARTTLS na porta 587. **Um endereço de e-mail de administrador** para o primeiro acesso e a recuperação de senha. ## 2\. Instalar o Docker Siga as instruções oficiais para a sua distribuição: [Install Docker Engine](https://docs.docker.com/engine/install/). Depois, permita que o seu usuário se comunique com o daemon: ``` sudo usermod -aG docker ``` Saia da sessão e entre de novo, depois confira se as duas partes estão instaladas: ``` docker ps docker compose version ``` ## 3\. Baixar a CLI Escolha o valor de `platform` que corresponde ao seu host: **linux/amd64** ``` curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/amd64" -o wlycli chmod +x wlycli ./wlycli -v ``` **linux/arm64** ``` curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/arm64" -o wlycli chmod +x wlycli ./wlycli -v ``` **darwin/arm64** ``` curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/arm64" -o wlycli chmod +x wlycli ./wlycli -v ``` **darwin/amd64** ``` curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/amd64" -o wlycli chmod +x wlycli ./wlycli -v ``` ## 4\. Implantar ``` ./wlycli deploy create \ -d example.com \ -e admin@example.com \ --smtp-host smtp.example.com \ --smtp-user "$MAIL_USER" \ --smtp-password "$MAIL_PASSWORD" \ --smtp-from noreply@example.com ``` Essas seis flags são todas as obrigatórias. O comando verifica o DNS, grava os arquivos da instalação, emite o certificado com o Certbot e inicia os contêineres. Conte com vários minutos até ele terminar. Padrões que você está aceitando aqui: | Configuração | Padrão | | --- | --- | | Diretório de instalação | `~/.welley/`, em que `` é o domínio com cada caractere não alfanumérico trocado por `_` (assim, `example.com` vira `example_com`) | | Banco de dados | contêiner de PostgreSQL incluído, com os dados dentro do diretório de instalação | | Certificados | Let's Encrypt via Certbot, renovados automaticamente uma vez por semana | | Uploads e arquivos estáticos | servidos de `https://storage.` | | Atualizações | canal `stable`, verificado todo dia e aplicado sem tempo de inatividade, quando possível | ## 5\. Primeiro acesso A senha de administrador gerada é impressa no log da plataforma: ``` docker logs example_com-platform-blue-1 | grep "Auto-init complete" ``` Abra `https://`, entre com o e-mail de administrador que você passou em `-e` e troque a senha imediatamente. Trate o log como segredo até fazer isso. ## 6\. Conferir o resultado ``` docker ps ``` Você deve ver um contêiner para cada um destes serviços: `nginx`, `platform-blue`, `rag-pipeline-blue`, `postgres`, `redis`, `autoheal` e `snoopy`, todos com o nome `--1`. ## Se algo deu errado O comando `create` não roda uma segunda vez enquanto o diretório do projeto ou os contêineres dele existirem. Se os arquivos estiverem certos e só alguns contêineres não tiverem iniciado, recrie esses contêineres sem perder nada: ``` ./wlycli deploy restart -d example.com ``` Se for preciso refazer a instalação em si, remova-a e comece de novo. Isso apaga o banco de dados incluído junto com todo o resto: ``` ./wlycli deploy delete -d example.com --yes-please-delete-all-the-data ``` ## Outros documentos - [**Welley CLI** docs/index.md](https://welley.com/pt/administrators/docs/cli/) - [**Implantar servidor** skills/deploy-server/SKILL.md](https://welley.com/pt/administrators/docs/deploy-server-skill/) - [**openai.yaml** skills/deploy-server/agents/openai.yaml](https://welley.com/pt/administrators/docs/deploy-server-openai-yaml/) - [**Referência da DigitalOcean** skills/deploy-server/references/digitalocean.md](https://welley.com/pt/administrators/docs/deploy-server-digitalocean/)