ackify/docs/fr/configuration.md

Configuration

Guide complet de configuration d'Ackify via variables d'environnement.

Variables Obligatoires

Ces variables sont requises pour démarrer Ackify :

# URL publique de votre instance (utilisée pour OAuth callbacks)
APP_DNS=sign.your-domain.com
ACKIFY_BASE_URL=https://sign.your-domain.com

# Nom de votre organisation (affiché dans l'interface)
ACKIFY_ORGANISATION="Your Organization Name"

# Configuration PostgreSQL
POSTGRES_USER=ackifyr
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=ackify

# OAuth2 Provider
ACKIFY_OAUTH_PROVIDER=google  # ou github, gitlab, ou vide pour custom
ACKIFY_OAUTH_CLIENT_ID=your_oauth_client_id
ACKIFY_OAUTH_CLIENT_SECRET=your_oauth_client_secret

# Secret pour chiffrer les cookies de session (générer avec: openssl rand -base64 32)
ACKIFY_OAUTH_COOKIE_SECRET=your_base64_encoded_secret_key

Variables Optionnelles

Serveur

# Adresse d'écoute HTTP (défaut: :8080)
ACKIFY_LISTEN_ADDR=:8080

# Niveau de logs: debug, info, warn, error (défaut: info)
ACKIFY_LOG_LEVEL=info

Sécurité & OAuth2

# Restreindre l'accès à un domaine email spécifique
ACKIFY_OAUTH_ALLOWED_DOMAIN=@company.com

# Activer l'auto-login silencieux (défaut: false)
ACKIFY_OAUTH_AUTO_LOGIN=false

# URL de logout personnalisée (optionnel)
ACKIFY_OAUTH_LOGOUT_URL=https://your-provider.com/logout

# Scopes OAuth2 personnalisés (défaut: openid,email,profile)
ACKIFY_OAUTH_SCOPES=openid,email,profile

Méthodes d'Authentification

Important : Au moins UNE méthode d'authentification doit être activée (OAuth ou MagicLink).

# Forcer l'activation/désactivation d'OAuth (défaut: auto-détecté depuis les credentials)
ACKIFY_AUTH_OAUTH_ENABLED=true

# Activer l'authentification MagicLink sans mot de passe (défaut: false)
# Nécessite que ACKIFY_MAIL_HOST soit configuré
ACKIFY_AUTH_MAGICLINK_ENABLED=true

Auto-détection :

• OAuth est automatiquement activé si ACKIFY_OAUTH_CLIENT_ID et ACKIFY_OAUTH_CLIENT_SECRET sont définis
• MagicLink nécessite une activation explicite avec ACKIFY_AUTH_MAGICLINK_ENABLED=true + configuration SMTP
• Service SMTP/Email est automatiquement activé quand ACKIFY_MAIL_HOST est configuré (indépendant de MagicLink)

Note : SMTP et MagicLink sont deux fonctionnalités distinctes :

• SMTP = Service d'envoi de rappels email aux signataires attendus (auto-détecté)
• MagicLink = Authentification sans mot de passe par email (nécessite activation explicite + SMTP)

Administration

# Liste d'emails admin (séparés par virgules)
ACKIFY_ADMIN_EMAILS=admin@company.com,admin2@company.com

# Restreindre la création de documents aux admins uniquement (défaut: false)
ACKIFY_ONLY_ADMIN_CAN_CREATE=false

Les admins ont accès à :

• Dashboard admin (/admin)
• Gestion des métadonnées documents
• Tracking des signataires attendus
• Envoi de rappels email
• Suppression de documents

Quand ACKIFY_ONLY_ADMIN_CAN_CREATE est activé :

• ✅ Seuls les utilisateurs admin peuvent créer de nouveaux documents
• ✅ Les utilisateurs non-admin verront un message d'erreur lors d'une tentative de création
• ✅ Les deux endpoints API (POST /documents et GET /documents/find-or-create) sont protégés

Limitation de Débit (Rate Limiting)

Configuration des limites de requêtes API pour prévenir les abus et contrôler le débit :

# Limites d'authentification Magic Link (par fenêtre de temps)
ACKIFY_AUTH_MAGICLINK_RATE_LIMIT_EMAIL=3   # Max requêtes par email (défaut: 3)
ACKIFY_AUTH_MAGICLINK_RATE_LIMIT_IP=10     # Max requêtes par IP (défaut: 10)

# Limites API générales (requêtes par minute)
ACKIFY_AUTH_RATE_LIMIT=5          # Endpoints d'authentification (défaut: 5/min)
ACKIFY_DOCUMENT_RATE_LIMIT=10     # Création de documents (défaut: 10/min)
ACKIFY_GENERAL_RATE_LIMIT=100     # Requêtes API générales (défaut: 100/min)

# Import CSV
ACKIFY_IMPORT_MAX_SIGNERS=500     # Max signataires par import CSV (défaut: 500)

Quand ajuster :

• Tests/CI : Augmenter les limites (ex: 1000) pour éviter les erreurs 429 durant les tests automatisés
• Trafic élevé : Augmenter GENERAL_RATE_LIMIT pour les charges de production
• Sécurité : Réduire AUTH_RATE_LIMIT pour prévenir les attaques par force brute

Journalisation (Logging)

# Niveau de log : debug, info, warn, error (défaut: info)
ACKIFY_LOG_LEVEL=info

# Format de log : classic ou json (défaut: classic)
ACKIFY_LOG_FORMAT=classic

Formats de log :

• classic : Format lisible pour le développement et déploiements simples
• json : JSON structuré pour aggrégateurs de logs (Datadog, ELK, Splunk)

Exemple de sortie JSON :

{"time":"2025-11-24T10:00:00Z","level":"INFO","msg":"Server started","port":8080}

Checksums Documents (Optionnel)

Configuration pour le calcul automatique de checksum lors de la création de documents depuis des URLs :

# Taille maximale de fichier à télécharger pour le calcul de checksum (défaut: 10485760 = 10MB)
ACKIFY_CHECKSUM_MAX_BYTES=10485760

# Timeout pour le téléchargement checksum en millisecondes (défaut: 5000ms = 5s)
ACKIFY_CHECKSUM_TIMEOUT_MS=5000

# Nombre maximum de redirections HTTP à suivre (défaut: 3)
ACKIFY_CHECKSUM_MAX_REDIRECTS=3

# Liste de types MIME autorisés séparés par virgules (défaut inclut PDF, images, docs Office, ODF)
ACKIFY_CHECKSUM_ALLOWED_TYPES=application/pdf,image/*,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.oasis.opendocument.*

Note : Ces paramètres s'appliquent uniquement lorsque les admins créent des documents via le dashboard admin avec une URL distante. Le système tentera de télécharger et calculer le checksum SHA-256 automatiquement.

Variables de test (⚠️ NE JAMAIS utiliser en production) :

# Désactiver la protection SSRF (tests uniquement)
ACKIFY_CHECKSUM_SKIP_SSRF_CHECK=false

# Ignorer la vérification des certificats TLS (tests uniquement)
ACKIFY_CHECKSUM_INSECURE_SKIP_VERIFY=false

Ces variables désactivent des protections de sécurité critiques et ne doivent être utilisées que dans des environnements de test isolés.

Row Level Security (RLS)

Ackify utilise PostgreSQL Row Level Security pour l'isolation des données par tenant. Ceci est configuré automatiquement lors des migrations.

# Mot de passe pour le rôle base de données ackify_app (requis pour RLS)
ACKIFY_APP_PASSWORD=your_secure_app_password

Fonctionnement :

• L'outil migrate crée un rôle non-superuser ackify_app avant d'exécuter les migrations
• L'application se connecte à PostgreSQL avec ce rôle
• Les policies RLS filtrent automatiquement toutes les requêtes par tenant
• Aucune fuite de données possible même si le code applicatif oublie le filtrage tenant

Voir Row Level Security pour la documentation détaillée.

Configuration Avancée

OAuth2 Providers

Voir OAuth Providers pour la configuration détaillée de :

• Google OAuth2
• GitHub OAuth2
• GitLab OAuth2 (public + self-hosted)
• Custom OAuth2 provider

Email (SMTP)

Voir Email Setup pour configurer l'envoi de rappels email.

Exemple Complet

Exemple de .env pour une installation en production :

# Application
APP_DNS=sign.company.com
ACKIFY_BASE_URL=https://sign.company.com
ACKIFY_ORGANISATION="ACME Corporation"
ACKIFY_LOG_LEVEL=info
ACKIFY_LISTEN_ADDR=:8080

# Base de données
POSTGRES_USER=postgres
POSTGRES_PASSWORD=super_secure_password_123
POSTGRES_DB=ackify

# RLS (Row Level Security)
ACKIFY_APP_PASSWORD=another_secure_password_456

# OAuth2 (Google)
ACKIFY_OAUTH_PROVIDER=google
ACKIFY_OAUTH_CLIENT_ID=123456789-abc.apps.googleusercontent.com
ACKIFY_OAUTH_CLIENT_SECRET=GOCSPX-xyz123
ACKIFY_OAUTH_ALLOWED_DOMAIN=@company.com

# Sécurité
ACKIFY_OAUTH_COOKIE_SECRET=ZXhhbXBsZV9iYXNlNjRfc2VjcmV0X2tleQ==

# Administration
ACKIFY_ADMIN_EMAILS=admin@company.com,cto@company.com

# Email (optionnel - omettre MAIL_HOST pour désactiver)
ACKIFY_MAIL_HOST=smtp.gmail.com
ACKIFY_MAIL_PORT=587
ACKIFY_MAIL_USERNAME=noreply@company.com
ACKIFY_MAIL_PASSWORD=app_specific_password
ACKIFY_MAIL_FROM=noreply@company.com
ACKIFY_MAIL_FROM_NAME="Ackify - ACME"
ACKIFY_MAIL_TEMPLATE_DIR=templates/emails
ACKIFY_MAIL_DEFAULT_LOCALE=fr

# Checksums Documents (optionnel - pour auto-checksum depuis URLs)
ACKIFY_CHECKSUM_MAX_BYTES=10485760
ACKIFY_CHECKSUM_TIMEOUT_MS=5000
ACKIFY_CHECKSUM_MAX_REDIRECTS=3

Validation de la Configuration

Après modification du .env, redémarrer :

docker compose restart ackify-ce

Vérifier les logs :

docker compose logs -f ackify-ce

Tester le health check :

curl http://localhost:8080/api/v1/health

Variables de Production

Checklist sécurité production :

• ✅ Utiliser HTTPS (ACKIFY_BASE_URL=https://...)
• ✅ Générer des secrets forts (64+ caractères)
• ✅ Configurer RLS avec un mot de passe fort (ACKIFY_APP_PASSWORD)
• ✅ Restreindre le domaine OAuth (ACKIFY_OAUTH_ALLOWED_DOMAIN)
• ✅ Configurer les emails admin (ACKIFY_ADMIN_EMAILS)
• ✅ Utiliser PostgreSQL avec SSL en production
• ✅ Logger en mode info (pas debug)
• ✅ Sauvegarder régulièrement la base de données

Voir Deployment pour plus de détails sur le déploiement en production.