mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
This commit is contained in:
Florian Forster
co-authored by
Federico Coppede
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: ZITADEL with Django Python
|
||||
sidebar_label: Django
|
||||
---
|
||||
|
||||
import AppJWT from '../imports/_app_jwt.mdx';
|
||||
import ServiceuserJWT from '../imports/_serviceuser_jwt.mdx';
|
||||
import ServiceuserRole from '../imports/_serviceuser_role.mdx';
|
||||
import SetupPython from '../imports/_setup_python.mdx';
|
||||
|
||||
This integration guide demonstrates the recommended way to incorporate ZITADEL into your Django Python application.
|
||||
It explains how to check the token validity in the API and how to check for permissions.
|
||||
|
||||
By the end of this guide, your application will have three different endpoint which are public, private(valid token) and private-scoped(valid token with specific role).
|
||||
|
||||
<Callout>
|
||||
This documentation references our [example](https://github.com/zitadel/example-django-python-oauth) on GitHub.
|
||||
</Callout>
|
||||
|
||||
## ZITADEL setup
|
||||
|
||||
Before we can start building our application, we have to do a few configuration steps in ZITADEL Management Console.
|
||||
|
||||
### Create application
|
||||
|
||||
<AppJWT components={props.components} />
|
||||
|
||||
### Create Serviceuser
|
||||
|
||||
<ServiceuserJWT components={props.components} />
|
||||
|
||||
### Give Serviceuser an authorization
|
||||
|
||||
<ServiceuserRole components={props.components} />
|
||||
|
||||
### Prerequisites
|
||||
|
||||
At the end you should have the following for the API:
|
||||
- Issuer, something like `https://example.zitadel.cloud` or `http://localhost:8080`
|
||||
- Introspection URL, something like `https://example.zitadel.cloud/oauth/v2/introspect`
|
||||
- Token URL, something like `https://example.zitadel.cloud/oauth/v2/token`
|
||||
- `.json`-key-file for the API, from the application
|
||||
- ID of the project
|
||||
|
||||
And the following from the Serviceuser:
|
||||
- `.json`-key-file from the serviceuser
|
||||
|
||||
## Setup new Django application
|
||||
|
||||
### Setup Python
|
||||
|
||||
<SetupPython components={props.components} />
|
||||
|
||||
### Install dependencies
|
||||
|
||||
For this example we need the following dependencies:
|
||||
- `django`: to create an API with django
|
||||
- `python-dotenv`: to use environment variables in the configuration
|
||||
- `authlib`: client-side OAuth functionality
|
||||
- `requests`: HTTP requests for the introspection
|
||||
|
||||
For the dependencies we need a requirements.txt-file with the following content:
|
||||
|
||||
```python reference
|
||||
https://github.com/zitadel/example-python-django-oauth/blob/main/requirements.txt
|
||||
```
|
||||
|
||||
Then install all dependencies with:
|
||||
```bash
|
||||
python -m pip install -U requirements.txt
|
||||
```
|
||||
|
||||
Then in your folder of choice, call the following command to create a Django base:
|
||||
```bash
|
||||
django-admin startproject myapi .
|
||||
```
|
||||
|
||||
## Define the Django API
|
||||
|
||||
### Add to the settings.py to include ZITADEL info
|
||||
|
||||
There is info needed for the introspection calls, which we put into the settings.py:
|
||||
|
||||
```python reference
|
||||
https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/settings.py#L125-L133
|
||||
```
|
||||
|
||||
and create a ".env"-file in the root folder with the configuration as an example:
|
||||
```bash
|
||||
ZITADEL_INTROSPECTION_URL = 'URL to the introspection endpoint to verify the provided token'
|
||||
ZITADEL_DOMAIN = 'Domain used as audience in the token verification'
|
||||
API_PRIVATE_KEY_FILE_PATH = 'Path to the key.json created in ZITADEL'
|
||||
```
|
||||
|
||||
I should look something like this:
|
||||
|
||||
```bash
|
||||
ZITADEL_INTROSPECTION_URL = 'https://example.zitadel.cloud/oauth/v2/introspect'
|
||||
ZITADEL_DOMAIN = 'https://example.zitadel.cloud'
|
||||
API_PRIVATE_KEY_FILE_PATH = '/tmp/example/250719519163548112.json'
|
||||
```
|
||||
|
||||
### Validator definition
|
||||
|
||||
To validate the tokens, we need a validator which can be called in the event of API-calls.
|
||||
|
||||
validator.py:
|
||||
|
||||
```python reference
|
||||
https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/validator.py
|
||||
```
|
||||
|
||||
### Requests and URLs
|
||||
|
||||
We define 3 different endpoints which differ in terms of requirements.
|
||||
views.py:
|
||||
|
||||
```python reference
|
||||
https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/views.py
|
||||
```
|
||||
|
||||
To handle endpoints the urls have to be added to the urls.py:
|
||||
|
||||
```python reference
|
||||
https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/urls.py
|
||||
```
|
||||
|
||||
### DB
|
||||
|
||||
Create and run migrations:
|
||||
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
### Run
|
||||
|
||||
You can use a local Django server to test the application.
|
||||
|
||||
```bash
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
### Call the API
|
||||
|
||||
To call the API you need an access token, which is then verified by ZITADEL.
|
||||
Please follow [this guide here](/guides/integrate/token-introspection/private-key-jwt), ignoring the first step as we already have the `.json`-key-file from the serviceaccount.
|
||||
|
||||
Optionally set the token as an environment variable:
|
||||
```
|
||||
export TOKEN='MtjHodGy4zxKylDOhg6kW90WeEQs2q...'
|
||||
```
|
||||
|
||||
With the access token, you can then do the following calls:
|
||||
```
|
||||
curl -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/public
|
||||
curl -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/private
|
||||
curl -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/private-scoped
|
||||
```
|
||||
|
||||
## Completion
|
||||
|
||||
Congratulations! You have successfully integrated your Django API with ZITADEL!
|
||||
|
||||
If you get stuck, consider checking out our [example](https://github.com/zitadel/example-python-django-oauth) application. This application includes all the functionalities mentioned in this quick-start. You can start by cloning the repository and defining the settings in the settings.py. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/example-python-django-oauth/issues).
|
||||
Reference in New Issue
Block a user