Homepage sur Google Cloud Run
Homepage (gethomepage/homepage) est un tableau de bord d'applications/lanceur de services auto-hébergé et hautement personnalisable — une application Next.js 16 / Node 22 dont toute la configuration (services, favoris, widgets, mise en page) réside dans une poignée de fichiers YAML, avec des widgets optionnels de statut/statistiques en direct pour d'autres applications auto-hébergées que vous exécutez. Ce module déploie Homepage sur Cloud Run v2 sur la base de la fondation App_CloudRun, qui provisionne et gère l'infrastructure partagée de Google Cloud.
Ce guide se concentre sur les services cloud utilisés par Homepage et sur la manière de les explorer et de les exploiter depuis la console Google Cloud et la ligne de commande. Pour les mécanismes communs à toutes les applications Cloud Run — identité de service, ingress et équilibrage de charge, mise à l'échelle et concurrence, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et cycle de vie du déploiement — reportez-vous au guide de la fondation App_CloudRun plutôt que de les répéter ici.
Ce que coûte Homepage sur RAD, et comment cela se compare
L'exécution de Homepage sur Cloud Run dans votre propre projet Google Cloud coûte environ 16,78 $/mois en frais Google Cloud, en plus d'un forfait unique de 40 crédits de module RAD facturé une fois au moment du déploiement. Homepage est l'application la plus légère de ce lot, et de loin — un tableau de bord statique sans base de données propre — de sorte que son coût d'exécution en projet propre est proche du plancher de ce que coûte tout déploiement Cloud Run. Dans un projet géré par RAD, les frais de module tombent à 36 crédits (10 % de moins) et le coût d'exécution est mesuré à l'heure en crédits au lieu d'être facturé directement par Google — voir Mettez-le en pause gratuitement ci-dessous pour le seul avantage géré par RAD qu'un VPS auto-hébergé ne peut égaler — ou voir le guide GKE si vous préférez l'exécuter sur Kubernetes.
Ce que vous payez sur RAD
| Projet propre | Projet géré par RAD | |
|---|---|---|
| Frais de module (unique) | 40 crédits | 36 crédits (10 % de moins) |
| Builds | Inclus dans le prix : pas de frais de build pour la création, 5 mises à jour par mois (mois calendaire UTC) gratuites puis 2 crédits chacune, et rien pour la suppression ou pour un build échoué, dans la limite de 10 builds échoués par jour (UTC). Les sessions de lab et les projets clients sont l'exception : ils sont toujours facturés à la minute pour le temps de build | Identique |
| Coût d'exécution Google Cloud | 16,78 $/mois, facturé par Google au prix catalogue | ~16 crédits/jour, mesuré au prix catalogue plus la marge de RAD |
Votre premier déploiement réussi sur RAD est exempt de frais de module, quel que soit le montant : une fois par compte, pour un module que vous déployez et payez vous-même (dans une solution, les frais d'une application : la première à réussir ; jamais une session de lab ou un projet client).
Coût d'exécution par défaut dans votre propre projet
| Ressource | US$/mois (prix catalogue Google, us-central1) |
|---|---|
| Cloud Run, 1x vCPU / 0,5 GiB (scaleToZero) | 10,78 $ |
| Cloud NAT et réseau | 5,00 $ |
| Cloud Storage (modules complémentaires, sauvegardes) | 1,00 $ |
| Total | 16,78 $ |
Comment cela se compare
- Une comparaison auto-gérée : Hetzner CPX22 (2 vCPU/4 Go) coûte environ 24 $/mois, un Droplet DigitalOcean 2 vCPU/4 Go coûte le même 24 $/mois, et un GCP Compute Engine e2-standard-2 (2 vCPU/8 Go) coûte environ 49 $/mois — nettement plus qu'un tableau de bord de configuration seule sans besoin de base de données ; une micro-instance à vCPU partagé de 5-6 $/mois de l'un des mêmes fournisseurs l'exécuterait confortablement.
- Homepage n'a pas de SaaS hébergé commercial propre — il est distribué uniquement en tant que logiciel auto-hébergé configuré en YAML.
- Comme il n'y a pas de base de données ou de serveur de fichiers ici, l'écart entre RAD-managed et un VPS nu est plus petit que pour presque tout le reste dans ce lot — principalement juste le TLS géré, Secret Manager et la surveillance par rapport à le faire à la main.
Mettez-le en pause gratuitement : supprimez un projet géré par RAD, restaurez-le lorsque vous en avez besoin
C'est l'avantage principal d'un projet géré par RAD, et il ne coûte rien pendant la pause. La suppression d'un projet géré par RAD délie d'abord sa facturation, puis demande à Google de supprimer le projet purement et simplement — la suppression logicielle récupérable de 30 jours de Google. Contrairement à la suppression d'un module, cela ne démantèle pas Cloud SQL, aucune VM, ou la ressource de calcul une par une : l'ensemble du projet s'arrête simplement, et rien n'est facturé pendant qu'il attend, car la facturation est déjà déliée.
Une restauration n'est pas garantie — conservez vos propres sauvegardes. Les conditions de Google Cloud ne garantissent pas qu'un projet restauré, ou les ressources qu'il contient, sera utilisable après sa restauration, de sorte que la restauration ne peut pas être considérée comme un moyen de récupérer un projet supprimé. Avant de supprimer, assurez-vous d'avoir effectué des sauvegardes appropriées des données et de la configuration de l'application et de les avoir stockées en dehors du projet. Si une restauration échoue, ou si le projet restauré ne fonctionne pas, la solution de repli consiste à redéployer l'application (voir la section suivante) et à restaurer sa configuration et ses données à partir de ces sauvegardes.
La restauration, dans les 30 jours et uniquement par le propriétaire du projet, demande à Google de récupérer le projet et de rattacher son compte de facturation, puis vous demande d'exécuter la mise à jour sur chaque déploiement pour confirmer que tout est revenu. Comme rien n'a été détruit individuellement, cette mise à jour trouve les mêmes ressources déjà présentes — c'est une vérification, pas une reconstruction, et une mise à jour ne facture jamais les frais de module à nouveau. Les mises à jour sont incluses dans le prix (5 par mois pour chaque déploiement), donc une restauration ne coûte normalement aucun crédit.
Ce qu'il faut : vous devez être propriétaire du projet (pas un projet dont RAD gère uniquement la facturation), vous devez le restaurer vous-même dans les 30 jours — après cela, Google le supprime définitivement — et la restauration est admise comme la création d'un nouveau projet, donc votre solde de crédits achetés doit toujours dépasser le seuil du niveau (100 crédits pour le niveau sandbox que la plupart des utilisations d'étude/démo conviennent). Google indique que la plupart des services sont à nouveau pleinement fonctionnels dans les 36 heures suivant une restauration.
Un véritable écart : les sauvegardes nocturnes sont écrites dans un bucket à l'intérieur du projet, et ce bucket a la suppression logicielle de Cloud Storage explicitement désactivée, il est donc très probable qu'il disparaisse dès que vous supprimez le projet — même si le projet lui-même est récupérable pendant 30 jours. Si vous avez personnalisé Homepage et que vous souhaitez conserver ce travail, copiez une sauvegarde (vers Google Drive, ou un bucket en dehors du projet) avant de supprimer. Pour une installation par défaut sans rien d'irremplaçable, cela n'a pas d'importance.
Payez uniquement pendant que vous l'utilisez, l'autre méthode : supprimer et redéployer
Dans votre propre projet, ou une fois que 30 jours se sont écoulés sur un projet géré par RAD, il n'y a pas de pause gratuite — la suppression supprime les ressources définitivement, et ramener Homepage signifie redéployer à partir de zéro. Cela coûte 40 crédits (les frais de module ; les builds sont inclus).
La suppression ne permet d'économiser de l'argent que si Homepage reste inutilisé suffisamment longtemps pour compenser ce coût de redéploiement par rapport à son propre coût d'exécution — pour Homepage, cela représente environ 8 jours ou plus.
Conservez d'abord les données : les sauvegardes nocturnes sont stockées dans un bucket à l'intérieur du déploiement et sont supprimées avec celui-ci, donc copiez la dernière sauvegarde avant de la supprimer si vous souhaitez la conserver.
Sessions de lab et environnements gérés
Sessions de lab, pour la formation : un formateur anime une session pour une classe. Chaque participant obtient l'application dans son propre projet Google Cloud pendant 15 minutes à 24 heures, dans la limite d'une allocation définie par le formateur. Le formateur peut aussi créer un seul environnement partagé pour toute la classe, et chacun utilise alors la même application et ses données. Soit le formateur finance toutes les places, soit chaque participant paie la sienne. Tout est supprimé à la fin de la session et les crédits inutilisés sont reversés au formateur.
Environnements gérés, pour les cabinets de conseil : un partenaire exécute l'application pour un client à partir d'un portefeuille cloisonné qu'il finance, et règle directement avec le client. Si le portefeuille est faible, la facturation est interrompue et les données sont conservées, de sorte que personne ne reçoit de frais inattendus. À la fin, le partenaire transfère le projet et les déploiements deviennent la propriété du client.
Les crédits peuvent être achetés dans plus de 20 devises, y compris XAF, XOF, NGN, GHS, KES et ZAR, par carte, virement bancaire ou argent mobile.
Sources (8 octobre 2026) : Prix catalogue de l'API Google Cloud Billing Catalog ; radmodules.dev/pricing pour les frais propres de RAD et les estimations de crédits quotidiens ; documentation de Google sur la suppression/restauration de projets pour les affirmations de pause/restauration.
1. Vue d'ensemble
Homepage s'exécute comme un seul conteneur Node.js/Next.js sur Cloud Run v2. Contrairement à presque tous les autres modules de ce catalogue, il n'a pas de base de données et pas de cache — son état entier est un répertoire de fichiers YAML :
| Capacité | Service Google Cloud | Notes |
|---|---|---|
| Calcul | Cloud Run v2 | Processus Node.js unique, 1000m CPU / 512Mi mémoire par défaut |
| Base de données | aucune | Homepage n'a aucune base de données ; database_type = "NONE" |
| Stockage d'objets | Cloud Storage | Un bucket storage monté à /app/config via GCS FUSE — contient tous les fichiers de configuration YAML (settings.yaml, services.yaml, bookmarks.yaml, widgets.yaml, docker.yaml) plus les logs |
| Cache et file d'attente | aucun | enable_redis = false est codé en dur dans main.tf, remplaçant la valeur par défaut de la fondation true |
| Secrets | aucun | Aucun secret n'est généré — Homepage n'a pas besoin de ses propres identifiants |
| Ingress | URL Cloud Run | URL run.app par défaut ; équilibreur de charge HTTPS externe optionnel + domaine personnalisé |
Valeurs par défaut judicieuses à connaître d'emblée :
- Généralement pré-construit — pas d'image personnalisée, pas de Cloud Build pour l'application.
Homepage_Commondéfinitimage_source = "prebuilt"etcontainer_build_config.enabled = false;ghcr.io/gethomepage/homepageest déployé directement.enable_image_mirroring = truele copie toujours dans Artifact Registry (évite les limites de débit de GHCR), mais c'est un miroir, pas un build. - Port 3000, chemin de santé
/api/healthcheck. Confirmé via un déploiement en direct :GET /api/healthcheckrenvoie un200 "up"non authentifié une fois l'application prête (soutenu par la directiveHEALTHCHECKde l'image). - Pas de base de données, pas de Redis — architecturalement inhabituel pour ce catalogue. Presque tous les autres modules d'application connectent une instance Cloud SQL et/ou Redis via la fondation ; Homepage n'a besoin ni de l'un ni de l'autre. Cela signifie également qu'il n'a aucune des classes de bugs habituelles de câblage DSN, socket-vs-TCP, ou encodage d'URL de mot de passe documentées ailleurs dans ce dépôt — il n'y a tout simplement aucune connexion de base de données à mal configurer.
- La mise à l'échelle à zéro et les instances multiples sont toutes deux réellement sûres. Homepage
lit sa configuration YAML en direct depuis le disque à chaque requête (pas de cache en mémoire),
et son auto-amorçage de configuration unique au premier démarrage est idempotent. Le
module utilise par défaut
min_instance_count = 0/max_instance_count = 3— la plupart des applications avec état de ce catalogue ont besoin du contraire (min = 1,max = 1) pour éviter la perte au démarrage à froid ou une course de monoscript ; Homepage n'a besoin d'aucune de ces protections. - Pas d'authentification propre.
HOMEPAGE_ALLOWED_HOSTSpar défaut"*"— cela ne filtre que la vérification de l'en-têteHostsur les appels de données de widget/api/*de Homepage, pas un véritable contrôle d'accès. Placez-le derrière IAP, un VPN ou un proxy inverse si vous devez restreindre l'accès. - Une option de montage GCS FUSE documentée et vérifiée sur Cloud Run.
Homepage_Commondemandeuid=1000,gid=1000dans lemount_optionsdu volume (correspondant auxPUID/PGIDdu conteneur), mais l'intégration gcsfuse intégrée de Cloud Run substitue silencieusement son propreuid=2000,gid=2000— confirmé via la ligne de log "CLI Flags" de GCSFuse au moment du déploiement. Cela n'a eu aucun impact fonctionnel (le montage est resté auto-cohérent et inscriptible), mais il est bon de le savoir pour qu'un futur mainteneur ne suppose pas que lesmount_optionsconfigurés sont littéralement honorés sur Cloud Run.
2. Services Google Cloud et comment les explorer
Toutes les commandes supposent que PROJECT et REGION sont définis. Les noms de services et de ressources
sont indiqués dans les Sorties du déploiement.
A. Cloud Run — le service Homepage
- Console : Cloud Run → sélectionnez le service pour les révisions, le trafic, les logs et les métriques.
- CLI :
gcloud run services list --project "$PROJECT" --region "$REGION"
gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
Voir App_CloudRun pour la mise à l'échelle, la concurrence et le partage de trafic.
B. Cloud Storage — le volume de configuration
Le bucket storage est monté à /app/config via GCS FUSE. Il contient tous
les fichiers de configuration YAML lus par Homepage (settings.yaml, services.yaml,
bookmarks.yaml, widgets.yaml, docker.yaml) ainsi que les logs de Homepage — ce
bucket est l'état persistant complet de Homepage ; il n'y a rien d'autre à
sauvegarder.
- CLI :
gcloud storage buckets list --project "$PROJECT" --filter="name~homepage"
gcloud storage ls "gs://<bucket-name>/"
gcloud storage cat "gs://<bucket-name>/settings.yaml"
C. Secret Manager
Rien à voir ici — Homepage ne génère aucun secret. Confirmer cela est en soi une vérification de bon sens utile lors d'un nouveau déploiement :
gcloud secrets list --project "$PROJECT" --filter="name~homepage"
# expect: no results
D. Réseau et ingress
- CLI :
gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
E. Cloud Logging et Monitoring
- CLI :
Recherchez la ligne de log "CLI Flags" de GCSFuse près du démarrage pour confirmer l'UID/GID réellement monté (voir §1 ci-dessus — il affichera
gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50uid=2000,gid=2000sur Cloud Run quelle que soit la valeur configuréemount_options).
3. Comportement de l'application Homepage
- Pas de job de schéma de base de données au premier déploiement. Homepage n'a pas de base de données, donc
initialization_jobsest vide par défaut et aucun job n'est nécessaire. - Pas d'assistant de configuration au premier démarrage. Il n'y a pas de compte administrateur à créer et pas de
flux d'intégration — Homepage affiche son tableau de bord à partir de la configuration
existante dans
/app/config(les valeurs par défaut intégrées de l'image upstream lors d'un nouveau déploiement, puisque le point d'entrée auto-amorce tout fichier manquant). Personnalisez le tableau de bord en modifiant directement les fichiers YAML (voir §2B) ou en configurantdocker.yaml/la découverte basée sur les étiquettes si vous le connectez à une API Docker/Kubernetes. - Chemin de santé. Les sondes de démarrage et de vivacité ciblent toutes deux
GET /api/healthcheck— un200 "up"non authentifié, confirmé en direct. - Inspecter l'exécution du job (ne devrait rien afficher, par conception) :
gcloud run jobs executions list --job <job-name> --project "$PROJECT" --region "$REGION"
La surcharge de l'option de montage GCS FUSE — à savoir, mais pas à s'inquiéter
Homepage_Common définit explicitement mount_options avec uid=1000,gid=1000 sur
le volume GCS /app/config, correspondant aux variables d'environnement PUID=1000/PGID=1000
du conteneur. Sur un déploiement en direct, la ligne "CLI Flags" de GCSFuse de Cloud Logging
au démarrage du conteneur montre que le montage réel utilise
uid=2000,gid=2000 — l'intégration gcsfuse intégrée de Cloud Run remplace
inconditionnellement la valeur configurée. Lors des tests, cela n'a eu aucun impact fonctionnel :
le montage était auto-cohérent (l'UID/GID remplacé de Cloud Run correspondait à ce que le montage lui-même utilisait pour toutes les écritures ultérieures) et l'application a démarré et écrit sa configuration proprement. La leçon est plus étroite qu'un bug : ne
supposez pas que l'UID/GID mount_options que vous configurez est ce que Cloud Run
utilise littéralement — vérifiez via la ligne de log si vous déboguez un réel
problème de permissions ici. (Ceci est spécifique à l'intégration gcsfuse propre à Cloud Run ;
le pilote CSI GCS FUSE distinct de GKE n'a pas une telle surcharge et
exige réellement que l'UID/GID configuré corresponde à l'utilisateur du conteneur — voir
la découverte GKE gcsfuse référencée dans le CLAUDE.md de ce dépôt.)
gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 100 \
| grep -i "gcsfuse"
4. Variables de configuration
Les variables sont regroupées exactement comme elles apparaissent sur la plateforme de déploiement. Seuls les paramètres spécifiques ou notables pour Homepage sont listés ; toute autre entrée est héritée de App_CloudRun avec son comportement standard.
Groupe 3 — Identité de l'application
| Variable | Valeur par défaut | Description |
|---|---|---|
application_name | homepage | Nom de base des ressources. |
application_display_name | Homepage | Nom lisible par l'homme affiché dans l'interface utilisateur de la plateforme. |
application_version | latest | Transmis directement comme balise d'image ghcr.io/gethomepage/homepage — pas d'étape de build. |
homepage_allowed_hosts | * | HOMEPAGE_ALLOWED_HOSTS — liste blanche d'en-têtes Host séparés par des virgules pour les appels /api/* de Homepage. Pas une véritable limite de contrôle d'accès. |
Groupe 4 — Exécution et mise à l'échelle
| Variable | Valeur par défaut | Description |
|---|---|---|
container_port | 3000 | Port du serveur autonome Next.js de Homepage. |
cpu_limit / memory_limit | 1000m / 512Mi | Léger — le plancher de 512 Mo de la génération 2 est largement suffisant. |
min_instance_count / max_instance_count | 0 / 3 | Les deux directions sont réellement sûres ici — voir §1 ; un cas rare dans ce catalogue où la valeur par défaut large est intentionnelle, pas un espace réservé. |
enable_image_mirroring | true | Reflète l'image pré-construite dans Artifact Registry (évite les limites de débit de GHCR) — pas un build. |
container_protocol | http1 | HTTP/1.1 simple ; pas d'exigence gRPC/h2c. |
enable_cloudsql_volume | false | Homepage n'a pas de Cloud SQL — conservez false. |
Groupe 11 — Cloud Storage et système de fichiers
| Variable | Valeur par défaut | Description |
|---|---|---|
gcs_volumes | [] | Le montage du bucket storage à /app/config est ajouté automatiquement ; utilisez ceci uniquement pour des volumes supplémentaires. |
enable_nfs | false | Non nécessaire — GCS FUSE à /app/config est suffisant pour la charge de travail de fichiers de configuration de Homepage. |
Groupe 12 — Backend de base de données
| Variable | Valeur par défaut | Description |
|---|---|---|
database_type | NONE | Fixé par Homepage_Common — Homepage n'a pas de base de données SQL, point final. |
Groupe 13 — Jobs et tâches planifiées
| Variable | Valeur par défaut | Description |
|---|---|---|
initialization_jobs | [] | Reste vide par défaut — rien à amorcer. |
Groupe 14 — Observabilité et santé
| Variable | Valeur par défaut | Description |
|---|---|---|
startup_probe / liveness_probe | HTTP /api/healthcheck | 200 "up" non authentifié — une valeur par défaut précise correspondant à la directive HEALTHCHECK de l'image, transmise inchangée depuis Homepage_Common. |
5. Sorties
| Sortie | Description |
|---|---|
service_name / homepage_url | Nom du service Cloud Run et URL du tableau de bord (port 3000). |
storage_buckets | Le bucket storage supportant /app/config. |
container_image / container_registry | La référence de l'image déployée et le dépôt Artifact Registry. |
deployment_id / tenant_id / resource_prefix | Identifiants de dénomination. |
project_id / project_number | Identifiants de projet. |
initialization_jobs | Noms des jobs d'initialisation créés (vide pour Homepage). |
6. Pièges de configuration et valeurs par défaut judicieuses
Risque : Critique (perte de données / panne / sécurité) — Élevé (service dégradé) — Moyen (coût ou dégradation partielle) — Faible (mineur).
| Paramètre | Valeur judicieuse | Risque | Conséquence si incorrect |
|---|---|---|---|
gcs_volumes / stockage à /app/config | Laissez le montage automatique storage en place | Critique | La suppression ou la mauvaise configuration de ce volume entraîne la perte de tous les fichiers de configuration YAML lors du prochain démarrage à froid — Homepage n'a pas d'autre source de vérité. |
HOMEPAGE_ALLOWED_HOSTS | Laissez * à moins que vous ne connaissiez le nom d'hôte final, puis resserrez-le | Moyen | Une valeur trop étroite renvoie des 400 pour chaque widget basé sur l'API (le shell de la page se charge toujours) si le nom d'hôte de la requête réelle ne correspond pas ; le traiter comme une véritable limite d'authentification est un faux sentiment de sécurité de toute façon. |
| Chemin de la sonde | Laissez à /api/healthcheck | Élevé | Un chemin de sonde authentifié ou inexistant laisserait la révision en permanence non saine même si l'application a démarré correctement. |
enable_redis | Laissez le false codé en dur tel quel (n'essayez pas de le forcer via environment_variables) | Faible | Homepage n'a rien à mettre en cache ; l'activation de Redis gaspille une dépendance Memorystore/NFS-Redis sans aucun avantage. |
| UID/GID de montage GCS FUSE supposé | Ne vous fiez pas à l'UID/GID uid=1000,gid=1000 configuré comme étant littéral sur Cloud Run | Faible | L'intégration gcsfuse propre à Cloud Run utilise silencieusement uid=2000,gid=2000 à la place — inoffensif en pratique, mais une fausse piste si vous déboguez un problème de permissions en lisant le Terraform au lieu de la ligne de log de montage réelle. |
Pour le comportement de la fondation référencé tout au long — identité de service, mise à l'échelle et concurrence, ingress et équilibrage de charge, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir d'images — voir App_CloudRun. La configuration d'application spécifique à Homepage est décrite dans Homepage_Common.
Guides associés
- Lab pratique : Homepage sur Cloud Run — déployez-le étape par étape, avec les écrans de la console et les commandes à chaque étape.
- Homepage sur GKE Autopilot — la même application sur Kubernetes, lorsque vous avez besoin de l'autre cible de déploiement.
- Homepage Common — Configuration d'application partagée — la configuration partagée par les deux cibles de déploiement.
- Déployé avec Dolibarr sur Google Cloud Run, Invoice Ninja sur Google Cloud Run, Kimai sur Google Cloud Run, Docuseal sur Google Cloud Run dans la solution Small Business Suite.
Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.