From 3f4329d0bf2e4511358822845edcc698290a5ac3 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 29 Mar 2025 21:16:19 +0100 Subject: [PATCH] docs: add index and initial documentation pages - Added index.md with TOC - Created pages: introduction, development, deployment - Renamed deployment file for clarity - Improved formatting across pages --- README.md | 101 ++--------------- docs/api.md | 14 +++ docs/development.md | 97 ++++++++++++++++ docs/index.md | 38 +++++++ docs/installation-k8s.md | 231 ++++++++++++++++++++++++++++++++++++++ docs/installation.md | 234 +++------------------------------------ docs/introduction.md | 42 +++++++ 7 files changed, 445 insertions(+), 312 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/development.md create mode 100644 docs/index.md create mode 100644 docs/installation-k8s.md create mode 100644 docs/introduction.md diff --git a/README.md b/README.md index 67d0757cf..3b5b60ac0 100644 --- a/README.md +++ b/README.md @@ -46,105 +46,22 @@ Docs is a collaborative text editor designed to address common challenges in kno ## Getting started πŸ”§ -### Test it - -Test Docs on your browser by logging in on this [environment](https://impress-preprod.beta.numerique.gouv.fr/) - -``` -email: test.docs@yopmail.com -password: I'd<3ToTestDocs -``` - -### Run it locally - -> ⚠️ Running Docs locally using the methods described below is for testing purposes only. It is based on building Docs using Minio as the S3 storage solution but you can choose any S3 compatible object storage of your choice. - -**Prerequisite** - -Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop: - -```shellscript -$ docker -v - -Docker version 20.10.2, build 2291f61 - -$ docker compose version - -Docker Compose version v2.32.4 -``` - -> ⚠️ You may need to run the following commands with sudo but this can be avoided by adding your user to the `docker` group. - -**Project bootstrap** - -The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/): - -```shellscript -$ make bootstrap FLUSH_ARGS='--no-input' -``` - -This command builds the `app` container, installs dependencies, performs database migrations and compile translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues. - -Your Docker services should now be up and running πŸŽ‰ - -You can access to the project by going to . +For detailed guides on setup, development, and deployment, check out the documentation available on our [GitHub Pages site](https://suitenumerique.github.io/docs/). -You will be prompted to log in, the default credentials are: +Quick links: -``` -username: impress -password: impress -``` +- πŸ“š [Documentation Overview](https://suitenumerique.github.io/docs/) +- πŸ§‘β€πŸ’» [Development Guide](https://suitenumerique.github.io/docs/development) +- πŸš€ [Deployment Options](https://suitenumerique.github.io/docs/deployment) -πŸ“ Note that if you need to run them afterwards, you can use the eponym Make rule: - -```shellscript -$ make run -``` -⚠️ For the frontend developer, it is often better to run the frontend in development mode locally. - -To do so, install the frontend dependencies with the following command: - -```shellscript -$ make frontend-development-install -``` - -And run the frontend locally in development mode with the following command: - -```shellscript -$ make run-frontend-development -``` - -To start all the services, except the frontend container, you can use the following command: - -```shellscript -$ make run-backend -``` - -**Adding content** -You can create a basic demo site by running: - -```shellscript -$ make demo -``` +### Test it -Finally, you can check all available Make rules using: +Test Docs on your browser by logging in on this [environment](https://impress-preprod.beta.numerique.gouv.fr/) -```shellscript -$ make help ``` - -**Django admin** - -You can access the Django admin site at - -. - -You first need to create a superuser account: - -```shellscript -$ make superuser +email: test.docs@yopmail.com +password: I'd<3ToTestDocs ``` ## Feedback πŸ™‹β€β™‚οΈπŸ™‹β€β™€οΈ diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 000000000..c40c65495 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,14 @@ +# πŸ“‘ API Reference + +## 🌐 API Overview + +Our API is fully documented using **Swagger UI**. + +πŸ‘‰ View the interactive docs here: +[πŸ”— Swagger UI](http://localhost:8071/api/v1.0/swagger/) + + + +## Authentication + +For cookieAuth (apiKey) use Y_PROVIDER_API_KEY. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 000000000..1fd3c2414 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,97 @@ +# Development + +### Run it locally + +> ⚠️ Running Docs locally using the methods described below is for testing purposes only. It is based on building Docs using Minio as the S3 storage solution but you can choose any S3 compatible object storage of your choice. + +**Prerequisite** + +Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop: + +```shellscript +$ docker -v + +Docker version 20.10.2, build 2291f61 + +$ docker compose version + +Docker Compose version v2.32.4 +``` + +> ⚠️ You may need to run the following commands with sudo but this can be avoided by adding your user to the `docker` group. + +**Project bootstrap** + +The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/): + +```shellscript +$ make bootstrap FLUSH_ARGS='--no-input' +``` + +This command builds the `app` container, installs dependencies, performs database migrations and compile translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues. + +Your Docker services should now be up and running πŸŽ‰ + +You can access to the project by going to . + +You will be prompted to log in, the default credentials are: + +``` +username: impress +password: impress +``` + +πŸ“ Note that if you need to run them afterwards, you can use the eponym Make rule: + +```shellscript +$ make run +``` + +⚠️ For the frontend developer, it is often better to run the frontend in development mode locally. + +To do so, install the frontend dependencies with the following command: + +```shellscript +$ make frontend-development-install +``` + +And run the frontend locally in development mode with the following command: + +```shellscript +$ make run-frontend-development +``` + +To start all the services, except the frontend container, you can use the following command: + +```shellscript +$ make run-backend +``` + +**Adding content** +You can create a basic demo site by running: + +```shellscript +$ make demo +``` + +Finally, you can check all available Make rules using: + +```shellscript +$ make help +``` + +**Django admin** + +You can access the Django admin site at + +. + +You first need to create a superuser account: + +```shellscript +$ make superuser +``` + +### Development environment + +@todo: the linter, sdk project files, cursor prompt diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..7ce467d99 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,38 @@ +# πŸ“– Welcome to the Docs Documentation + +Below is a table of contents to help you navigate the documentation +files available in this folder. + +## πŸ“š Table of Contents + +### 🏁 Getting Started +- πŸ“– [Introduction](./introduction.md) +- πŸ‘¨β€πŸ’» [Development Setup](./development.md) +- 🀝 [Contributing](https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md) + +### πŸ“‘ API +- 🌐 [API Overview](./api.md) + +### πŸš€ Deployment Options +- βš™οΈ [Installation Guide](./installation.md) + - πŸ’» [Standalone Installation](./installation-standalone.md) + - 🐳 [Docker Setup](./installation-docker.md) + - ☸️ [Kubernetes Deployment](./installation-k8s.md) + - πŸ› οΈ [Advanced Configuration](./installation-advanced.md) + +### πŸ”– Release & Maintenance +- πŸ—’οΈ [Release Notes](./release.md) +- 🧾 [Changelog](https://github.com/suitenumerique/docs/blob/main/CHANGELOG.md) +- ⬆️ [Upgrade Guide](https://github.com/suitenumerique/docs/blob/main/UPGRADE.md) +- πŸ” [Security Policy](https://github.com/suitenumerique/docs/blob/main/SECURITY.md) + +### 🌍 Community & Governance +- πŸ“œ [Code of Conduct](https://github.com/suitenumerique/docs/blob/main/CODE_OF_CONDUCT.md) + + + + + +Looking for help? Reach out via [Matrix](https://matrix.to/#/#docs-official:matrix.org) or email us at [docs@numerique.gouv.fr](mailto:docs@numerique.gouv.fr). + +[Back to repo](https://github.com/suitenumerique/docs) diff --git a/docs/installation-k8s.md b/docs/installation-k8s.md new file mode 100644 index 000000000..d0f6e0451 --- /dev/null +++ b/docs/installation-k8s.md @@ -0,0 +1,231 @@ +# Installation on a k8s cluster + +This document is a step-by-step guide that describes how to install Docs on a k8s cluster without AI features. It's a teaching document to learn how it's work. It needs to be adapt for production environment. + + +## Prerequisites + +- k8s cluster with an nginx-ingress controller +- an OIDC provider (if you don't have one, we will provide an example) +- a PostgreSQL server (if you don't have one, we will provide an example) +- a Memcached server (if you don't have one, we will provide an example) +- a S3 bucket (if you don't have one, we will provide an example) + +### Test cluster + +If you do not have a test cluster, you can install everything on a local kind cluster. In this case, the simplest way is to use our script **bin/start-kind.sh**. + +To be able to use the script, you will need to install: + +- Docker (https://docs.docker.com/desktop/) +- Kind (https://kind.sigs.k8s.io/docs/user/quick-start/#installation) +- Mkcert (https://github.com/FiloSottile/mkcert#installation) +- Helm (https://helm.sh/docs/intro/quickstart/#install-helm) + +``` +./bin/start-kind.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 4700 100 4700 0 0 92867 0 --:--:-- --:--:-- --:--:-- 94000 +0. Create ca +The local CA is already installed in the system trust store! πŸ‘ +The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! πŸ‘ + + +Created a new certificate valid for the following names πŸ“œ + - "127.0.0.1.nip.io" + - "*.127.0.0.1.nip.io" + +Reminder: X.509 wildcards only go one level deep, so this won't match a.b.127.0.0.1.nip.io ℹ️ + +The certificate is at "./127.0.0.1.nip.io+1.pem" and the key at "./127.0.0.1.nip.io+1-key.pem" βœ… + +It will expire on 24 March 2027 πŸ—“ + +1. Create registry container unless it already exists +2. Create kind cluster with containerd registry config dir enabled +Creating cluster "suite" ... + βœ“ Ensuring node image (kindest/node:v1.27.3) πŸ–Ό + βœ“ Preparing nodes πŸ“¦ + βœ“ Writing configuration πŸ“œ + βœ“ Starting control-plane πŸ•ΉοΈ + βœ“ Installing CNI πŸ”Œ + βœ“ Installing StorageClass πŸ’Ύ +Set kubectl context to "kind-suite" +You can now use your cluster with: + +kubectl cluster-info --context kind-suite + +Thanks for using kind! 😊 +3. Add the registry config to the nodes +4. Connect the registry to the cluster network if not already connected +5. Document the local registry +configmap/local-registry-hosting created +Warning: resource configmaps/coredns is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically. +configmap/coredns configured +deployment.apps/coredns restarted +6. Install ingress-nginx +namespace/ingress-nginx created +serviceaccount/ingress-nginx created +serviceaccount/ingress-nginx-admission created +role.rbac.authorization.k8s.io/ingress-nginx created +role.rbac.authorization.k8s.io/ingress-nginx-admission created +clusterrole.rbac.authorization.k8s.io/ingress-nginx created +clusterrole.rbac.authorization.k8s.io/ingress-nginx-admission created +rolebinding.rbac.authorization.k8s.io/ingress-nginx created +rolebinding.rbac.authorization.k8s.io/ingress-nginx-admission created +clusterrolebinding.rbac.authorization.k8s.io/ingress-nginx created +clusterrolebinding.rbac.authorization.k8s.io/ingress-nginx-admission created +configmap/ingress-nginx-controller created +service/ingress-nginx-controller created +service/ingress-nginx-controller-admission created +deployment.apps/ingress-nginx-controller created +job.batch/ingress-nginx-admission-create created +job.batch/ingress-nginx-admission-patch created +ingressclass.networking.k8s.io/nginx created +validatingwebhookconfiguration.admissionregistration.k8s.io/ingress-nginx-admission created +secret/mkcert created +deployment.apps/ingress-nginx-controller patched +7. Setup namespace +namespace/impress created +Context "kind-suite" modified. +secret/mkcert created +$ kubectl -n ingress-nginx get po +NAME READY STATUS RESTARTS AGE +ingress-nginx-admission-create-t55ph 0/1 Completed 0 2m56s +ingress-nginx-admission-patch-94dvt 0/1 Completed 1 2m56s +ingress-nginx-controller-57c548c4cd-2rx47 1/1 Running 0 2m56s +``` +When your k8s cluster is ready (the ingress nginx controller is up), you can start the deployment. This cluster is special because it uses the *.127.0.0.1.nip.io domain and mkcert certificates to have full HTTPS support and easy domain name management. + +Please remember that *.127.0.0.1.nip.io will always resolve to 127.0.0.1, except in the k8s cluster where we configure CoreDNS to answer with the ingress-nginx service IP. + +## Preparation + +### What will you use to authenticate your users ? + +Docs uses OIDC, so if you already have an OIDC provider, obtain the necessary information to use it. In the next step, we will see how to configure Django (and thus Docs) to use it. If you do not have a provider, we will show you how to deploy a local Keycloak instance (this is not a production deployment, just a demo). + +``` +$ kubectl create namespace impress +$ kubectl config set-context --current --namespace=impress +$ helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak -f examples/keycloak.values.yaml +$ #wait until +$ kubectl get po +NAME READY STATUS RESTARTS AGE +keycloak-0 1/1 Running 0 6m48s +keycloak-postgresql-0 1/1 Running 0 6m48s +``` + +From here the important informations you will need are : + +``` +OIDC_OP_JWKS_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/certs +OIDC_OP_AUTHORIZATION_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/auth +OIDC_OP_TOKEN_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/token +OIDC_OP_USER_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/userinfo +OIDC_OP_LOGOUT_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/session/end +OIDC_RP_CLIENT_ID: impress +OIDC_RP_CLIENT_SECRET: ThisIsAnExampleKeyForDevPurposeOnly +OIDC_RP_SIGN_ALGO: RS256 +OIDC_RP_SCOPES: "openid email" +``` + +You can find these values in **examples/keycloak.values.yaml** + +### Find redis server connexion values + +Impress need a redis so we will start by deploying a redis : + +``` +$ helm install redis oci://registry-1.docker.io/bitnamicharts/redis -f examples/redis.values.yaml +$ kubectl get po +NAME READY STATUS RESTARTS AGE +keycloak-0 1/1 Running 0 26m +keycloak-postgresql-0 1/1 Running 0 26m +redis-master-0 1/1 Running 0 35s +``` + +### Find postgresql connexion values + +Impress uses a postgresql db as backend so if you have a provider, obtain the necessary information to use it. If you do not have, you can install a postgresql testing environment as follow: + +``` +$ helm install postgresql oci://registry-1.docker.io/bitnamicharts/postgresql -f examples/postgresql.values.yaml +$ kubectl get po +NAME READY STATUS RESTARTS AGE +keycloak-0 1/1 Running 0 28m +keycloak-postgresql-0 1/1 Running 0 28m +postgresql-0 1/1 Running 0 14m +redis-master-0 1/1 Running 0 42s +``` + +From here important informations you will need are : + +``` +DB_HOST: postgres-postgresql +DB_NAME: impress +DB_USER: dinum +DB_PASSWORD: pass +DB_PORT: 5432 +POSTGRES_DB: impress +POSTGRES_USER: dinum +POSTGRES_PASSWORD: pass +``` + +### Find s3 bucket connexion values + +Impress uses a s3 bucket to store documents so if you have a provider obtain the necessary information to use it. If you do not have, you can install a local minio testing environment as follow: + +``` +$ helm install minio oci://registry-1.docker.io/bitnamicharts/minio -f examples/minio.values.yaml +$ kubectl get po +NAME READY STATUS RESTARTS AGE +keycloak-0 1/1 Running 0 38m +keycloak-postgresql-0 1/1 Running 0 38m +minio-84f5c66895-bbhsk 1/1 Running 0 42s +minio-provisioning-2b5sq 0/1 Completed 0 42s +postgresql-0 1/1 Running 0 24m +redis-master-0 1/1 Running 0 10m +``` + +## Deployment + +Now you are ready to deploy Impress without AI. AI requiered more dependancies (openai API). To deploy impress you need to provide all previous informations to the helm chart. + +``` +$ helm repo add impress https://suitenumerique.github.io/docs/ +$ helm repo update +$ helm install impress impress/docs -f examples/impress.values.yaml +$ kubectl get po +NAME READY STATUS RESTARTS AGE +impress-docs-backend-96558758d-xtkbp 0/1 Running 0 79s +impress-docs-backend-createsuperuser-r7ltc 0/1 Completed 0 79s +impress-docs-backend-migrate-c949s 0/1 Completed 0 79s +impress-docs-frontend-6749f644f7-p5s42 1/1 Running 0 79s +impress-docs-y-provider-6947fd8f54-78f2l 1/1 Running 0 79s +keycloak-0 1/1 Running 0 48m +keycloak-postgresql-0 1/1 Running 0 48m +minio-84f5c66895-bbhsk 1/1 Running 0 10m +minio-provisioning-2b5sq 0/1 Completed 0 10m +postgresql-0 1/1 Running 0 34m +redis-master-0 1/1 Running 0 20m +``` + +## Test your deployment + +In order to test your deployment you have to login to your instance. If you use exclusively our examples you can do : + +``` +$ kubectl get ingress +NAME CLASS HOSTS ADDRESS PORTS AGE +impress-docs impress.127.0.0.1.nip.io localhost 80, 443 114s +impress-docs-admin impress.127.0.0.1.nip.io localhost 80, 443 114s +impress-docs-collaboration-api impress.127.0.0.1.nip.io localhost 80, 443 114s +impress-docs-media impress.127.0.0.1.nip.io localhost 80, 443 114s +impress-docs-ws impress.127.0.0.1.nip.io localhost 80, 443 114s +keycloak keycloak.127.0.0.1.nip.io localhost 80 49m +``` + +You can use impress on https://impress.127.0.0.1.nip.io. The provisionning user in keycloak is impress/impress. + diff --git a/docs/installation.md b/docs/installation.md index 9f911b61f..a7e77b639 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,230 +1,24 @@ -# Installation on a k8s cluster +# πŸš€ Deployment Options -This document is a step-by-step guide that describes how to install Docs on a k8s cluster without AI features. It's a teaching document to learn how it's work. It needs to be adapt for production environment. +--- -## Prerequisites +### βœ… [Standalone Installation](./installation-standalone.md) +> **Todo**: Add instructions for installing Docs without Docker or orchestration β€” ideal for advanced users or bare-metal setups. -- k8s cluster with an nginx-ingress controller -- an OIDC provider (if you don't have one, we will provide an example) -- a PostgreSQL server (if you don't have one, we will provide an example) -- a Memcached server (if you don't have one, we will provide an example) -- a S3 bucket (if you don't have one, we will provide an example) +--- -### Test cluster +### 🐳 [Docker Setup](./installation-docker.md) +> **Todo**: Add setup steps using Docker and Docker Compose β€” great for local testing or small team deployments. -If you do not have a test cluster, you can install everything on a local kind cluster. In this case, the simplest way is to use our script **bin/start-kind.sh**. +--- -To be able to use the script, you will need to install: +### ☸️ [Kubernetes Deployment](./installation-k8s.md) -- Docker (https://docs.docker.com/desktop/) -- Kind (https://kind.sigs.k8s.io/docs/user/quick-start/#installation) -- Mkcert (https://github.com/FiloSottile/mkcert#installation) -- Helm (https://helm.sh/docs/intro/quickstart/#install-helm) +Deploy Docs on a scalable, production-ready Kubernetes cluster. This includes persistent storage, service orchestration, and configuration options for custom domains, ingress, and more. -``` -./bin/start-kind.sh - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 4700 100 4700 0 0 92867 0 --:--:-- --:--:-- --:--:-- 94000 -0. Create ca -The local CA is already installed in the system trust store! πŸ‘ -The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! πŸ‘ +πŸ“„ See [installation-k8s.md](./installation-k8s.md) for full instructions. +--- -Created a new certificate valid for the following names πŸ“œ - - "127.0.0.1.nip.io" - - "*.127.0.0.1.nip.io" - -Reminder: X.509 wildcards only go one level deep, so this won't match a.b.127.0.0.1.nip.io ℹ️ - -The certificate is at "./127.0.0.1.nip.io+1.pem" and the key at "./127.0.0.1.nip.io+1-key.pem" βœ… - -It will expire on 24 March 2027 πŸ—“ - -1. Create registry container unless it already exists -2. Create kind cluster with containerd registry config dir enabled -Creating cluster "suite" ... - βœ“ Ensuring node image (kindest/node:v1.27.3) πŸ–Ό - βœ“ Preparing nodes πŸ“¦ - βœ“ Writing configuration πŸ“œ - βœ“ Starting control-plane πŸ•ΉοΈ - βœ“ Installing CNI πŸ”Œ - βœ“ Installing StorageClass πŸ’Ύ -Set kubectl context to "kind-suite" -You can now use your cluster with: - -kubectl cluster-info --context kind-suite - -Thanks for using kind! 😊 -3. Add the registry config to the nodes -4. Connect the registry to the cluster network if not already connected -5. Document the local registry -configmap/local-registry-hosting created -Warning: resource configmaps/coredns is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically. -configmap/coredns configured -deployment.apps/coredns restarted -6. Install ingress-nginx -namespace/ingress-nginx created -serviceaccount/ingress-nginx created -serviceaccount/ingress-nginx-admission created -role.rbac.authorization.k8s.io/ingress-nginx created -role.rbac.authorization.k8s.io/ingress-nginx-admission created -clusterrole.rbac.authorization.k8s.io/ingress-nginx created -clusterrole.rbac.authorization.k8s.io/ingress-nginx-admission created -rolebinding.rbac.authorization.k8s.io/ingress-nginx created -rolebinding.rbac.authorization.k8s.io/ingress-nginx-admission created -clusterrolebinding.rbac.authorization.k8s.io/ingress-nginx created -clusterrolebinding.rbac.authorization.k8s.io/ingress-nginx-admission created -configmap/ingress-nginx-controller created -service/ingress-nginx-controller created -service/ingress-nginx-controller-admission created -deployment.apps/ingress-nginx-controller created -job.batch/ingress-nginx-admission-create created -job.batch/ingress-nginx-admission-patch created -ingressclass.networking.k8s.io/nginx created -validatingwebhookconfiguration.admissionregistration.k8s.io/ingress-nginx-admission created -secret/mkcert created -deployment.apps/ingress-nginx-controller patched -7. Setup namespace -namespace/impress created -Context "kind-suite" modified. -secret/mkcert created -$ kubectl -n ingress-nginx get po -NAME READY STATUS RESTARTS AGE -ingress-nginx-admission-create-t55ph 0/1 Completed 0 2m56s -ingress-nginx-admission-patch-94dvt 0/1 Completed 1 2m56s -ingress-nginx-controller-57c548c4cd-2rx47 1/1 Running 0 2m56s -``` - -When your k8s cluster is ready (the ingress nginx controller is up), you can start the deployment. This cluster is special because it uses the \*.127.0.0.1.nip.io domain and mkcert certificates to have full HTTPS support and easy domain name management. - -Please remember that \*.127.0.0.1.nip.io will always resolve to 127.0.0.1, except in the k8s cluster where we configure CoreDNS to answer with the ingress-nginx service IP. - -## Preparation - -### What will you use to authenticate your users ? - -Docs uses OIDC, so if you already have an OIDC provider, obtain the necessary information to use it. In the next step, we will see how to configure Django (and thus Docs) to use it. If you do not have a provider, we will show you how to deploy a local Keycloak instance (this is not a production deployment, just a demo). - -``` -$ kubectl create namespace impress -$ kubectl config set-context --current --namespace=impress -$ helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak -f examples/keycloak.values.yaml -$ #wait until -$ kubectl get po -NAME READY STATUS RESTARTS AGE -keycloak-0 1/1 Running 0 6m48s -keycloak-postgresql-0 1/1 Running 0 6m48s -``` - -From here the important informations you will need are : - -``` -OIDC_OP_JWKS_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/certs -OIDC_OP_AUTHORIZATION_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/auth -OIDC_OP_TOKEN_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/token -OIDC_OP_USER_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/userinfo -OIDC_OP_LOGOUT_ENDPOINT: https://keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/session/end -OIDC_RP_CLIENT_ID: impress -OIDC_RP_CLIENT_SECRET: ThisIsAnExampleKeyForDevPurposeOnly -OIDC_RP_SIGN_ALGO: RS256 -OIDC_RP_SCOPES: "openid email" -``` - -You can find these values in **examples/keycloak.values.yaml** - -### Find redis server connexion values - -Impress need a redis so we will start by deploying a redis : - -``` -$ helm install redis oci://registry-1.docker.io/bitnamicharts/redis -f examples/redis.values.yaml -$ kubectl get po -NAME READY STATUS RESTARTS AGE -keycloak-0 1/1 Running 0 26m -keycloak-postgresql-0 1/1 Running 0 26m -redis-master-0 1/1 Running 0 35s -``` - -### Find postgresql connexion values - -Impress uses a postgresql db as backend so if you have a provider, obtain the necessary information to use it. If you do not have, you can install a postgresql testing environment as follow: - -``` -$ helm install postgresql oci://registry-1.docker.io/bitnamicharts/postgresql -f examples/postgresql.values.yaml -$ kubectl get po -NAME READY STATUS RESTARTS AGE -keycloak-0 1/1 Running 0 28m -keycloak-postgresql-0 1/1 Running 0 28m -postgresql-0 1/1 Running 0 14m -redis-master-0 1/1 Running 0 42s -``` - -From here important informations you will need are : - -``` -DB_HOST: postgres-postgresql -DB_NAME: impress -DB_USER: dinum -DB_PASSWORD: pass -DB_PORT: 5432 -POSTGRES_DB: impress -POSTGRES_USER: dinum -POSTGRES_PASSWORD: pass -``` - -### Find s3 bucket connexion values - -Impress uses a s3 bucket to store documents so if you have a provider obtain the necessary information to use it. If you do not have, you can install a local minio testing environment as follow: - -``` -$ helm install minio oci://registry-1.docker.io/bitnamicharts/minio -f examples/minio.values.yaml -$ kubectl get po -NAME READY STATUS RESTARTS AGE -keycloak-0 1/1 Running 0 38m -keycloak-postgresql-0 1/1 Running 0 38m -minio-84f5c66895-bbhsk 1/1 Running 0 42s -minio-provisioning-2b5sq 0/1 Completed 0 42s -postgresql-0 1/1 Running 0 24m -redis-master-0 1/1 Running 0 10m -``` - -## Deployment - -Now you are ready to deploy Impress without AI. AI requiered more dependancies (openai API). To deploy impress you need to provide all previous informations to the helm chart. - -``` -$ helm repo add impress https://suitenumerique.github.io/docs/ -$ helm repo update -$ helm install impress impress/docs -f examples/impress.values.yaml -$ kubectl get po -NAME READY STATUS RESTARTS AGE -impress-docs-backend-96558758d-xtkbp 0/1 Running 0 79s -impress-docs-backend-createsuperuser-r7ltc 0/1 Completed 0 79s -impress-docs-backend-migrate-c949s 0/1 Completed 0 79s -impress-docs-frontend-6749f644f7-p5s42 1/1 Running 0 79s -impress-docs-y-provider-6947fd8f54-78f2l 1/1 Running 0 79s -keycloak-0 1/1 Running 0 48m -keycloak-postgresql-0 1/1 Running 0 48m -minio-84f5c66895-bbhsk 1/1 Running 0 10m -minio-provisioning-2b5sq 0/1 Completed 0 10m -postgresql-0 1/1 Running 0 34m -redis-master-0 1/1 Running 0 20m -``` - -## Test your deployment - -In order to test your deployment you have to login to your instance. If you use exclusively our examples you can do : - -``` -$ kubectl get ingress -NAME CLASS HOSTS ADDRESS PORTS AGE -impress-docs impress.127.0.0.1.nip.io localhost 80, 443 114s -impress-docs-admin impress.127.0.0.1.nip.io localhost 80, 443 114s -impress-docs-collaboration-api impress.127.0.0.1.nip.io localhost 80, 443 114s -impress-docs-media impress.127.0.0.1.nip.io localhost 80, 443 114s -impress-docs-ws impress.127.0.0.1.nip.io localhost 80, 443 114s -keycloak keycloak.127.0.0.1.nip.io localhost 80 49m -``` - -You can use impress on https://impress.127.0.0.1.nip.io. The provisionning user in keycloak is impress/impress. \ No newline at end of file +### βš™οΈ [Advanced Configuration](./installation-advanced.md) +> **Todo**: Add guides on customizing environment variables, external services (e.g. MinIO, Redis), scaling strategies, and CI/CD integrations. diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..aa51a5499 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,42 @@ +# Introduction + +The Docs project is an open-source collaborative note-taking, wiki, and documentation platform designed to scale efficiently. It serves as an alternative to tools like Notion or Outline, emphasizing simplicity and real-time collaboration. The architecture of Docs is structured to support these goals, integrating various technologies and components. + +## πŸ› οΈ Quick Start + +Follow these steps to get the project up and running: + +```bash +git clone https://github.com/suitenumerique/docs.git && \ +cd docs && \ +make bootstrap FLUSH_ARGS='--no-input' +``` + +The last command prepares the application for use by building the necessary services, installing dependencies, applying migrations, and compiling translations β€” all in one step. + + +## 🧩 Core Components + +πŸ› οΈ Backend (Django + DRF) aka impress: +Powers the business logic, API endpoints, authentication, and permission management. Built with Django and the Django Rest Framework, it's the backbone of all server-side operations. + +πŸ–ΌοΈ Frontend (React): +The user interface is crafted with React, providing a fast, clean, and intuitive experience for document editing and navigation. + +🀝 Real-Time Collaboration (Yjs): +Enables multiplayer editing with real-time syncing using Yjs, a CRDT-based framework that ensures conflict-free collaboration across users and devices. + +🧠 AI Assistant: +Built-in AI actions let users generate, summarize, translate, and correct content, helping teams work faster and smarter. + + +## πŸ”Œ Integration with External Services + +πŸ“¦ Storage (MinIO): +Uses MinIO, an S3-compatible object storage system, to handle uploaded documents, media assets, and persistent file storage β€” ideal for scalable deployments. + +πŸ—ƒοΈ Database (PostgreSQL): +Relies on PostgreSQL for reliable and structured data management, ensuring transactional integrity and scalability across user and document data. + +⚑ Caching & Task Queues (Redis): +Leverages Redis for both caching and message queuing between services β€” boosting performance and enabling asynchronous operations like background processing.