Sådan self-hoster du Homepage i 2026: Allowed Hosts, widgets og konfiguration

Der findes to versioner af at “køre Homepage”: En container eksisterer, eller også udfører servicen sit reelle arbejde. Det er kun den anden, der betyder noget. Her er beviset, at du kan indlæse services og bookmarks, kalde flere live-widgets, teste søgning og genstarte efter redigering af en YAML-konfigurationsfil.

Homepage har dette formål: en startside med live-widgets til self-hostede services. Deploymentet skal bevare de dele, der understøtter denne funktionalitet; en port, et volume og et certifikat er input – ikke resultatet.

Vælg den mindst mulige brugbare Homepage-topologi

Et nyttigt Homepage-diagram viser den offentlige route, den private port 3000, state-grænsen og alle understøttende krav. Markér, hvilke pile der transporterer credentials, og hvilke der er almindelig brugertrafik. Det eksterne krav for Homepage er read-only-konfiguration samt credentials til valgfrie service-widgets. Test outbound DNS, TLS og provider-adfærd uden at eksponere endnu en inbound-service.

Bevis diagrammet med én reel handling: indlæs services og bookmarks, kald flere live-widgets, test søgning og genstart efter redigering af en YAML-konfigurationsfil. Presset kommer sandsynligvis fra widget-fan-out, langsomme downstream-API'er, DNS-opslag og browser-dashboardets refresh-rate; overvåg denne sti i stedet for at behandle alle HTTP-requests ens.

Opgradér Homepage uden at gætte

Den første nyttige driftsmetrik for Homepage er, om den kan indlæse services og bookmarks, kalde flere live-widgets, teste søgning og genstarte efter redigering af en YAML-konfigurationsfil. Kombinér den med saturation-signaler for widget-fan-out, langsomme downstream-API'er, DNS-opslag og browser-dashboardets refresh-rate. En process-only probe bør ikke kalde dyre dependencies eller genstarte containeren, fordi en upstream-service kortvarigt er utilgængelig.

Behandl upgrades som dataændringer, fordi konfigurationsnøgler og widget-integrations kan ændre sig, så validér YAML og provider-adfærd før en image-opdatering. Pin versioner, øv dig på restored state, og behold det tidligere image tilgængeligt, indtil en rollback fortsat er gyldig. Når hosten afvises, eller YAML-indentering forhindrer config i at blive indlæst, skal du gemme logs fra før genstarten; de indeholder normalt den kausale fejlmeddelelse.

En production acceptance-test for Homepage

Før de rigtige brugere kommer til, skal du lave et release-worksheet for Homepage. Det skal angive det pinnede image, port 3000, canonical origin, persistente paths og ejeren af read-only-konfiguration samt credentials til valgfrie service-widgets. Vedhæft det forventede resultat af denne transaktion: indlæs services og bookmarks, kald flere live-widgets, test søgning og genstart efter redigering af en YAML-konfigurationsfil.

Brug worksheetet efter en normal udskiftning og efter en clean restore. Recovery accepteres kun, hvis services, bookmarks, widgets og custom assets kommer tilbage, og alle kritiske widgets håndterer downstream-fejl synligt. Indsaml også et kort resource trace, der dækker widget-fan-out, langsomme downstream-API'er, DNS-opslag og browser-dashboardets refresh-rate; opbevar det sammen med releaset, så fremtidige kapacitetsændringer sammenlignes med den samme workload.

Inkludér én kontrolleret fejl: Afvis midlertidigt den teststi, der bruges af read-only-konfiguration samt credentials til valgfrie service-widgets. Bekræft, at Homepage rapporterer problemet ved den korrekte boundary, genskab den gyldige tilstand, og kør transaktionen igen. Det tester error visibility, ikke blot succes, og forhindrer en tilsyneladende sund brugerflade i at skjule en defekt worker, callback eller databaseforbindelse.

Gør Homepage-start reproducerbar

Brug containeren som en udskiftelig runtime, ikke som stedet, hvor sandheden ligger.

docker run -d \
  --name homepage \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v homepage-data:/app/config \
  -e HOMEPAGE_ALLOWED_HOSTS=home.example.com \
  ghcr.io/gethomepage/homepage:latest

Tillad og verificér den outbound- eller client-side-sti, der kræves til read-only-konfiguration samt credentials til valgfrie service-widgets. Kontrollér container-brugeren, writable paths og den bundne listener, før du eksponerer den. Kør den komplette handling — indlæs services og bookmarks, kald flere live-widgets, test søgning og genstart efter redigering af en YAML-konfigurationsfil — og gem den nøjagtige image-reference, der gav resultatet.

Adskil udskiftelige containere fra varige data

Det persistente recovery-sæt er konfigurationsfiler, bookmarks, services og custom assets. Mount /app/config før bootstrap, skriv harmløse eksempeldata, og udskift containeren for at bevise, at stien faktisk er persistent. Et volume beskytter data mod udskiftning af containeren, men ikke mod tab af hosten, utilsigtet sletning eller korruption på applikationsniveau.

Tag backups, der forstår datakilden: Brug logical dumps til live-databaser, når det er nødvendigt, og kopiér kun filer fra en konsistent tilstand. Opbevar én krypteret kopi væk fra Homepage-hosten. Acceptkriteriet for en restore er specifikt – services, bookmarks, widgets og custom assets skal komme tilbage, og alle kritiske widgets skal håndtere downstream-fejl synligt. Guiden til backups, der er testet med restore forklarer, hvorfor job-success alene ikke er tilstrækkeligt.

Domains, proxy headers og port 3000

Browseren, API-klienten og Homepage skal være enige om én origin. For at sikre det skal du angive allowed hosts for det præcise domain og proxy-hostname. Bevar den oprindelige host og protokol, samtidig med at port 3000 ikke er tilgængelig som en konkurrerende offentlig adresse.

Guiden til fejlfinding af et site, der er nede hjælper med at skelne mellem en utilgængelig route og en applikation, der svarer. Denne forskel er vigtig her: Hosten afvises, eller YAML-indentering forhindrer config i at blive indlæst. Kun den første fejl løses med ingress-ændringer; den anden kræver inspektion af Homepage-logs, state eller workload.

Sikkerhedsbeslutninger, der gælder specifikt for Homepage

Overfør ikke sikkerhedsantagelser fra en lokal tutorial. Homepage's specifikke problem er at committe widget API keys til et offentligt repository. I produktion bør du derfor angive allowed hosts præcist og opbevare widget API keys i environment eller secret-backed config i stedet for i et offentligt repository.

HOMEPAGE_ALLOWED_HOSTS styrer adfærd, ikke confidentiality; validér dens type og værdi, og opbevar ægte Homepage-credentials separat. Begræns filesystem- og netværksadgang, beskyt setup-endpoints, og definér upload-, request- eller execution-limits omkring widget-fan-out, langsomme downstream-API'er, DNS-opslag og browser-dashboardets refresh-rate.

Hvor Dockup fjerner arbejde for Homepage

For Homepage er Dockup mest nyttig ved grænsen mellem et image og en persistent service. Den holder routen til 3000, TLS, secret-værdier og storage knyttet sammen på tværs af container-udskiftninger, uanset om compute håndteres af Dockup eller af din tilknyttede server.

Afslut med applikationsviden: Angiv allowed hosts for det præcise domain og proxy-hostname; tillad og verificér read-only-konfiguration samt credentials til valgfrie service-widgets; og kør denne verificering: indlæs services og bookmarks, kald flere live-widgets, test søgning og genstart efter redigering af en YAML-konfigurationsfil. Gem resultatet som et deployment-check, så den næste image-opdatering vurderes ud fra adfærd frem for container-status.

Ofte stillede spørgsmål

Hvad kræver Homepage til et production deployment?

Route Homepage-containeren på port 3000 gennem én HTTPS-origin. Det eksterne leveringskrav er read-only-konfiguration samt credentials til valgfrie service-widgets. Erklær ikke Homepage klar, før du kan indlæse services og bookmarks, kalde flere live-widgets, teste søgning og genstarte efter redigering af en YAML-konfigurationsfil.

Hvilke Homepage-data skal med i en backup?

Persistér /app/config, og inkludér konfigurationsfiler, bookmarks, services og custom assets i det samme recovery-manifest. En clean Homepage-restore er kun godkendt, når services, bookmarks, widgets og custom assets kommer tilbage, og alle kritiske widgets håndterer downstream-fejl synligt.

Kræver Homepage HTTPS bag en reverse proxy?

Brug HTTPS til den offentlige Homepage-origin, og behold port 3000 på den interne route. Anvend Homepage-indstillingen korrekt: Angiv allowed hosts for det præcise domain og proxy-hostname. For Homepage beskytter HTTPS credentials eller brugerindhold under transmission og holder origin-sensitiv client-adfærd konsistent.

Hvordan skal en Homepage-upgrade testes?

Genskab den aktuelle Homepage-state i et isoleret deployment, anvend kandidatversionen, og gentag dens acceptance-transaktion. Vær særligt opmærksom, fordi konfigurationsnøgler og widget-integrations kan ændre sig, så validér YAML og provider-adfærd før en image-opdatering. Behold det tidligere Homepage-image, indtil grænsen for datamigrering og rollback er forstået.