Shlink Common — Configuration applicative partagée
Shlink_Common est la couche applicative partagée de Shlink. Elle n'est pas déployée seule ; elle fournit la configuration propre à Shlink sur laquelle s'appuient à la fois Shlink_CloudRun et la variante GKE, afin que les deux variantes de plateforme se comportent de manière identique là où cela compte. Les utilisateurs finaux ne configurent jamais cette couche directement — elle n'a aucune entrée propre dans l'interface de déploiement — mais comprendre ce qu'elle fournit explique les valeurs par défaut que vous voyez dans la documentation des plateformes.
Pour l'infrastructure qui provisionne et exécute réellement Shlink, consultez le guide de la plateforme (Shlink_CloudRun) et les guides du socle (App_CloudRun, App_GKE, App_Common).
1. Ce que fournit cette couche
| Domaine | Fourni par Shlink_Common | Où cela apparaît |
|---|---|---|
| Clé d'API initiale | Génère une clé d'API aléatoire de 32 caractères, la stocke dans Secret Manager et l'injecte sous le nom INITIAL_API_KEY afin que Shlink amorce sa première clé d'API REST au premier démarrage | Sorties secret_ids / secret_values ; §Accès au premier lancement dans le guide de la plateforme |
| Image de conteneur | Fine surcouche Cloud Build FROM shlinkio/shlink:stable — le point d'entrée officiel est conservé tel quel | Sortie container_image du déploiement de la plateforme |
| Moteur de base de données | Impose Cloud SQL for PostgreSQL 15 (DB_DRIVER = postgres, DB_PORT = 5432) | §Base de données dans le guide de la plateforme |
| Amorçage de la base de données | Définit le job db-init (postgres:15-alpine) qui crée de manière idempotente l'utilisateur et la base de données via le socket de l'Auth Proxy | Sortie initialization_jobs |
| Environnement de base | IS_HTTPS_ENABLED=true ; laisse volontairement DB_USER / DB_NAME non définis pour que les valeurs propres au tenant du socle l'emportent | Comportement de l'application dans le guide de la plateforme |
| Stockage d'objets | Aucun — Shlink stocke tout son état dans PostgreSQL (storage_buckets = []) | Sortie storage_buckets (vide) |
| Tests de santé | Sondes de démarrage et de vivacité sur /rest/health (HTTP 200 non authentifié) | §Observabilité dans le guide de la plateforme |
2. Secret de la clé d'API initiale
Shlink n'a pas de comptes utilisateur administrateur — tout se pilote via son API REST avec un en-tête X-Api-Key. Shlink_Common génère une clé aléatoire de 32 caractères, la stocke sous le nom secret-<prefix>-shlink-initial-api-key dans Secret Manager et l'injecte dans le conteneur comme variable d'environnement secrète INITIAL_API_KEY. Shlink lit cette variable au premier démarrage et l'enregistre comme sa première clé d'API ; le déploiement est donc utilisable immédiatement, sans étape manuelle de création de clé.
Récupérez-la après le déploiement :
API_SECRET=$(gcloud secrets list --project "$PROJECT" \
--filter="name~shlink AND name~initial-api-key" --format="value(name)" --limit=1)
API_KEY=$(gcloud secrets versions access latest --secret="$API_SECRET" --project "$PROJECT")
Le nom de clé INITIAL_API_KEY utilise des tirets bas simples comme séparateurs ; c'est donc aussi une clé de données de Secret Kubernetes valide pour le chemin SecretSync de GKE. Le secret du mot de passe de la base de données est géré par le socle, et non par cette couche, et il est injecté sous le nom DB_PASSWORD (que Shlink lit directement — aucun remappage dans le point d'entrée n'est nécessaire).
3. Image de conteneur — pas de point d'entrée personnalisé
L'image officielle de Shlink lit toute sa configuration (DB_*, DEFAULT_DOMAIN, IS_HTTPS_ENABLED, INITIAL_API_KEY, …) directement depuis les variables d'environnement et exécute automatiquement ses migrations de base de données au démarrage du conteneur ; Shlink_Common utilise donc l'image telle quelle : le Dockerfile est une fine surcouche FROM shlinkio/shlink:stable qui n'existe que pour donner quelque chose à construire au pipeline Cloud Build de la plateforme, et l'image est mise en miroir dans Artifact Registry pour éviter les limites de débit de Docker Hub.
Le tag stable suit la dernière version stable de Shlink ; épinglez une version précise en remplaçant application_version (p. ex. 4.4.0) pour des builds reproductibles.
# Confirm the deployed image
gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION" \
--format='value(spec.template.spec.containers[0].image)'
4. Moteur de base de données et amorçage
Shlink s'exécute sur PostgreSQL 15 (database_type = "POSTGRES_15"). À chaque apply, un job ponctuel db-init (image postgres:15-alpine) se connecte à Cloud SQL — en associant le socket Unix de l'Auth Proxy à un chemin de socket PostgreSQL standard lorsqu'il est présent — et, de manière idempotente :
- Crée l'utilisateur de l'application (ou réinitialise son mot de passe s'il existe).
- Accorde le rôle de l'utilisateur à
postgresafin que la propriété de la base de données puisse être attribuée. - Crée la base de données de l'application, dont cet utilisateur est propriétaire (ou corrige la propriété).
- Accorde tous les privilèges sur la base de données et sur le schéma
public. - Envoie un signal d'arrêt
POST /quitquitquitau sidecar Cloud SQL Proxy pour que le job se termine proprement.
Nommage propre au tenant : le socle crée le véritable utilisateur et la véritable base de données sous des noms propres au tenant et les injecte sous les noms DB_USER / DB_NAME ; comme Shlink lit directement ces variables, Shlink_Common ne les définit volontairement pas — les prédéfinir avec les noms de base courts shlink ferait s'authentifier l'application avec un rôle qui n'est jamais créé (password authentication failed for user "shlink").
Inspectez directement la base de données :
gcloud sql connect <instance-name> --user=<db-user> --project "$PROJECT"
5. Valeurs par défaut de l'environnement de base
DB_DRIVER = postgres,DB_PORT = 5432— la configuration native de Shlink par variables d'environnement ; le socket/l'hôte provient deDB_HOST, injecté par le socle.IS_HTTPS_ENABLED = true— la plateforme place toujours le service derrière HTTPS (URLrun.app, équilibreur de charge ou Ingress) ; Shlink génère donc des URL courtes enhttps://.DEFAULT_DOMAINvolontairement non défini — l'URL publique du service n'est connue qu'après le déploiement ; définissez-la après le déploiement (ou viaenvironment_variables) pour que les URL courtes générées portent le bon hôte.- Migrations au démarrage — l'installation et les mises à niveau du schéma ont lieu automatiquement à chaque démarrage du conteneur ; il n'existe pas de job de migration distinct.
6. Comportement des sondes de santé
Shlink expose /rest/health — un point de terminaison public et non authentifié qui renvoie HTTP 200 avec application/health+json {"status":"pass"} une fois l'application démarrée — de sorte que de simples sondes HTTP fonctionnent sur les deux plateformes (contrairement aux applications dont les points de terminaison de santé exigent une authentification et imposent une sonde de vivacité désactivée).
- Sonde de démarrage — HTTP
/rest/health, délai initial de 30 s, période de 10 s, seuil d'échec de 30 (jusqu'à ~300 s pour les migrations du premier démarrage). - Sonde de vivacité — HTTP
/rest/health, délai initial de 30 s, période de 30 s, seuil d'échec de 3.
Notez que Shlink n'a pas de page d'accueil web — / renvoie 404 par conception — ne pointez donc jamais une sonde ou un test de disponibilité vers le chemin racine.
7. Stockage d'objets
Aucun. Shlink conserve tout son état — URL courtes, visites, tags, domaines, clés d'API — dans PostgreSQL ; storage_buckets est donc vide et aucun partage NFS ni bucket GCS n'est provisionné. La durabilité est assurée par les sauvegardes automatiques de Cloud SQL.
Pour la configuration propre à Shlink destinée aux utilisateurs (variables par groupe, sorties et exploration de chaque service depuis la console et la CLI), consultez le guide de la plateforme : Shlink_CloudRun.
Guides associés
- Shlink sur Google Cloud Run — cette configuration déployée sur Cloud Run.
- Shlink sur GKE Autopilot — cette configuration déployée sur GKE.
Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.