django_yunohost_integration

Python package django_yunohost_integration with helpers for integrate a Django project as YunoHost package.

A example usage of this package is here:

• https://github.com/YunoHost-Apps/django_example_ynh

Pull requests welcome ;)

These projects used django_yunohost_integration:

• https://github.com/YunoHost-Apps/pyinventory_ynh
• https://github.com/YunoHost-Apps/django-for-runners_ynh
• https://github.com/YunoHost-Apps/django-fmd_ynh

Features

• SSOwat integration (see below)
• Helper to create first super user for scripts/install
• Run Django development server with a local generated YunoHost package installation (called local_test)
• Helper to run test against local_test "installation"

SSO authentication

SSOwat is fully supported:

• First user ($YNH_APP_ARG_ADMIN) will be created as Django's super user
• All new users will be created as normal users
• Login via SSO is fully supported
• User Email, First / Last name will be updated from SSO data

usage

To create/update the first user in install/upgrade, e.g.:

./manage.py create_superuser --username="$admin" --email="$admin_mail"

This Create/update Django superuser and set a unusable password. A password is not needed, because auth done via SSOwat ;)

Main parts in settings.py:

from pathlib import Path as __Path

from django_yunohost_integration.base_settings import *  # noqa
from django_yunohost_integration.secret_key import get_or_create_secret as __get_or_create_secret


DEBUG = bool(int('__DEBUG_ENABLED__'))  # Set via config_panel.toml

# -----------------------------------------------------------------------------

DATA_DIR_PATH = __Path('__DATA_DIR__')  # /home/yunohost.app/$app
assert DATA_DIR_PATH.is_dir(), f'Directory not exists: {DATA_DIR_PATH}'

INSTALL_DIR_PATH = __Path('__INSTALL_DIR__')  # /var/www/$app
assert INSTALL_DIR_PATH.is_dir(), f'Directory not exists: {INSTALL_DIR_PATH}'

LOG_FILE = __Path('__LOG_FILE__')  # /var/log/$app/$app.log
assert LOG_FILE.is_file(), f'File not exists: {LOG_FILE}'

PATH_URL = '__PATH_URL__'  # $YNH_APP_ARG_PATH
PATH_URL = PATH_URL.strip('/')

# -----------------------------------------------------------------------------

# Function that will be called to finalize a user profile:
YNH_SETUP_USER = 'setup_user.setup_project_user'

SECRET_KEY = __get_or_create_secret(DATA_DIR_PATH / 'secret.txt')  # /home/yunohost.app/$app/secret.txt

# INSTALLED_APPS.append('<insert-your-app-here>')

# -----------------------------------------------------------------------------

At least you have to set these settings:

from django_yunohost_integration.base_settings import *  # noqa

INSTALLED_APPS.append('django_yunohost_integration')

MIDDLEWARE.insert(
    MIDDLEWARE.index('django.contrib.auth.middleware.AuthenticationMiddleware') + 1,
    # login a user via HTTP_REMOTE_USER header from SSOwat:
    'django_yunohost_integration.sso_auth.auth_middleware.SSOwatRemoteUserMiddleware',
)

# Keep ModelBackend around for per-user permissions and superuser
AUTHENTICATION_BACKENDS = (
    'axes.backends.AxesBackend',  # AxesBackend should be the first backend!
    #
    # Authenticate via SSO and nginx 'HTTP_REMOTE_USER' header:
    'django_yunohost_integration.sso_auth.auth_backend.SSOwatUserBackend',
    #
    # Fallback to normal Django model backend:
    'django.contrib.auth.backends.ModelBackend',
)

LOGIN_REDIRECT_URL = None
LOGIN_URL = '/yunohost/sso/'
LOGOUT_REDIRECT_URL = '/yunohost/sso/'
# /yunohost/sso/?action=logout

ROOT_URLCONF = 'urls'  # .../conf/urls.py

local test

Build prerequisites

We install psycopg2 (a PostgreSQL adapter for the Python) that needs some build prerequisites, e.g.:

~$ sudo apt install build-essential python3-dev libpq-dev

For quicker developing of django_yunohost_integration in the context of YunoHost app, it's possible to run the Django developer server with the settings and urls made for YunoHost installation.

e.g.:

~$ git clone https://github.com/YunoHost-Apps/django_yunohost_integration.git
~$ cd django_yunohost_integration/
~/django_yunohost_integration$ ./dev-cli.py

For quicker developing of django_yunohost_integration in the context of YunoHost app, it's possible to run the Django developer server with the settings and urls made for YunoHost installation.

e.g.:

~/django_yunohost_integration$ ./dev-cli.py local-test

• SQlite database will be used
• A super user with username test and password test is created
• The page is available under http://127.0.0.1:8000/app_path/

dev-cli.py usage

usage: ./dev-cli.py [-h] {coverage,install,lint,local-test,mypy,nox,pip-audit,publish,test,update,update-readme-history,update-test-snapshot-files,version}



╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help    show this help message and exit                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                             │
│   • coverage  Run tests and show coverage report.                                      │
│   • install   Install requirements and 'django_yunohost_integration' via pip as        │
│               editable.                                                                │
│   • lint      Check/fix code style by run: "ruff check --fix"                          │
│   • local-test                                                                         │
│               Build a "local_test" YunoHost installation and start the Django dev.     │
│               server against it.                                                       │
│   • mypy      Run Mypy (configured in pyproject.toml)                                  │
│   • nox       Run nox                                                                  │
│   • pip-audit                                                                          │
│               Run pip-audit check against current requirements files                   │
│   • publish   Build and upload this project to PyPi                                    │
│   • test      Run unittests                                                            │
│   • update    Update dependencies (uv.lock) and git pre-commit hooks                   │
│   • update-readme-history                                                              │
│               Update project history base on git commits/tags in README.md             │
│                                                                                        │
│               Will be exited with 1 if the README.md was updated otherwise with 0.     │
│                                                                                        │
│               Also, callable via e.g.:                                                 │
│                   python -m cli_base update-readme-history -v                          │
│   • update-test-snapshot-files                                                         │
│               Update all test snapshot files (by remove and recreate all snapshot      │
│               files)                                                                   │
│   • version   Print version and exit                                                   │
╰────────────────────────────────────────────────────────────────────────────────────────╯

Backwards-incompatible changes

v0.9

Starting with v0.9 we only support YunoHost >= v12.

For this the auth_middleware was changed:

• HTTP_REMOTE_USER changed HTTP_YNH_USER
• HTTP_AUTH_USER was removed
• SSOwAuthUser changed to JWT token yunohost.portal

The YunoHost package nginx config should be set:

proxy_set_header Ynh-User $http_ynh_user;

history

• v0.11.0
  • 2026-08-08 - Add Cobertura XML coverage reporting and GitHub upload-code-coverage integration
  • 2026-08-08 - fix flaky test
  • 2026-08-08 - Expand github CI matrix
  • 2026-08-08 - fix code style and tests
  • 2026-08-08 - Modernize
  • 2026-08-08 - Apply mamageprojects updates
• v0.10.9
  • 2025-12-05 - Replace DEBUG_ENABLED default "YES" to "1"
  • 2025-12-05 - Update requirements
• v0.10.8
  • 2025-10-31 - Bugfix redirect of Ynh app is installed on domain root next=/
• v0.10.7
  • 2025-10-31 - Bugfix SSO login redirection: Don't change the domain

Links

• Report a bug about this package: https://github.com/YunoHost-Apps/django_yunohost_integration
• YunoHost website: https://yunohost.org/
• PyPi package: https://pypi.org/project/django_yunohost_integration/