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<user>.
DNS
Dois registros, ambos apontando para o IP público do host:
| Registro | Finalidade |
|---|---|
<domain> |
o próprio site |
storage.<domain> |
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 |
|---|---|---|
<mail-domain> |
TXT | SPF, por exemplo v=spf1 include:<provider> ~all. Use o valor exato indicado pelo seu provedor de SMTP |
_dmarc.<mail-domain> |
TXT | DMARC, por exemplo v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain> |
<selector>._domainkey.<mail-domain> |
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 <mail-domain>, depois DKIM, e precisa estar como Successful. O SES Easy DKIM publica três registros CNAME com o nome <token>._domainkey.<mail-domain>.
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. Depois, permita que o seu usuário se comunique com o daemon:
sudo usermod -aG docker <user>
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/<project>, em que <project> é 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.<domain> |
| 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://<domain>, 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 <project>-<service>-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