Déploiement¶

Cette page détaille ce qu’il faut installer sur votre serveur pour créer un environnement prêt pour la production de Canaille.

Serveur d’application¶

Après avoir fini l”installation de Canaille, vous devez l’exécuter dans un serveur d’application WSGI. Il existe de nombreux serveurs d’applications que vous pouvez utiliser avec Canaille, comme Gunicorn, uWSGI, uvicorn ou Hypercorn par exemple.

Cannaille fournit une intégration légère d’Hypercorn, mais vous pouvez utiliser n’importe quel serveur d’application. Le point d’entrée WSGI à configurer dans votre serveur est canaille:create_app.

Intégration Hypercorn¶

Pour exécuter le serveur d’application intégré Hypercorn, vous pouvez simplement exécuter la commande canaille run. Une intégration d’Hypercorn est disponible dans l’exécutable de Canaille. Cependant si vous installez Canaille par les paquets Python, vous devez installer l’extra [server]``(par exemple avec ``pip install canaile[server]) pour qu’Hypercorn soit disponible.

Exécution de la commande run¶

$ canaille run
[2025-01-02 16:39:18 +0100] [304043] [INFO] Running on http://0.0.0.0:8000 (CTRL + C to quit)
[2025-01-02 16:39:18,412] INFO in logging: Running on http://0.0.0.0:8000 (CTRL + C to quit)

By default it runs on the port 8000 of localhost, this could be enough but you might want to customize it a little bit more. Fortunately Hypercorn provides a configuration documentation to adjust it to your needs. You can tweak Hypercorn in the main Canaille configuration file, at the CANAILLE_HYPERCORN namespace, or by passing CLI parameters.

Running the Canaille run command with parameters¶

$ canaille run --bind 0.0.0.0:1234 --workers 4

Proxy configuration¶

When running Canaille behind a reverse proxy like Nginx or Caddy, you should configure the setting to properly handle forwarded headers. With the CANAILLE_HYPERCORN__PROXY_MODE env var, or with the PROXY_MODE configuration setting in the [CANAILLE_HYPERCORN] namespace, set the value to legacy for traditional X-Forwarded-* headers (the most common), or modern for RFC 7239 Forwarded headers. You can also adjust PROXY_MODE to match the number of trusted proxies between the client and your application (defaults to 1).

Serveur web¶

Maintenant vous devez brancher votre serveur d’application WSGI à votre serveur web pour qu’il soit accessible sur internet. Voici quelques exemples de configuration de serveur web que vous pouvez utiliser :

Nginx¶

Exemple de configuration Nginx pour Canaille¶

server {
    listen 80;
    listen [::]:80;
    server_name auth.mydomain.example;
    return 301 https://$server_name$request_uri;
}

server {
    server_name auth.mydomain.example;

    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    ssl_certificate /etc/letsencrypt/live/auth.mydomain.example/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.mydomain.example/privkey.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
    ssl_session_tickets off;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_stapling on;
    ssl_stapling_verify on;

    index index.html index.php;
    charset utf-8;
    client_max_body_size 10M;

    access_log /opt/canaille/logs/nginx.access.log;
    error_log /opt/canaille/logs/nginx.error.log;

    gzip on;
    gzip_vary on;
    gzip_comp_level 4;
    gzip_min_length 256;
    gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
    gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-Frame-Options                      "SAMEORIGIN"    always;
    add_header X-Content-Type-Options               "nosniff"       always;
    add_header Referrer-Policy                      "same-origin"   always;

    location /static {
        root /opt/canaille/src/canaille;

        location ~* ^.+\.(?:css|cur|js|jpe?g|gif|htc|ico|png|html|xml|otf|ttf|eot|woff|woff2|svg)$ {
            access_log off;
            expires 30d;
            more_set_headers Cache-Control public;
        }
    }

    location / {
        proxy_pass http://unix:/run/canaille.sock;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Apache¶

Exemple de configuration Apache pour Canaille¶

<VirtualHost *:80>
    ServerName auth.mydomain.example
    ServerAdmin admin@mydomain.example

    CustomLog /opt/canaille/logs/apache-http-access.log combined
    ErrorLog /opt/canaille/logs/apache-http-error.log

    RewriteEngine On
    RewriteCond %{REQUEST_URI} !^/\.well\-known/acme\-challenge/
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]    </VirtualHost>
</VirtualHost>

<VirtualHost *:443>
    ServerName auth.mydomain.example
    ServerAdmin admin@mydomain.example
    Protocols h2 http/1.1

    CustomLog /opt/canaille/logs/apache-https-access.log combined
    ErrorLog /opt/canaille/logs/apache-https-error.log

    SSLEngine On
    SSLCertificateFile      /etc/letsencrypt/live/auth.mydomain.example/fullchain.pem
    SSLCertificateKeyFile   /etc/letsencrypt/live/auth.mydomain.example/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

    ProxyPreserveHost On
    ProxyPass /static/ !
    ProxyPass / unix:/run/canaille.sock
    ProxyPassReverse / unix:/run/canaille.sock

    RequestHeader set X-FORWARDED-PROTOCOL ssl
    RequestHeader set X-FORWARDED-SSL on
</VirtualHost>

Tâches récurrentes¶

Vous pourriez vouloir nettoyer la base de données pour limiter sa croissance. Vous pouvez supprimer régulièrement les jetons expirés et les code d’autorisation avec :

$ env CANAILLE_CONFIG="$CANAILLE_CONF_DIR/config.toml" FLASK_APP=canaille "$CANAILLE_INSTALL_DIR/env/bin/canaille" clean

Webfinger¶

Vous pourriez vouloir configurer un terminal WebFinger sur votre site web principal pour permettre la découverte automatique de votre installation Canaille basée sur le nom de compte d’un de vos utilisateurs. Par exemple, supposons que votre domaine soit mondomain.schmilblick et que votre domaine Canaille soit auth.mondomain.schmilblick et qu’il existe un utilisateur jean.dupont. Une application tierce pourrait avoir besoin d’authentifier l’utilisateur et lui demander son compte. L’utilisateur fournirait son compte jean.dupont@mondomain.schmilblick, alors l’application exécuterait une requête WebFinger sur https://mondomain.schmilblick/.well-known/webfinger et la réponse contiendrait l’adresse du serveur d’authentification https://auth.mondomain.schmilblick. Avec cette information, l’application tierce pourrait rediriger l’utilisateur vers la page d’authentification Canaille.

La difficulté est que le terminal WebFinger doit être hébergé sur le domaine de plus haut niveau (c’est-à-dire mydomain.example) alors que le serveur d’authentification peut être hébergé sur un sous-niveau(par exemple auth.mydomain.example). Canaille fournit un terminal WebFinger, mais il n’est pas hébergé sur le domaine de plus haut niveau, une redirection est obligatoire sur le chemin /.well-known/webfinger.

Voici des exemples de configuration pour Nginx ou Apache :

Configuration webfinger Nginx pour le domaine de plus haut niveau¶

 server {
     listen 443;
     server_name mydomain.example;
     rewrite  ^/.well-known/webfinger https://auth.mydomain.example/.well-known/webfinger permanent;
 }

Configuration webfinger Apache pour le domaine de plus haut niveau¶

 <VirtualHost *:443>
     ServerName mydomain.example
     RewriteEngine on
     RewriteRule "^/.well-known/webfinger" "https://auth.mydomain.example/.well-known/webfinger" [R,L]
 </VirtualHost>