Configuration d’un sous-répertoire avec AWS à l’aide de CloudFront et Route 53

Hébergez votre documentation dans un sous-répertoire /docs à l’aide d’AWS CloudFront et Route 53.

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

1

Configuration de votre site GitBook

Dans votre organisation GitBook, cliquez sur le nom de votre site de documentation dans la barre latérale, puis cliquez 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.

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

Sous Configuration supplémentaire, vous verrez désormais 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 Créer une fonction .

Choisissez Créer à partir de zéro, puis :

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

• Sélectionnez Node.js comme runtime (utilisez la version la plus récente disponible).

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

Cliquez sur Créer une fonction.

3

Mettez à jour le code de la fonction Lambda

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

export const handler = async (event) => {
	const request = event.Records[0].cf.request;
	
	// à mettre à jour si votre sous-répertoire n’est pas /docs
	const subdirectory = '/docs';
	
	// à mettre à jour avec l’URL de votre proxy ci-dessous
	const target = new URL('<URL du proxy que vous avez obtenu 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éployez pour enregistrer vos modifications.

4

Configurez 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 onglet

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 Relations d’approbation onglet

5. Cliquez sur Modifier la politique d’approbation

6. Remplacez la politique d’approbation par la suivante :

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

Cliquez sur Mettre à jour la politique 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 Actions menu déroulant en haut à droite

2. Sélectionnez Publier une nouvelle version

3. Ajoutez éventuellement 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 (Virginie du Nord). 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 spécifiés, conservez les valeurs par défaut.

Spécifier l’origine

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

Paramètres de cache

Paramètre	Champ 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 à nouveau sur Suivant .

Cliquez sur Créer une distribution.

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

7

Associez 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. Accédez à l’onglet Comportements onglet

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 la champ ARN de la fonction Lambda collez l’ARN de votre fonction Lambda publiée (depuis 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

Configurez 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. Entrez 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

Configurez 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 qu’ils pointent 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 Routage des domaines vers CloudFront.

2. Cliquez sur Configurer le routage 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 faire pointer 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 (par ex. https://example.com/docs)

2. Vous devriez voir votre site de documentation GitBook !

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

• d’attendre quelques minutes supplémentaires pour la propagation DNS

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

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

• de vérifier que le statut 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 (sans utiliser $LATEST)

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

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

Le DNS ne se résout pas :

• Les modifications DNS peuvent mettre du temps à se propager (jusqu’à 48 heures, bien que ce soit 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

Le sous-répertoire ne fonctionne pas :

• Vérifiez la 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

• Passez en revue les journaux CloudFront pour voir si les requêtes atteignent la distribution