L’alternative Open Source à Notion, initiative étatique en collaboration avec l’Allemagne, est devenu le sujet de discussion numéro 1 sur Hacker News ces dernières 24h. Dans ce post, nous vous expliquons comment déployer Docs et le configurer sur Clever Cloud.
Qu’est-ce que Docs ?
Docs n’est pas qu’une alternative à Notion : c’est également un projet collaboratif émanant de la Direction Interministérielle du Numérique (DINUM pour les intimes) et son équivalent approximatif allemand, le Zentrum Digitale Souveränität (ZENDIS, ou Centre de la Souveraineté Numérique).
Docs fait partie des initiatives souveraines numériques des États, non seulement dans leur utilisation des outils numériques, mais également dans leur création. Chez Clever Cloud, nous avons déjà l’occasion de travailler au quotidien avec différents ministères, et nous sommes fiers de pouvoir contribuer à la diffusion de ces outils.
Docs étant configuré actuellement pour tourner sur Kubernetes, nous avons exploré les possibilités pour déployer Docs en utilisant Clever Cloud plutôt qu’un cluster kube. Bien sûr, il sera toujours possible de le déployer en utilisant Kubernetes lorsque notre produit de kube managé sera à disposition.
Comment déployer Docs sur Clever Cloud ?
Docs se compose de deux applications principales :
- Un backend (une API Rest Django) dans
src/backend - Un frontend (principalement reposant sur Next.js et des workspaces yarn) dans
src/frontend
Et intègre les dépendances suivantes :
- Une base de donnée PostgreSQL
- Une Redis
- Un Keycloak (optionnel)
Pour le déployer sur Clever Cloud, optez pour une application Python pour le backend, et une application Node.js pour le frontend. Inutile de versioner chaque sous-dossier. Vous pouvez pousser votre code avec Git depuis la racine du dépôt. Précisez simplement le sous-dossier à déployer grâce à la variable APP_FOLDER pour chacune de vos applications.
Déploiement du backend
Pour prendre en compte les variables d’environnement injectées au runtime sur Clever Cloud, nous avons apporté quelques modifications mineures au code. Nous avons également renommé les variables d’environnement de la base de données PostgreSQL et du stockage S3. Cette dernière modification permet de modifier la base de donnée ou les buckets, de changer d’add-on et de renouveler les identifiants sans devoir modifier manuellement la valeur des variables injectées dans l’application. Pour un déploiement fluide de Docs sur Clever Cloud, clonez la branche en cours de développement sur notre fork.
Ensuite, sur Clever Cloud :
- Créez une application Python
- Ajoutez une base de données PostrgreSQL
- Créez un add-on Cellar (ou créez directement le bucket si vous en avez déjà un) et connectez-le à l’application
- Créez un add-on Redis et connectez-le à l’application
- Ajoutez les variables d’environnement minimales de configuration à votre application :
APP_FOLDER="/src/backend"
CC_PYTHON_MODULE="impress.wsgi:application"
CC_PYTHON_VERSION="3"
CC_TROUBLESHOOT="true"
CELLAR_STORAGE_BUCKET_NAME="your-bucket-name"
DJANGO_ALLOWED_HOSTS="frontend-url/*"
DJANGO_CONFIGURATION="Development" / "Production"
DJANGO_SECRET_KEY="YourNewlyGeneratedKeyHere"
DJANGO_SETTINGS_MODULE="impress.settings"
DJANGO_SUPERUSER_PASSWORD=""
OIDC_OP_AUTHORIZATION_ENDPOINT="<>"
OIDC_OP_JWKS_ENDPOINT="<>"
OIDC_OP_TOKEN_ENDPOINT="<>"
OIDC_OP_USER_ENDPOINT="<>"
OIDC_RP_CLIENT_SECRET=""
STATIC_URL="frontend url"
- Cliquez sur l’onglet Configuration publiée et ajoutez les variables à mutualiser avec le frontend (la configuration Cellar et Keycloak, si vous en ajoutez un).
Dans votre application, ajoutez la remote fournie dans le tableau de bord de l’application Python (onglet Information) et nommez-la clever-backend, par exemple.
Poussez le code, une fois déployée, vous pourrez vous connecter à l’interface d’administration de l’API sur backend-url/admin.
Déploiement du frontend
Le frontend de Docs requiert beaucoup moins de dépendances. Celui est configuré pour utiliser des worspaces yarn, qui facilitent aussi bien la maintenance que le déploiement de plusieurs applications sur une seule machine virtuelle sur Clever Cloud.
- Sur Clever Cloud :
- Créez une application Node.js
- Ajoutez les variables d’environnement suivantes :
APP_FOLDER="./src/frontend"
CC_NODE_BUILD_TOOL="yarn"
CC_PRE_BUILD_HOOK="cd ./src/frontend && yarn install --frozen-lockfile && yarn app:build"
CC_RUN_COMMAND="cd ./src/frontend && yarn app:start"
CC_TROUBLESHOOT="true"
NEXT_PUBLIC_API_ORIGIN=""
NEXT_PUBLIC_SW_DEACTIVATED="true"
NODE_OPTIONS="--max-old-space-size=4096"
- Connectez l’application au backend (onglet services liées), ainsi qu’à l’add-on de base de données.
Dans votre application, ajoutez la remote fournie dans le tableau de bord de l’application Node.js (onglet Information) et nommez-la clever-frontend, par exemple.
Poussez le code, et vous pourrez vous connecter à partir de l’authentification que vous aurez définies avec Keycloak ou depuis l’API Django.
Allez plus loin avec Docs
Cet article présente un exemple pour déployer Docs sur Clever Cloud, Docs est cependant un projet riche intégrant de multiples fonctionnalités que vous pouvez activer ou personnaliser.
Pour travailler en local, vous trouverez des instructions pour démarrer le frontend ici, et pour démarrer le backend ici. Nous accueillons avec plaisir les questions et les contributions.