Configuration d’un sous-répertoire avec AWS en utilisant CloudFront et Route 53

Hébergez votre documentation avec un sous-répertoire /docs en utilisant AWS CloudFront et Route 53.

This feature is available on the Ultimate site plan.

Ce guide couvre la configuration d’un sous-répertoire à l’aide d’AWS CloudFront et Lambda@Edge. Il s’agit d’une approche pour les utilisateurs AWS. Si vous avez une configuration AWS différente (comme un équilibreur de charge avec des instances EC2 exécutant NGINX), vous devrez peut-être configurer votre proxy inverse différemment. Contactez l’assistance si vous avez besoin de conseils pour des configurations alternatives.

1

Configurer votre site GitBook

Dans votre organisation GitBook, cliquez sur le nom de votre site de documentation dans la barre latérale, puis cliquez sur Gérer le site ou ouvrez l’onglet Paramètres Ouvrez la section Domaine et redirections et sous « Sous-répertoire », cliquez sur Configurer un sous-répertoire.

Saisissez l’URL où vous souhaitez héberger votre documentation. Indiquez ensuite le sous-répertoire pour l’accès à la doc, par ex. example.com/docs, puis cliquez sur Configurer.

Sous Configuration supplémentaire, vous verrez maintenant une URL de proxy. Vous l’utiliserez à l’étape suivante lors de la configuration de votre fonction Lambda. Copiez-la dans votre presse-papiers.

2

Créez votre fonction Lambda@Edge

Connectez-vous à votre console AWS et accédez à Lambda.

Cliquez sur le bouton Créer une fonction .

Choisissez Auteur à partir de zéro, puis :

• Donnez un nom descriptif à votre fonction, par exemple gitbook-subpath-proxy.

• Sélectionnez Node.js comme environnement d’exécution (utilisez la dernière version disponible).

• Laissez l’architecture et les autres paramètres par défaut.

Cliquez sur Créer une fonction.

3

Mettre à jour le code de la fonction Lambda

Dans l’éditeur de fonction Lambda, remplacez le code par défaut par le suivant :

export const handler = async (event) => {
	const request = event.Records[0].cf.request;
	
	// mettez à jour si votre sous-répertoire n’est pas /docs
	const subdirectory = '/docs';
	
	// mettez à jour avec votre URL de proxy ci-dessous
	const target = new URL('<URL du proxy que vous avez obtenue de GitBook>');

	// réécriture : /docs* -> proxy.gitbook.site
	if (request.uri.startsWith(subdirectory)) {
		request.uri = target.pathname + request.uri.substring(subdirectory.length);

		// Supprimer la barre oblique finale si présente
		if (request.uri.endsWith('/')) {
			request.uri = request.uri.slice(0, -1);
		}

		request.origin = {
			custom: {
				domainName: target.host,
				port: 443,
				protocol: 'https',
				path: '',
				sslProtocols: ['TLSv1.2'],
				readTimeout: 30,
				keepaliveTimeout: 5,
				customHeaders: {},
			},
		};

		request.headers['host'] = [{ key: 'host', value: target.host }];
		request.headers['x-forwarded-host'] = [{ key: 'x-forwarded-host', value: target.host }];
	}
    
	return request;
};

Assurez-vous de mettre à jour target à la ligne 8 avec l’URL du proxy que vous avez obtenue de GitBook à la première étape. Cela ressemblera à https://proxy.gitbook.site/sites/site_XXXX

Assurez-vous également de mettre à jour subdirectory à la ligne 5 si vous utilisez un chemin de sous-répertoire différent de /docs.

Cliquez sur Déployer pour enregistrer vos modifications.

4

Configurer les autorisations Lambda pour Lambda@Edge

Avant de pouvoir utiliser votre fonction Lambda avec CloudFront, vous devez configurer le rôle d’exécution pour permettre à Lambda@Edge de l’assumer.

1. Dans votre fonction Lambda, cliquez sur l’onglet Configuration Puis

2. Cliquez sur Autorisations dans la barre latérale gauche

3. Sous Rôle d’exécution, cliquez sur le nom du rôle pour l’ouvrir dans IAM

4. Cliquez sur le bouton Relations d’approbation Puis

5. Cliquez sur Modifier la stratégie d’approbation

6. Remplacez la stratégie d’approbation par ce qui suit :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "edgelambda.amazonaws.com",
                    "lambda.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Cliquez sur Mettre à jour la stratégie pour enregistrer.

5

Publiez votre fonction Lambda

Lambda@Edge nécessite une version publiée (pas seulement $LATEST).

1. Dans votre fonction Lambda, cliquez sur le menu Actions dans le coin supérieur droit

2. Sélectionnez Publier une nouvelle version

3. Optionnellement, ajoutez une description comme « Version initiale pour CloudFront »

4. Cliquez sur Publier

5. Important : Copiez l’ARN de la version publiée qui apparaît en haut de la page (il inclura un numéro de version à la fin, comme arn:aws:lambda:us-east-1:123456789:function:gitbook-subpath-proxy:1)

Les fonctions Lambda@Edge doivent être créées dans la région us-east-1 (N. Virginie). Si vous avez créé votre fonction dans une autre région, vous devrez la recréer dans us-east-1.

6

Créez votre distribution CloudFront

Accédez à CloudFront dans la console AWS et cliquez sur Créer une distribution.

Configurez les paramètres suivants. Lorsque des paramètres ne sont pas précisés, conservez les valeurs par défaut.

Spécifier l’origine

Paramètre	Valeur
Type d’origine	Autre
Origine personnalisée	Le domaine principal de votre site web (p. ex., example.com)

Paramètres de cache

Paramètre	Valeur
Politique de cache	CachingDisabled
Politique de requête d’origine	AllViewerExceptHostHeader

Cliquez sur Ensuite, sélectionnez vos protections de sécurité préférées, puis cliquez sur Suivant à nouveau.

Cliquez sur Créer une distribution.

Attendez le déploiement de la distribution (le statut passera de « En cours » à « Activé »). Cela peut prendre plusieurs minutes.

7

Associer Lambda@Edge à CloudFront

Une fois votre distribution CloudFront déployée :

1. Cliquez sur l’ID de votre distribution pour ouvrir ses paramètres

2. Allez à l’onglet Comportements Puis

3. Sélectionnez le comportement par défaut et cliquez sur Modifier

4. Faites défiler jusqu’à Associations de fonctions

5. Sous Requête d’origine, sélectionnez Lambda@Edge

6. Dans le champ ARN de la fonction Lambda collez l’ARN de votre fonction Lambda publiée (de l’étape 5)

7. Cochez Inclure le corps pour permettre à la fonction d’accéder au corps des requêtes si nécessaire

8. Cliquez sur Enregistrer les modifications

8

Configurer le domaine et les enregistrements DNS

1. Sur la page principale de votre distribution CloudFront, cliquez sur l’onglet Général et sous Noms de domaine alternatifs, cliquez sur Ajouter un domaine

2. Saisissez le domaine pour lequel vous configurez votre sous-répertoire, par ex. example.com et cliquez sur Suivant

3. Sélectionnez votre certificat TLS existant, ou créez-en un nouveau si nécessaire, puis cliquez sur Suivant à nouveau

9

Configurer les enregistrements DNS Route 53 depuis CloudFront

Si vous utilisez Route 53 pour le DNS, vous devrez créer ou mettre à jour vos enregistrements DNS pour pointer vers votre distribution CloudFront.

1. Tout en restant sur la page principale de votre distribution CloudFront, assurez-vous d’être sur l’onglet Général puis sous l’URL que vous avez configurée dans Noms de domaine alternatifs, cliquez sur Acheminer les domaines vers CloudFront.

2. Cliquez sur Configurer l’acheminement automatiquement pour créer des enregistrements DNS A et AAAA pour votre domaine

Si vous n’utilisez pas Route 53, vous devrez mettre à jour les paramètres de votre fournisseur DNS pour diriger votre domaine vers le nom de domaine de votre distribution CloudFront. Vous pouvez le trouver dans les détails de la distribution CloudFront sous « Nom de domaine de la distribution ».

10

Testez votre configuration

Une fois que toutes les modifications ont été propagées (cela peut prendre 10 à 15 minutes) :

1. Ouvrez un navigateur et accédez à votre domaine avec le chemin du sous-répertoire (p. ex., https://example.com/docs)

2. Vous devriez voir votre site de documentation GitBook !

Si le site ne se charge pas immédiatement, essayez :

• Attendre quelques minutes de plus pour la propagation DNS

• Vider le cache de votre navigateur ou essayer une fenêtre de navigation privée

• Exécuter nslookup yourdomain.com dans le terminal pour vérifier que le DNS se résout correctement

• Vérifier que l’état de la distribution CloudFront est « Activé » et non « En cours »

Félicitations ! Votre documentation GitBook est désormais accessible via votre sous-répertoire personnalisé.

Dépannage

La fonction Lambda ne se déclenche pas :

• Assurez-vous d’avoir publié une version de votre fonction Lambda (et non pas $LATEST)

• Vérifiez que la fonction Lambda est dans la région us-east-1

• Vérifiez que la stratégie d’approbation inclut edgelambda.amazonaws.com

Le DNS ne se résout pas :

• Les changements DNS peuvent prendre du temps à se propager (jusqu’à 48 heures, bien que généralement beaucoup plus rapide)

• Vérifiez que vos enregistrements Route 53 pointent vers la bonne distribution CloudFront

• Vérifiez que vous avez supprimé tout ancien enregistrement DNS en conflit

Erreurs de certificat SSL :

• Assurez-vous que votre certificat SSL dans AWS Certificate Manager inclut votre domaine personnalisé

• Les certificats pour CloudFront doivent être créés dans la région us-east-1

Sous-répertoire ne fonctionne pas :

• Vérifiez le SOUS_RÉPERTOIRE valeur dans votre fonction Lambda correspond à ce que vous avez configuré dans GitBook

• Vérifiez que le target dans votre fonction Lambda est correct

• Examinez les journaux CloudFront pour voir si les requêtes atteignent la distribution