Saltar al contingutCECO LabDigital lab / web engineering
NRS Home Server

Guia / Self-hosting web

Com publicar webs estàtiques i apps Node amb Caddy i GitHub

Autoallotjar una web no és només copiar fitxers a un PC. Hi ha quatre peces diferents: el build que produeix el contingut, el procés que el serveix localment, la frontera pública HTTPS i el mecanisme que actualitza una revisió per una altra. Separar aquestes peces fa més fàcil diagnosticar errors i evita exposar serveis interns que no haurien de ser públics.

Autoria editorial · CECO LabActualitzat · 02/10/2026Caddy · Node · GitHub

Primer separa les quatre responsabilitats

Build

Una web estàtica pot generar HTML/CSS/JS en una carpeta de sortida; una app Node necessita codi, dependències i un entrypoint que es manté en execució.

Servei local

Els fitxers estàtics necessiten un file server. Una app Node ha d'escoltar en una adreça i port controlats, preferiblement loopback si Caddy és l'única entrada pública.

Frontera pública

Caddy rep el domini, termina HTTPS i decideix si serveix fitxers o envia la petició al procés Node. El panell d'administració no ha de compartir aquesta superfície per defecte.

Actualització

GitHub pot ser la font de codi i un runner self-hosted pot executar build, proves i desplegament, però l'actualització és una operació distinta de mantenir el servei viu.

Caddy: fitxers estàtics i reverse proxy són dos casos diferents

Per a una web estàtica, Caddy pot servir directament una arrel de fitxers amb file_server. Per a Node, la pràctica habitual és deixar l'aplicació en un port local i posar Caddy davant amb reverse_proxy. Quan la configuració utilitza un domini públic i DNS/ports estan preparats, Caddy pot gestionar HTTPS automàticament.

  • En estàtic, publica només la carpeta de sortida del build; no exposis el repositori, .git, fitxers .env ni directoris de treball.
  • En Node, escolta en loopback quan només Caddy hagi de parlar amb l'aplicació. No cal obrir el port intern al router.
  • El domini públic ha d'apuntar a la IP correcta i TCP 80/443 ha d'arribar a Caddy si vols certificats públics automàtics.
  • Valida la configuració abans de recarregar-la i comprova el domini real després del canvi.
  • Un 200 del backend local i un 200 del domini públic són proves diferents: totes dues importen.

GitHub és la font de revisió, no el supervisor del procés

Un workflow amb runner self-hosted pot fer checkout, instal·lar dependències, executar tests, generar un build i preparar una revisió nova al mateix servidor. Això no converteix GitHub Actions en un gestor de processos. El servei estàtic o Node necessita el seu propi mecanisme d'execució, reinici o substitució controlada, i el desplegament ha de saber quina revisió queda activa.

Flux que convé poder auditar

  • Commit o SHA que es vol desplegar i branca d'origen.
  • Resultat de build i proves abans de tocar el servei actiu.
  • Directori o revisió preparada fora de la publicació actual.
  • Canvi atòmic o pas explícit d'activació i reinici del procés Node.
  • Smoke local i després smoke HTTPS del domini públic.
  • Revisió anterior disponible per fer rollback si el canvi falla.

Cas real: NRS Home Server

NRS Home Server aplica aquesta separació en Windows. Els desplegaments conserven procedència GitHub i historial; StaticHost i AppHost mantenen serveis independents del panell; i la publicació Caddy és opt-in per domini. Caddy continua sent extern: NRS Home Server no l'instal·la ni modifica DNS, router, firewall o certificats del sistema.

  • Les webs estàtiques es registren i es serveixen mitjançant un StaticHost independent; les apps Node utilitzen ports loopback reservats.
  • La publicació d'un domini apunta només a serveis registrats. El panell, Drive, backups i administració de Minecraft no es converteixen en destins públics.
  • Abans de recarregar Caddy, la configuració generada es valida. Un gateway preparat no es presenta com a accessible des d'Internet si DNS o la xarxa externa no s'han comprovat.
  • Els projectes GitHub conserven revisió desplegada, comprovació manual de frescor i una revisió anterior compatible per a recuperació.
  • El model lleuger de persistència arrenca després d'iniciar sessió a Windows; no equival a hosting 24/7 abans del login.

Checklist de publicació

  1. 01

    Decideix si el projecte és estàtic o necessita un procés Node persistent.

  2. 02

    Mantén l'app Node en loopback i publica només Caddy a Internet.

  3. 03

    Comprova DNS, ports 80/443 i firewall abans d'esperar HTTPS públic.

  4. 04

    Executa build i QA sobre la revisió exacta que vols desplegar.

  5. 05

    Prepara el canvi fora del servei actiu i conserva una via de rollback.

  6. 06

    Verifica primer el servei local i després el domini HTTPS real.

  7. 07

    No permetis que un workflow no fiable executi codi amb permisos del servidor.

El que aquesta arquitectura no resol sola

Caddy no substitueix backups, monitorització, gestió de processos, actualitzacions del sistema ni una política de seguretat. Un runner self-hosted tampoc és una caixa de sorra: executa workflows dins d'una màquina que controles i pot conservar estat entre jobs. Si el servidor és crític, necessita més disciplina operativa que un PC domèstic encès puntualment.