The open-source alternative to Notion, a French government initiative in collaboration with Germany, has become the number 1 topic of discussion on Hacker News over the last 24 hours. In this post, we explain how to deploy and configure Docs on Clever Cloud.
What is Docs?
Docs isn’t just an alternative to Notion: it’s also a collaborative project from the Direction Interministérielle du Numérique (DINUM) and its German equivalent, the Zentrum Digitale Souveränität (ZENDIS, or Center for Digital Sovereignty).
Docs is one of many initiatives aimed at ensuring the digital sovereignty of governments , not only in their use of digital tools, but also in their creation. At Clever Cloud, we’ve already had the opportunity to work with various ministries on a daily basis, and we’re proud to be able to contribute to the diffusion of these tools.
As Docs currently runs on Kubernetes, we have explored the possibilities of deploying it using Clever Cloud rather than a kube cluster. Of course, you’ll be able to deploy it using Kubernetes when our managed kube product becomes available.
How to deploy Docs on Clever Cloud
Docs consists of two main applications:
- A backend (a Django API Rest) in src/backend
- A frontend (mainly based on Next.js and yarn workspaces) in src/frontend
And integrates the following dependencies :
- PostgreSQL database
- Redis
- Keycloak (optional)
To deploy it on Clever Cloud, opt for a Python application for the backend, and a Node.js application for the frontend. There’s no need to version each subfolder; you can push your code with Git from the repository root and specify which subfolder to deploy using the APP_FOLDER variable for each of your applications.
Backend deployment
To take the value from the environment variables injected at runtime on Clever Cloud, we’ve made a few minor modifications to the code, and also renamed the environment variables for the PostgreSQL database and S3 storage. This last modification allows you to modify the database or buckets, change add-ons and renew identifiers without having to manually modify the value of the variables injected into the application. For smooth deployment of Docs on Clever Cloud, clone the branch under development on our fork.
Then, on Clever Cloud:
- Create a Python application
- Add a PostrgreSQL database
- Create a Cellar add-on (or create the bucket directly, if you already have one) and connect it to the application.
- Create a Redis add-on and connect it to the application
- Add the minimum configuration environment variables to your 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"
Click on the Exposed configuration tab and add the variables to be shared with the frontend (the Cellar configuration and Keycloak, if you’re adding one).
In your application, add the remote provided in the Python application dashboard (Information tab) and name it clever-backend, for example.
Once deployed, you’ll be able to connect to the API administration interface on backend-url/admin.
Deploying the frontend
The Docs frontend requires far fewer dependencies, this one is configured to use yarn worspaces that facilitate both maintenance and the deployment of multiple applications on a single virtual machine on Clever Cloud.
On Clever Cloud:
- Create a Node.js application
- Add the following environment variables:
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"
- Connect the application to the backend (Linked services tab), as well as to the database add-on.
- In your application, add the remote provided in the Node.js application dashboard (Information tab) and name it clever-frontend, for example.
Push the code, and you’ll be able to connect using the authentication you’ve defined with Keycloak or the Django API.
Go further with Docs
This article presents an example of deployment on Clever Cloud, but Docs is a rich project with multiple functionalities that you can activate or customize. To work locally, you’ll find instructions for starting the frontend here, and for starting the backend here. We welcome questions and contributions!