Avvio rapido: installazione minima di Welley
Il percorso più breve per avere un'istanza Welley in funzione su un singolo host Linux, su qualsiasi cloud o sul tuo hardware. Usa solo i flag che la CLI richiede davvero; tutto il resto resta sui valori predefiniti.
Cosa ottieni: la piattaforma, la pipeline RAG, Nginx, Redis e un container PostgreSQL incluso, con un certificato Let's Encrypt emesso durante l'installazione. Niente database gestito, niente CDN, niente telemetria o integrazione con Slack: per questi trovi le guide per AWS EC2 e DigitalOcean.
1. Prerequisiti
Un host Linux
- Ubuntu 24.04 LTS (o una distribuzione recente equivalente).
- 2 vCPU, 4 GB di RAM, 60 GB di disco come punto di partenza.
- Un indirizzo IPv4 pubblico che non cambia.
- Le porte TCP in entrata 80 e 443 aperte da internet, e la 22 aperta per te. La porta 80 serve durante l'installazione per la verifica del certificato e in seguito per il rinnovo settimanale.
- Un utente non root con
sudo: la guida esegue tutto con quell'utente, indicato più sotto come<user>.
DNS
Due record, entrambi che puntano all'IP pubblico dell'host:
| Record | Scopo |
|---|---|
<domain> |
il sito stesso |
storage.<domain> |
upload e file statici, perché questa configurazione non ha una CDN |
Creali prima di iniziare: la CLI controlla che entrambi i nomi puntino a questo host e si ferma se non è così.
Record DNS per le email
Il dominio del tuo indirizzo --smtp-from ha bisogno di record di autenticazione email. Senza, Gmail, Outlook e altri grandi provider spesso scartano i messaggi diretti a chi non ha mai ricevuto nulla da te. Questo vale per ogni invito e ogni conferma di iscrizione: la mail non finisce nemmeno nello spam, anche se il tuo provider SMTP la segna come inviata.
| Record | Tipo | Valore |
|---|---|---|
<mail-domain> |
TXT | SPF, per esempio v=spf1 include:<provider> ~all. Prendi il valore esatto dal tuo provider SMTP |
_dmarc.<mail-domain> |
TXT | DMARC, per esempio v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain> |
<selector>._domainkey.<mail-domain> |
TXT o CNAME | DKIM, generato dal tuo provider SMTP quando verifichi il dominio |
Un dominio può avere un solo record SPF. Se ne ha già uno, aggiungi il tuo provider a quello invece di crearne un secondo. create ti avvisa se SPF o DMARC mancano, ma non si ferma. Non può controllare DKIM, perché il nome del selettore dipende dal tuo provider.
Non saltare DKIM. Molti provider, Amazon SES compreso, inviano per impostazione predefinita con il proprio dominio come mittente della busta. SPF allora controlla il dominio del provider e non il tuo, quindi non conta per DMARC, e solo DKIM può far passare DMARC. Controlla lo stato di DKIM nella console del tuo provider. In Amazon SES lo trovi in Verified identities, poi <mail-domain>, poi DKIM, e deve indicare Successful. SES Easy DKIM pubblica tre record CNAME chiamati <token>._domainkey.<mail-domain>.
Credenziali SMTP
Host, utente, password e un indirizzo mittente, da un provider qualsiasi. La piattaforma ne ha bisogno per la conferma via email e il recupero della password, e senza di esse la CLI si rifiuta di procedere con l'installazione. I valori predefiniti prevedono l'invio con STARTTLS sulla porta 587.
Un indirizzo email per l'admin, per il primo accesso e per il recupero della password.
2. Installa Docker
Segui le istruzioni ufficiali per la tua distribuzione: Install Docker Engine. Poi permetti al tuo utente di comunicare con il daemon:
sudo usermod -aG docker <user>
Esci e rientra, poi controlla che entrambe le parti siano a posto:
docker ps
docker compose version
3. Scarica la CLI
Scegli il valore di platform che corrisponde al tuo 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. Installa
./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
Questi sei flag sono tutti quelli richiesti. Il comando controlla il DNS, scrive i file dell'installazione, emette il certificato con Certbot e avvia i container; ci vorranno alcuni minuti.
I valori predefiniti che accetti qui:
| Impostazione | Valore predefinito |
|---|---|
| Cartella di installazione | ~/.welley/<project>, dove <project> è il dominio con ogni carattere non alfanumerico sostituito da _ (quindi example.com diventa example_com) |
| Database | container PostgreSQL incluso, con i dati nella cartella di installazione |
| Certificati | Let's Encrypt tramite Certbot, rinnovati automaticamente una volta a settimana |
| Upload e file statici | serviti da https://storage.<domain> |
| Aggiornamenti | canale stable, controllati ogni giorno e applicati senza interruzioni quando possibile |
5. Primo accesso
La password generata per l'admin viene scritta nel log della piattaforma:
docker logs example_com-platform-blue-1 | grep "Auto-init complete"
Apri https://<domain>, accedi con l'email dell'admin che hai passato con -e e cambia subito la password. Finché non l'hai fatto, considera il log riservato.
6. Controlla il risultato
docker ps
Dovresti vedere un container ciascuno per nginx, platform-blue, rag-pipeline-blue, postgres, redis, autoheal e snoopy, tutti con nome <project>-<service>-1.
Se qualcosa è andato storto
create non parte una seconda volta finché esistono la cartella del progetto o i suoi container. Se i file sono a posto e solo alcuni container non si sono avviati, ricreali senza perdere nulla:
./wlycli deploy restart -d example.com
Se l'installazione stessa va rifatta, rimuovila e ricomincia da capo. Così elimini il database incluso insieme a tutto il resto:
./wlycli deploy delete -d example.com --yes-please-delete-all-the-data