ICHEC Django Core
ichec-django-core is the base for ICHEC's Django web apps. It gives your app
secure default settings, member and organisation models, sign-in through
Keycloak, and a REST API for all of these. You write the parts that are specific
to your app.
The reference app
is a complete app built on it, deployed with the ichec.platform Ansible
collection.
Try the example app
The app directory is a minimal portal built on the library. Run it
locally to see what you get before you write any code. You need
uv (brew install uv).
git clone https://git.ichec.ie/platform-engineering/modules/web/ichec-django-core.git
cd ichec-django-core
uv run tox exec -e dev -- python manage.py migrate
uv run tox exec -e dev -- python manage.py createsuperuser
uv run tox -e dev
Sign in at http://localhost:8000/accounts/login/ as the admin you created,
then open http://localhost:8000/api/ to browse the API. The dev env in
pyproject.toml holds the development settings.
Use it in your app
This guide assumes you can build a basic Django app. If not, work through the Django tutorial first.
Add the library to your dependencies:
uv add ichec-django-core
Settings
Import the library's settings, then set the few values that depend on your project layout. Your settings file then looks like app/settings.py:
from pathlib import Path
from ichec_django_core import settings
from ichec_django_core.settings import *
BASE_DIR = Path(__file__).resolve().parent.parent
ROOT_URLCONF = "app.urls"
WSGI_APPLICATION = "app.wsgi.application"
ASGI_APPLICATION = "app.asgi.application"
TEMPLATES = settings.get_templates(BASE_DIR)
DATABASES = settings.get_databases(BASE_DIR)
STATIC_ROOT = settings.get_static_root(BASE_DIR)
MEDIA_ROOT = settings.get_media_root(BASE_DIR)
Override any other setting below the import.
The library reads its settings from environment variables. Django won't start
without DJANGO_SECRET_KEY and DJANGO_ALLOWED_HOSTS, or without
DJANGO_SQL_PASSWORD when it uses a database server rather than SQLite.
For local work, set them in a tox env, as the dev env in
pyproject.toml does. In production, the deployment passes
them to the container.
settings.py lists every variable and its
default.
URLs
Register the library's API views on your own router, and include its other views, as in app/urls.py:
from django.urls import include, path
from rest_framework import routers
from ichec_django_core.urls import register_drf_views
router = routers.DefaultRouter()
register_drf_views(router)
urlpatterns = [
path("api/", include(router.urls)),
path("", include("ichec_django_core.urls")),
]
Register your app's own viewsets on the same router, so the whole API sits under
one /api/ root.
Set the error handlers too, so errors on /api/ paths come back as JSON, as the
schema documents:
handler404 = "ichec_django_core.views.errors.not_found"
handler500 = "ichec_django_core.views.errors.server_error"
Sign in with Keycloak
The example app uses Django's own login, which lets anyone register. Real deployments sign users in through Keycloak with OpenID Connect (OIDC).
Register your app as a client in the Keycloak realm, then set:
WITH_OIDC=1
OIDC_RP_CLIENT_ID=my-app
OIDC_RP_CLIENT_SECRET=...
OIDC_OP_AUTHORIZATION_ENDPOINT=https://keycloak.example.org/realms/my-realm/protocol/openid-connect/auth
OIDC_OP_TOKEN_ENDPOINT=https://keycloak.example.org/realms/my-realm/protocol/openid-connect/token
OIDC_OP_USER_ENDPOINT=https://keycloak.example.org/realms/my-realm/protocol/openid-connect/userinfo
OIDC_OP_JWKS_ENDPOINT=https://keycloak.example.org/realms/my-realm/protocol/openid-connect/certs
OIDC_OP_LOGOUT_ENDPOINT=https://keycloak.example.org/realms/my-realm/protocol/openid-connect/logout
Leave DJANGO_WITH_USER_LOGIN unset in production.
To sign in through a Keycloak on your machine, with a Test realm on port 8080,
run uv run tox -e dev-oidc.
mozilla-django-oidc
does the OIDC work, and its docs explain each setting.
Optional features
Each of these is off until you turn it on.
- Background tasks. Emails and Keycloak syncs run inline by default. To run them
on a Celery worker, install the
asyncextra and setDJANGO_TASK_BACKEND=celery,CELERY_BROKER_URLandCELERY_RESULT_BACKEND. Then callcreate_celery_app()in your app'scelery.py, as in app/celery.py, and runcelery -A your_app worker. To run your own functions the same way, decorate them with@background_task("your_app.task_name")fromichec_django_core.tasks. - File storage. Uploaded files are served by Django by default. Set
DJANGO_DOWNLOAD_DELIVERYtoxaccelto have nginx serve them, or tos3to keep them in object storage. The comments in settings.py explain each mode. - Keycloak attributes. The app can copy values such as a member's role or
avatar onto their Keycloak user, so other apps in the realm can read them.
Set
KEYCLOAK_ATTRIBUTE_SYNC_ENABLED=1, install thekeycloakextra, and list the attributes inKEYCLOAK_ATTRIBUTE_SYNC. See sso/__init__.py.
Test your app
ichec_django_core.test has helpers for your app's tests:
AuthAPITestCasecalls your API as each test user.AuthorizationSweepTestCasecalls every endpoint in your schema as each role, and checks the result against a file listing who may call what. The reference app shows it in use.- The checks in
test/privacy.pyprove that erasing a member removes all their personal data, including from your app's models.
Work on this library
Install the development tools and run the checks that CI runs:
uv sync --group dev --extra async
uv run pytest
uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy src
uv run python runtests.py also runs the end-to-end tests in tests/e2e. If you
use direnv, run direnv allow once and the environment
activates when you enter the directory.
If you change a model or serializer, regenerate the API schema and commit it:
uv run python manage.py spectacular --file schema.yaml --validate
Licence
Copyright of the Irish Centre for High End Computing (ICHEC), released under the MIT License. See LICENSE.
1 maintainer
Release files for ichec-django-core 4.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ichec_django_core-4.0.0.tar.gz | 190.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ichec_django_core-4.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 362.8 kB
Release files / ichec_django_core-4.0.0.tar.gz
| Download URL | ichec_django_core-4.0.0.tar.gz |
|---|---|
| Size | 190.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a159b9651d5149d13597fed39d29fe7363b4119c4fc0936c0a281f8458a30bab
|
|
BLAKE2b-256 checksum How to use checksums |
3932199485c66f2b75f5aa41f39afc22eadcdfe68efad282eaf616610cbe0ade
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / ichec_django_core-4.0.0-py3-none-any.whl
| Download URL | ichec_django_core-4.0.0-py3-none-any.whl |
|---|---|
| Size | 172.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d62ad0c2ede478b7a37527cc5e4a2c81f889126d0fa6ee99e8db5d2cec0fe280
|
|
BLAKE2b-256 checksum How to use checksums |
b811f4e6e5f9c6756e79637dda5eba786f1e4275656bdc02480ef7ba1dc2747b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
