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

Hébergez votre documentation avec un sous-répertoire /docs en utilisant 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 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 l’assistance si vous avez besoin de conseils pour des configurations alternatives.

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 sur Gérer le site ou ouvrez l’ Paramètres onglet. Ouvrez la Domaine et redirections section et, sous « Sous-répertoire », cliquez sur Configurer un sous-répertoire.

Entrez l’URL où vous souhaitez héberger votre documentation. Puis spécifiez le sous-répertoire pour l’accès à la documentation, par exemple example.com/docs, et 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.

Créer 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 dernière version disponible).
Laissez l’architecture et les autres paramètres par défaut.

Cliquez sur Créer une fonction.

Mettre à jour le code de la fonction Lambda

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

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 l’URL du proxy ci-dessous
	const target = new URL('<URL de proxy obtenue depuis GitBook>');

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

		// supprimer le slash final s’il est présent
		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.

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.

Dans votre fonction Lambda, cliquez sur Configuration onglet
Cliquez sur Autorisations dans la barre latérale gauche
Sous Rôle d’exécution, cliquez sur le nom du rôle pour l’ouvrir dans IAM
Cliquez sur le Relations de confiance onglet
Cliquez sur Modifier la politique de confiance
Remplacez la politique de confiance 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 politique pour enregistrer.

Publier votre fonction Lambda

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

Dans votre fonction Lambda, cliquez sur le Actions menu déroulant en haut à droite
Sélectionnez Publier une nouvelle version
Ajoutez éventuellement une description comme « Version initiale pour CloudFront »
Cliquez sur Publier
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 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.

Créer 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

Autres

Origine personnalisée

Le domaine principal de votre site web (p. ex., 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 les protections de sécurité de votre choix, puis cliquez sur Suivant à nouveau.

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.

Associer Lambda@Edge à CloudFront

Une fois votre distribution CloudFront déployée :

Cliquez sur l’ID de votre distribution pour ouvrir ses paramètres
Accédez à Comportements onglet
Sélectionnez le comportement par défaut et cliquez sur Modifier
Faites défiler jusqu’à Associations de fonctions
Sous Requête d’origine, sélectionnez Lambda@Edge
Dans le ARN de la fonction Lambda champ, collez l’ARN de votre fonction Lambda publiée (à partir de l’étape 5)
Vérifiez Inclure le corps pour permettre à la fonction d’accéder aux corps des requêtes si nécessaire
Cliquez sur Enregistrer les modifications

Configurer le domaine et les enregistrements DNS

Sur la page principale de votre distribution CloudFront, cliquez sur l’ Général onglet, puis sous Noms de domaine alternatifs, cliquez sur Ajouter un domaine
Entrez le domaine pour lequel vous configurez votre sous-répertoire, par ex. example.com et cliquez sur Suivant
Sélectionnez votre certificat TLS existant, ou créez-en un nouveau si nécessaire, puis cliquez sur Suivant à nouveau

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 les faire pointer vers votre distribution CloudFront.

Tout en restant sur la page principale de votre distribution CloudFront, assurez-vous d’être dans l’ Général onglet, puis sous l’URL que vous avez configurée dans Noms de domaine alternatifs, cliquez sur Routage des domaines vers CloudFront.
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 le trouverez dans les détails de la distribution CloudFront, sous « Nom de domaine de la distribution ».

Tester votre configuration

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

Ouvrez un navigateur et accédez à votre domaine avec le chemin du sous-répertoire (p. ex., https://example.com/docs)
Vous devriez voir votre site de documentation GitBook !

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

Attendre encore quelques minutes pour la propagation du 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 de ne pas utiliser $LATEST)
Vérifiez que la fonction Lambda se trouve dans la région us-east-1
Vérifiez que la politique de confiance inclut edgelambda.amazonaws.com

Le DNS ne se résout pas :

Les modifications DNS peuvent prendre du temps à se propager (jusqu’à 48 heures, bien que ce soit généralement bien plus rapide)
Vérifiez que vos enregistrements Route 53 pointent vers la bonne distribution CloudFront
Vérifiez que vous avez supprimé les anciens enregistrements 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 la valeur dans votre fonction Lambda correspond à ce que vous avez configuré dans GitBook
Vérifiez que target dans votre fonction Lambda est correct
Consultez les journaux CloudFront pour voir si les requêtes atteignent la distribution

Mis à jour il y a 29 jours

Ce contenu vous a-t-il été utile ?