doc: Docs guide

.github/styles/config/vocabularies/Doc/accept.txt

@@ -17,6 +17,7 @@ checkMe
 Clever Cloud
 CLI
 Cloud
+config
 Coraza
 Corepack
 CRDs
@@ -86,7 +87,9 @@ Sidekiq
 Symfony
 syslog
 toolchain
+URIs
 VSCode
 webroot
 Wildfly
+yjs
 Zooper

content/guides/_index.md

@@ -9,68 +9,40 @@ type: "docs"
 comments: false
 llmsTxtOptional: true
 ---
-## Frameworks
 
 {{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}}
-  Step by steps guides to deploy your favorite framework on Clever Cloud
+  Step by steps guides to deploy and use your favorite stack on Clever Cloud
 {{< /hextra/hero-subtitle >}}
-
 {{< cards >}}
-  {{< card link="python-django-sample" title="Django" subtitle= "Configure your Django application to run on Clever Cloud" icon="django" >}}
+  {{< card link="astro" title="Astro" subtitle= "Build and deploy a Astro application on Clever Cloud" icon="astro" >}}
+  {{< card link="clever-operator" title="Clever Operator" subtitle= "Manage your Clever Cloud databases and addons seamlessly from Kubernetes" icon="kubernetes" >}}
+  {{< card link="docs" title="Docs" subtitle= "Deploy the open source document and live collaboration editor on Clever Cloud" icon="docs-suite" >}}
+  {{< card link="docusaurus" title="Docusaurus" subtitle= "Build and deploy a static Docusaurus based website on Clever Cloud" icon="docusaurus" >}}
+  {{< card link="django" title="Django" subtitle= "Configure your Django application to run on Clever Cloud" icon="django" >}}
   {{< card link="tutorial-drupal" title="Drupal" subtitle= "Deploy a Drupal-based website on Clever Cloud" icon="drupal" >}}
+  {{< card link="eleventy" title="Eleventy (11ty)" subtitle= "Build and deploy a static Eleventy (11ty) based website on Clever Cloud" icon="11ty" >}}
   {{< card link="ekg-statsd-haskell-metrics/" title="ekg-statsd" subtitle= "How to configure ekg-statsd package in your Haskell application" icon="haskell" >}}
   {{< card link="fluentd/" title="Fluentd" subtitle= "How to deploy Fluentd using Docker on Clever Cloud" icon="fluentd" >}}
+  {{< card link="hexo" title="Hexo" subtitle= "Build and deploy a static Hexo based website on Clever Cloud" icon="hexo" >}}
+  {{< card link="hugo" title="Hugo" subtitle= "Build and deploy a static Hugo based website on Clever Cloud" icon="hugo" >}}
+  {{< card link="hugo-static-s3" title="Hugo + Cellar" subtitle= "Build and deploy a static Hugo based website and host it using Cellar" icon="hugo" >}}
+  {{< card link="kibana" title="Customize Kibana" subtitle= "Deploy and customize a Kibana server on Clever Cloud" icon="kibana" >}}
   {{< card link="tutorial-laravel" title="Laravel" subtitle= "Deploy a Laravel app on Clever Cloud" icon="laravel" >}}
+  {{< card link="lume-deno" title="Lume (Deno)" subtitle= "Build and deploy a static Lume (Deno) based website on Clever Cloud" icon="deno" >}}
+  {{< card link="mdbook" title="mdBook" subtitle= "Build and deploy a static mbBook based website on Clever Cloud" icon="mdbook" >}}
+  {{< card link="mkdocs" title="MkDocs" subtitle= "Build and deploy a static MkDocs based website on Clever Cloud" icon="docs" >}}
   {{< card link="moodle" title="Moodle" subtitle="Full Moodle installation and configuration guide" icon="moodle" >}}
+  {{< card link="node-js-mongo-db" title="Node.js + MongoDB starter" subtitle= "Starter tutorial to deploy a Node.js + MongoDB application on Clever Cloud" icon="node" >}}
   {{< card link="node-statsd-nodejs-metrics" title="node-statsd" subtitle= "Configure node-statsd package on your Node.js application to push custom metrics" icon="node" >}}
+  {{< card link="nuxt" title="Nuxt" subtitle= "Build and deploy a Nuxt application on Clever Cloud" icon="nuxt" >}}
+  {{< card link="pgpool" title="Pgpool-II" subtitle= "How to configure and use Pgpool-II for PostgreSQL add-ons" icon="pg" >}}
   {{< card link="play-framework-1" title="Play 1 x Scala" subtitle= "Set up your Play 1 + Scala application to run on Clever Cloud" icon="play" >}}
   {{< card link="play-framework-2" title="Play 2 x Scala" subtitle= "Set up your Play 2 + Scala application to run on Clever Cloud" icon="play" >}}
+  {{< card link="proxysql" title="ProxySQL" subtitle= "Configure and use ProxySQL for MySQL add-ons" icon="mysql" >}}
   {{< card link="ruby-on-rails" title="Ruby On Rails" subtitle= "How to deploy Ruby on Rails framework" icon="ruby" >}}
   {{< card link="ruby-rack" title="Ruby Rack" subtitle= "Set up a Ruby Rack application and deploy on Clever Cloud" icon="ruby" >}}
+  {{< card link="ruby-rack-app-tutorial" title="Ruby Rack" subtitle= "Write a hello world web application using Rack and deploy it on Clever Cloud" icon="ruby" >}}
   {{< card link="tutorial-symfony" title="Symfony" subtitle= "Deploy a Symfony application on Clever Cloud" icon="symfony" >}}
   {{< card link="tutorial-wordpress" title="WordPress" subtitle= "Deploy WordPress on Clever Cloud" icon="wordpress" >}}
 {{< /cards >}}
 
-## Static Site Generator (SSG)/ Server Side Rendering (SSR)
-
-<br>
-<div class="mb-12">
-{{< hextra/hero-subtitle >}}
-  Use Clever Cloud as a runner to build an efficient static website and host it in minutes.&nbsp;<br class="sm:block hidden" />
-{{< /hextra/hero-subtitle >}}
-</div>{{< cards >}}
-  {{< card link="astro" title="Astro" subtitle= "Build and deploy a Astro application on Clever Cloud" icon="astro" >}}
-  {{< card link="docusaurus" title="Docusaurus" subtitle= "Build and deploy a static Docusaurus based website on Clever Cloud" icon="docusaurus" >}}
-  {{< card link="eleventy" title="Eleventy (11ty)" subtitle= "Build and deploy a static Eleventy (11ty) based website on Clever Cloud" icon="11ty" >}}
-  {{< card link="hexo" title="Hexo" subtitle= "Build and deploy a static Hexo based website on Clever Cloud" icon="hexo" >}}
-  {{< card link="hugo" title="Hugo" subtitle= "Build and deploy a static Hugo based website on Clever Cloud" icon="hugo" >}}
-  {{< card link="hugo-static-s3" title="Hugo + Cellar" subtitle= "Build and deploy a static Hugo based website and host it using Cellar" icon="hugo" >}}
-  {{< card link="lume-deno" title="Lume (Deno)" subtitle= "Build and deploy a static Lume (Deno) based website on Clever Cloud" icon="deno" >}}
-  {{< card link="mdbook" title="mdBook" subtitle= "Build and deploy a static mbBook based website on Clever Cloud" icon="mdbook" >}}
-  {{< card link="mkdocs" title="MkDocs" subtitle= "Build and deploy a static MkDocs based website on Clever Cloud" icon="docs" >}}
-  {{< card link="nuxt" title="Nuxt" subtitle= "Build and deploy a Nuxt application on Clever Cloud" icon="nuxt" >}}
-{{< /cards >}}
-
-## Starter Tutorials
-
-{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}}
-  Tutorials to learn the basis of app configuration and deployments
-{{< /hextra/hero-subtitle >}}
-
-{{< cards >}}
- {{< card link="node-js-mongo-db" title="Node.js + MongoDB starter" subtitle= "Starter tutorial to deploy a Node.js + MongoDB application on Clever Cloud" icon="node" >}}
- {{< card link="ruby-rack-app-tutorial" title="Ruby Rack" subtitle= "Write a hello world web application using Rack and deploy it on Clever Cloud" icon="ruby" >}}
-{{< /cards >}}
-
-## Level Up your Add-ons
-
-{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}}
-  Take your dependencies to the next level
-{{< /hextra/hero-subtitle >}}
-
-{{< cards >}}
- {{< card link="kibana" title="Customize Kibana" subtitle= "Deploy and customize a Kibana server on Clever Cloud" icon="kibana" >}}
- {{< card link="kubernetes-operator" title="Kubernetes Operator" subtitle= "Manage your Clever Cloud databases and add-ons seamlessly from Kubernetes" icon="kubernetes" >}}
- {{< card link="pgpool" title="Pgpool-II" subtitle= "How to configure and use Pgpool-II for PostgreSQL add-ons" icon="pg" >}}
- {{< card link="proxysql" title="ProxySQL" subtitle= "Configure and use ProxySQL for MySQL add-ons" icon="mysql" >}}
-{{< /cards >}}

content/guides/docs.md

@@ -0,0 +1,290 @@
+---
+title: 'Docs'
+description: 
+tags:
+- guides
+keywords:
+- 
+
+draft: false
+type: docs
+---
+
+{{< hextra/hero-subtitle >}}
+  The open source document editor where your notes can become knowledge through live collaboration.
+{{< /hextra/hero-subtitle >}}
+
+## Docs architecture overview
+
+[Docs](https://github.com/suitenumerique/docs) runs on a Python backend and displays the application on a React/Next frontend. A [yjs provider](https://github.com/yjs/yjs) completes the stack to enable collaborative features.
+
+```mermaid
+flowchart TD
+ subgraph s1["Python"]
+        n6["Backend"]
+  end
+ subgraph s2["Node.JS"]
+        n7["Frontend"]
+  end
+ subgraph s3["Node.js"]
+        n8["yjs provider"]
+  end
+    n1["PostrgreSQL"] --> s1
+    s1 --> n1 & s2 & n2["Keycloak"] & n4["Cellar"] & s3
+    n2 --> s2 & s1
+    s3 --> s1
+    n4 --> s2
+    n1@{ shape: cyl}
+    n2@{ shape: hex}
+    n4@{ shape: rect}
+```
+
+## Deploy Docs
+
+Docs runs using:
+
+- a **Python** application for the backend (in `src/backend`)
+- a **Node.js** application for the frontend (in `src/frontend`)
+- a **Node.js** application for the y-provider (in `src/frontend/servers/y-provider`)
+
+This guide walks you trough a deployment from the root of [Docs repository](https://github.com/suitenumerique/docs). Clone the repository and follow the steps to deploy Docs with a minimal configuration.
+
+### Deploy the backend
+
+{{% steps %}}
+
+#### Create a Python application
+
+Select at least an `XS` plan. Smaller instances can make the build to fail.
+
+Inject the following environment variables
+
+```env
+APP_FOLDER="/src/backend"
+CC_PRE_BUILD_HOOK="cd src/backend && pip install pip-tools && pip-compile pyproject.toml &&
+pip-sync requirements.txt"
+CC_PYTHON_MODULE="impress.wsgi:application"
+CC_PYTHON_VERSION="3"
+CC_RUN_SUCCEEDED_HOOK="cd src/backend && python manage.py migrate"
+DATA_DIR="home/bas/<app_id>/src/backend/data"
+DJANGO_CONFIGURATION="Production"
+DJANGO_SECRET_KEY="<your-key>"
+DJANGO_SETTINGS_MODULE="impress.settings"
+DJANGO_SUPERUSER_PASSWORD="<your-password>"
+```
+
+#### Create a PosgreSQL add-on
+
+Inject the DB credentials into the Python application:
+
+```env
+DB_HOST="<postrgresql_addon_host_value>"
+DB_NAME="<postrgresql_addon_name_value>"
+DB_PASSWORD="<postrgresql_addon_password_value>"
+DB_PORT="<postrgresql_addon_port_value>"
+DB_USER="<postrgresql_addon_user_value>"
+```
+
+#### Set the backend domain name
+
+Select **Domain names** and add use the path routing feature on Clever Cloud to set the domain ans follows:
+
+- Domain name: `<docs-base-domain>`
+- Route: `/api/v1.0/`
+
+**⚠️ Don't skip the trailing slash at the end of the route.**
+
+You can use `.cleverapps.io` domains for tests. Make sure to set a custom domain before releasing for production.
+
+Then, inject the following environment variables:
+
+```env
+DJANGO_ALLOWED_HOSTS="<docs-base-domain>"
+DJANGO_CSRF_TRUSTED_ORIGINS="https://<docs-base-domain>"
+IMPRESS_BASE_URL="https://<docs-base-domain>"
+LOGIN_REDIRECT_URL="https://<docs-base-domain>"
+LOGOUT_REDIRECT_URL="https://<docs-base-domain>/*"
+```
+
+#### Push your code
+
+If you push using git, add the remote as `clever-backend`, for example.
+
+{{% /steps %}}
+
+### Deploy the frontend
+
+{{% steps %}}
+
+#### Create a Node.js application
+
+Select at least a `M` instance for the build, and inject the following environment variables:
+
+```env
+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"
+NEXT_PUBLIC_API_BASE_PATH="/"
+NEXT_PUBLIC_SW_DEACTIVATED="true"
+NODE_OPTIONS="--max-old-space-size=4096"
+```
+
+#### Set the frontend domain name
+
+- Select **Domain names** and set the base domain for Docs. The frontend doesn't need any route.
+- Add the domain to the environment variables: inject `NEXT_PUBLIC_API_ORIGIN="https://<docs-base-domain>"` to the list of the frontend environment variables.
+
+#### Push your code
+
+If you push using git, add the remote as `clever-frontend`, for example.
+
+{{% /steps %}}
+
+### Deploy the y-provider
+
+{{% steps %}}
+
+#### Create a Node.js application
+
+Inject the following environment variables:
+
+```env
+APP_FOLDER="/src/frontend/servers/y-provider"
+CC_NODE_BUILD_TOOL="yarn"
+CC_PRE_BUILD_HOOK="cd ./src/frontend/servers/y-provider && yarn install --frozen-lockfile && yarn build"
+CC_RUN_COMMAND="cd ./src/frontend/servers/y-provider && yarn start"
+COLLABORATION_LOGGING="true"
+COLLABORATION_SERVER_ORIGIN="https://<docs-base-domain>"
+COLLABORATION_SERVER_SECRET="<server-secret>"
+Y_PROVIDER_API_KEY="<generated-api-key>"
+```
+
+#### Set y-provider domain
+
+Select **Domain names** and add the following domains:
+
+- Domain: `<docs-base-domain>`
+- Route: `/collaboration/api/`
+
+- Domain: `<docs-base-domain>`
+- Route: `/ws/`
+
+#### Connect to the backend
+
+Select **Exposed configuration** and inject the following environment variables:
+
+```env
+COLLABORATION_API_URL="https://<docs-base-domain>/collaboration/api/"
+COLLABORATION_SERVER_SECRET="<server-secret>"
+```
+
+Then select the **backend** application > **Service dependencies** > **Link applications** and choose the y-provider application.
+
+#### Push your code
+
+If you push using git, add the remote as `clever-y-provider`, for example.
+
+{{% /steps %}}
+
+## How to configure Docs
+
+Docs depends on some services that needs configuration before it can function. Use the **Create > an add-on** function to create each dependency on Clever Cloud.
+
+### Keycloak
+
+Docs uses Keycloak as an authentication provider. Configure it by following these steps:
+
+{{% steps %}}
+
+#### Create a Keycloak add-on
+
+If you don't have a Keycloak instance, create one on Clever Cloud. If you already have one, skip this step. For the sake of demonstration, this guide follows [the example values provided by Docs](https://github.com/suitenumerique/docs/blob/main/docs/examples/impress.values.yaml). You can rename them as you see fit.
+
+#### Create a new realm
+
+Name it `impress`.
+
+#### Create a new client
+
+Name it `impress` as well.
+
+#### Client settings
+
+##### General settings
+
+- Client ID: impress
+- Client name: impress
+- Always Display in UI: ON
+
+##### Access settings
+
+- Root URL: `https://<docs-base-domain>`
+- Home URL: `https://<docs-base-domain>`
+- Valid redirect URIs: `https://<docs-base-domain>/api/v1.0/callback/*`
+- Valid post logout redirect URIs: `https://<docs-base-domain>/*`
+- Web origins: `https://<docs-base-domain>`
+
+##### Capability config
+
+- Client authentication: On
+- Authorization: Off
+- Authentication flow: Standard flow
+
+##### Find the Client Secret
+
+Find it in **Clients > impress > credentials**, named **Client secret*.
+
+##### Optional : Add an identity provider
+
+You can choose among different identity providers (GitHub, Google, etc, and even Clever Cloud).
+
+#### Inject the variables in the **backend** application
+
+```env
+OIDC_OP_AUTHORIZATION_ENDPOINT="https://<cc_keycloak_hostname_value>/realms/impress/protocol/openid-connect/auth"
+OIDC_OP_JWKS_ENDPOINT="https://<cc_keycloak_hostname_value>/realms/impress/protocol/openid-connect/certs"
+OIDC_OP_LOGOUT_ENDPOINT="https://<cc_keycloak_hostname_value>/realms/impress/protocol/openid-connect/session/end"
+OIDC_OP_TOKEN_ENDPOINT="https://<cc_keycloak_hostname_value>/realms/impress/protocol/openid-connect/token"
+OIDC_OP_USER_ENDPOINT="https://<cc_keycloak_hostname_value>/realms/impress/protocol/openid-connect/userinfo"
+OIDC_RP_CLIENT_ID="impress"
+OIDC_RP_CLIENT_SECRET="<client-secret>"
+OIDC_RP_SCOPES="openid email"
+OIDC_RP_SIGN_ALGO="RS256"
+```
+
+{{% /steps %}}
+
+### Redis
+
+Create a Redis add-on, but don't connect it to the application, since Docs requires an URI format that differs from the one provided by Clever Cloud. Instead, inject the variable in the **backend** application, using this format: `REDIS_URL="redis://default:<redis_password>:<redis_host>:<redis_port>"`
+
+### Cellar
+
+Docs uses s3 compatible storage to store uploaded files by users.
+
+{{% steps %}}
+
+#### Create a Cellar add-on
+
+#### Create a bucket
+
+#### Inject the variables in the **backend** application
+
+```env
+AWS_S3_ACCESS_KEY_ID="<cellar-addon_key_id_value>"
+AWS_S3_ENDPOINT_URL="<cellar-addon_host_value>"
+AWS_S3_REGION_NAME="auto"
+AWS_S3_SECRET_ACCESS_KEY="<cellar-addon_key_secret_value>"
+AWS_STORAGE_BUCKET_NAME="<name-of-your-bucket>"
+AWS_REQUEST_CHECKSUM_CALCULATION="when_required"
+AWS_RESPONSE_CHECKSUM_VALIDATION="when_required"
+```
+
+{{% /steps %}}
+
+## 🎓 Further Help
+
+{{< cards >}}
+  {{< card link="https://github.com/suitenumerique/docs/blob/main/docs/installation.md#preparation" title="Docs documentation" subtitle="Installation instructions" icon="adjustments-horizontal" >}}
+{{< /cards >}}