Elido su k3s: cosa distribuisce (e cosa no) il chart Helm

Elido distribuisce un chart Helm che installa l'intero stack su un solo cluster Kubernetes, e questo articolo lo percorre su un singolo nodo k3s. Prima dei comandi, la parte che decide se continuare a leggere: Elido non è open source e il self-hosting non è un prodotto che vendiamo. Il repository non ha un file di licenza, quindi nessuno al di fuori dell'azienda ha la licenza per eseguirlo o modificarlo. Il chart è uno strumento di distribuzione che teniamo nel repo, e i comandi qui sotto vengono da lì e dal runbook accanto (consultato il 2026-10-25). Usa questa guida se lavori su Elido, se hai un accordo scritto con noi o se vuoi vedere esattamente cosa comporta eseguire la piattaforma.

Se stai ancora scegliendo tra progetti che puoi davvero scaricare, parti dal confronto degli shortener self-hosted. Copre YOURLS, Shlink, Kutt e Dub e non ripete nessuno dei passaggi qui.

Cos'è il chart, e cosa non è

Il chart sta in deploy/helm/elido. I suoi metadati puntano a un repository GitHub sotto l'organizzazione elidoapp; una richiesta non autenticata a quell'indirizzo ha restituito 404 il 2026-10-25, quindi non aspettarti di clonarlo da internet. Il file di values scarica le immagini da ghcr.io/elidoapp, e un commento al suo interno chiama pubblico il registry. Non ho potuto confermare i pull anonimi, quindi consideralo non verificato.

Il chart è anche giovane. La sua versione è 0.1.0, e la sua stessa descrizione chiama l'obiettivo "single-region k3s cluster on a beefy VM". Mancano alcune cose che la gente presume arrivino con un chart Kubernetes, e una versione precedente di questo articolo ne descriveva a torto alcune:

• Nessuna alta disponibilità. Ogni stateful set gira con una replica.
• Nessun job di backup. Lo dice il runbook, che ti indica di usare Velero, k8up o gli snapshot del provider.
• Nessun oggetto di monitoraggio, dashboard o autoscaler.
• Nessun edge multi-regione. Il preset riunisce i reindirizzamenti in un'unica flotta.

Se un'autorità o la tua policy richiedono queste cose, metti a budget il lavoro per aggiungerle tu.

Cosa distribuisce il preset self-host

values-selfhost.yaml riduce tutto per stare in un host da 4 core e 8 GB. Esegue una replica di ogni workload applicativo: api-core, analytics-api, click-ingester, url-scanner, notification, bio-renderer, billing, la dashboard (web), il sito marketing e una flotta edge che risponde per ogni host. Un servizio di identità gestisce registrazione e sessioni.

Dietro ci sono sei stateful set con volumi persistenti: Postgres (20Gi nel preset), Redis (2Gi), un archivio a colonne per gli eventi di click (30Gi), un bus di eventi (10Gi), object storage (20Gi) e un indice di ricerca (5Gi). Qui Redis è una singola istanza con persistenza append-only, non un cluster. Diversi servizi che prima erano separati, tra cui gestione dei domini, consegna dei webhook e indicizzazione della ricerca, ora girano dentro api-core, ed è per questo che l'elenco dei workload è più corto di quanto suggeriscano i vecchi documenti.

Prerequisiti

Il runbook richiede Kubernetes 1.27 o successivo, Helm 3.13 o successivo e kubectl puntato al cluster. Ti servono anche record DNS per gli hostname di dashboard, API, reindirizzamento e bio, un relay SMTP raggiungibile dal cluster e un ingress controller di classe caddy.

k3s include Traefik, che si contenderebbe le porte 80 e 443 con il controller che stai per installare. Disabilitalo quando installi k3s:

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable traefik" sh -
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $UID ~/.kube/config
kubectl get nodes   # should show Ready

Installazione, passo per passo

Crea il namespace e genera i secret. Lo script produce valori casuali per la password del database, le chiavi di cookie e cifratura del servizio di identità, la chiave di offuscamento degli slug e il pepper delle chiavi API, e crea dei placeholder per SMTP e LiqPay. Salta i secret già esistenti a meno che tu non passi --rotate.

kubectl create namespace elido
./deploy/helm/elido/scripts/bootstrap-secrets.sh elido

Lo script stampa la password di Postgres alla fine. Salvala. Poi sostituisci il placeholder SMTP prima che qualcuno si registri; lo stesso schema vale per elido-liqpay se accetti pagamenti:

kubectl -n elido create secret generic elido-smtp \
  --from-literal=host=smtp.example.com \
  --from-literal=port=587 \
  [email protected] \
  --from-literal=pass=YOUR_SMTP_KEY \
  --from-literal=kratos_uri='smtps://postmaster%40your-domain.com:[email protected]:465/?disable_starttls=false' \
  --dry-run=client -o yaml | kubectl apply -f -

Installa l'ingress controller con il TLS on-demand attivato:

helm repo add caddy https://caddyserver.github.io/charts
helm -n caddy-system upgrade --install caddy caddy/caddy-ingress-controller \
  --create-namespace --set controller.config.onDemandTLS=true

Ora installa Elido stesso. Fissa image.tag a una release che hai scelto. L'esempio del runbook usa latest, il che rende difficile ragionare su aggiornamenti e rollback.

helm -n elido upgrade --install elido ./deploy/helm/elido \
  -f ./deploy/helm/elido/values-selfhost.yaml \
  --set image.tag=YOUR_TAG \
  --set ingress.hosts.dashboard=app.your-domain.com \
  --set ingress.hosts.api=api.your-domain.com \
  --set ingress.hosts.bio=bio.your-domain.com \
  --set 'ingress.hosts.redirect={r.your-domain.com}' \
  --set ingress.hosts.marketing=your-domain.com \
  --set auth.kratos.publicHost=app.your-domain.com
kubectl -n elido get pods -w

Le migrazioni girano come init container per i servizi che ne hanno bisogno e come job di pre-install per il servizio di identità. Se una migrazione fallisce, i nuovi pod non ricevono mai traffico.

Primo utente e domini personalizzati

Apri https://app.your-domain.com/signup e registrati. Il servizio di identità crea l'account e api-core memorizza una riga utente. Nulla rende ancora quell'utente un owner, quindi crea a mano un workspace e una membership, che è ciò che dicono di fare le note di installazione del chart stesso:

kubectl -n elido exec -it sts/postgres -- psql -U elido -d elido <<'SQL'
INSERT INTO workspaces (slug, name, plan_tier)
VALUES ('default', 'Default', 'business') RETURNING id;
INSERT INTO workspace_members (workspace_id, user_id, role)
SELECT 1, id, 'owner' FROM users WHERE email = '[email protected]';
SQL

I domini personalizzati usano il TLS on-demand. Un cliente aggiunge links.brand.com nella dashboard, poi punta un CNAME all'host che hai impostato in EDGE_CNAME_TARGET (una variabile di api-core che per impostazione predefinita è l'hostname edge di Elido stesso, quindi cambiala). Alla prima richiesta HTTPS l'ingress controller chiama GET /v1/caddy/ask su api-core. Un 200 emette il certificato; un 403 significa che il dominio non è verificato. Fai debug con kubectl -n elido logs deploy/api-core | grep caddy/ask.

Backup, aggiornamenti e rollback

I backup sono tuoi. L'indicazione del runbook è snapshot giornalieri del volume di Postgres (data-postgres-0) e settimanali per l'archivio a colonne (data-clickhouse-0), dato che i dati dei click si possono rieseguire dal bus di eventi entro la sua finestra di conservazione. Il volume del bus di eventi non richiede backup. Per usare un Postgres gestito, imposta postgres.enabled=false e punta l'url del secret elido-postgres a quello. Esegui un ripristino in un namespace di prova prima di fare affidamento su tutto questo.

Gli aggiornamenti sono un solo comando con un nuovo tag:

helm -n elido upgrade elido ./deploy/helm/elido \
  -f ./deploy/helm/elido/values-selfhost.yaml --set image.tag=NEW_TAG

Gli aggiornamenti rolling usano maxSurge: 1 e maxUnavailable: 0, e helm -n elido rollback elido <revision> riporta indietro i Deployment senza toccare volumi o secret. Con una replica per servizio, aspettati brevi interruzioni sui workload che non sono stateless.

Problemi noti

Se il motivo per cui sei qui è un DPO, l'opzione ospitata potrebbe già bastare: i suoi dati primari sono nell'UE, e la guida alla residenza UE elenca cosa viene elaborato fuori. Per il lato della latenza nel gestire in proprio i reindirizzamenti, vedi l'articolo sugli edge POP.

Correlati sul blog

• URL shortener self-hosted a confronto
• Alternative a Bitly e il divario di funzioni
• Raggiungere un p95 sotto i 15ms nei reindirizzamenti
• Residenza dei dati UE per gli strumenti di marketing
• Edge POP contro routing solo DNS