CyberTrainGuidesConfiguration

Configuration

Configuration et variables d’environnement

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.port = 3000
  c.workers = 1
end

Cybertrain::Config lit d’abord l’environnement ; config/app.rb a le dernier mot :

Variable Attribut Par défaut
CYBERTRAIN_ENV env "development" ; "production" dans un binaire issu de cybertrain build (aussi "test")
PORT port 3000
CYBERTRAIN_DATABASE database_path storage/#{env}.sqlite3
CYBERTRAIN_SECRET_KEY_BASE secret_key_base requis en production ; en dev/test, un secret est généré automatiquement dans tmp/secret_key
CYBERTRAIN_ENCRYPTION_KEY encryption_key "" ; 64 caractères hexadécimaux (cybertrain secret --hex), la clé des colonnes qu’un modèle chiffre avec encrypts. Le démarrage échoue si elle est mal formée, ou vide dès qu’un modèle déclare encrypts (voir Colonnes chiffrées)
CYBERTRAIN_ENCRYPTION_KEY_PREVIOUS encryption_keys_previous [] ; d’anciennes clés séparées par des virgules, essayées pour le déchiffrement seulement, pour changer de clé en réenregistrant les enregistrements ; une entrée mal formée arrête le démarrage
SPINEL_WORKERS workers 1 ; le serveur de développement l’ignore et tourne toujours avec un seul worker (pourquoi)
CYBERTRAIN_HOST host "127.0.0.1" ; 0.0.0.0 écoute sur toutes les interfaces (conteneurs)
CYBERTRAIN_ALLOWED_HOSTS allowed_hosts Le développement accepte localhost, 127.0.0.1, [::1] ; des noms d’hôte exacts séparés par des virgules étendent cette liste (sans schéma, port ni joker). Les autres hôtes reçoivent une 403 avant les fichiers statiques, les sessions, le routage ou les diagnostics. C’est distinct de l’adresse d’écoute ; la production et le test n’appliquent cette liste qu’une fois que CYBERTRAIN_HOSTS y active le contrôle
CYBERTRAIN_HOSTS hosts_from_env (ajouté à allowed_hosts) [] ; des noms d’hôte exacts séparés par des virgules (une adresse IPv6 entre crochets ; sans schéma, chemin, port ni joker, sinon le démarrage échoue), ajoutés après les noms du loopback dans tous les environnements. Définis, ils activent le contrôle des hôtes en production et en test aussi : un autre Host reçoit une 403 Blocked host et est journalisé. Un GET ou HEAD du chemin de santé passe quel que soit le Host (voir Hôtes)
CYBERTRAIN_FORCE_SSL force_ssl false ; 1 ou true redirige http vers https (301 pour GET et HEAD, 307 sinon ; d’après X-Forwarded-Proto derrière un proxy), envoie Strict-Transport-Security: max-age=63072000; includeSubDomains et écrit tous les cookies Secure ; le chemin de santé n’est jamais redirigé. Toute autre valeur que 1, true, 0, false ou vide arrête le démarrage. Derrière un proxy, définissez aussi CYBERTRAIN_TRUSTED_PROXY ou CYBERTRAIN_TRUSTED_PROXIES, sinon les URL que l’application construit restent en http
CYBERTRAIN_SESSION_SAME_SITE session_same_site "Lax" ; aussi Strict ou None (None ajoute toujours Secure) ; toute autre valeur arrête le serveur au démarrage
CYBERTRAIN_SESSION_PARTITIONED session_partitioned false ; 1 ou true ajoute Partitioned (et Secure)
CYBERTRAIN_TRUSTED_PROXY trusted_proxy false ; 1 ou true fait de request.client_ip (ce que compte rate_limit) la dernière adresse de X-Forwarded-For d’une connexion venant du loopback, pour un reverse proxy sur le même hôte (voir Limitation du débit) ; raccourci de CYBERTRAIN_TRUSTED_PROXIES=127.0.0.0/8,::1
CYBERTRAIN_TRUSTED_PROXIES trusted_proxies [] ; des adresses IPv4/IPv6 ou des CIDR séparés par des virgules (172.16.0.0/12,10.0.0.0/8) dont les connexions ont leur request.client_ip tiré de la dernière adresse de X-Forwarded-For, pour un proxy atteint par un réseau, comme kamal-proxy dans son conteneur ; une entrée invalide arrête le serveur au démarrage
CYBERTRAIN_MAX_PAGE max_page 10000 : la plus grande page que donne params.page_number et qu’accepte Relation#page (voir Pagination) ; une valeur qui n’est pas un nombre d’au plus 18 chiffres, ou inférieure à 1, donne la valeur par défaut
CYBERTRAIN_FILTER_PARAMETERS filter_parameters ["password", "password_confirmation", "token", "secret", "secret_key_base", "session_key", "api_key", "authorization"] ; des noms séparés par des virgules remplacent la liste. Un paramètre dont le nom contient l’un d’eux (sans tenir compte de la casse ASCII : password correspond aussi à user[password]) voit sa valeur écrite [FILTERED] dans le journal des requêtes et sur la page d’erreur de développement ; [] dans config/app.rb désactive ce filtrage
CYBERTRAIN_LOG_LEVEL log_level :info : le niveau le moins important écrit, debug, info, warn, error, fatal ou none (en majuscules ou minuscules ; none coupe le journal des requêtes et écrit toujours les lignes d’erreur) ; toute autre valeur arrête le démarrage (voir Journaux). cybertrain test utilise :none sauf si config/app.rb le fixe
CYBERTRAIN_LOG_FORMAT log_format :text ; json écrit un objet JSON par ligne, pour un collecteur de journaux ; toute autre valeur arrête le démarrage. cybertrain test garde des lignes de texte sauf si config/app.rb le fixe, quoi que dise la variable
CYBERTRAIN_SENTRY_DSN sentry_dsn "" : rien n’est envoyé. Un DSN Sentry ou GlitchTip y envoie chaque rapport d’erreur (voir Signalement des erreurs) ; il demande require "cybertrain/error_reporter/sentry" (ou require "cybertrain") dans bin/<app>.rb, faute de quoi le démarrage est refusé. Un DSN illisible arrête le démarrage en nommant la partie fautive, jamais la clé. cybertrain test le vide sauf si config/app.rb l’affecte
CYBERTRAIN_ERROR_SAMPLE_RATE error_sample_rate 1.0 : la part des rapports d’erreur envoyés à Sentry, de 0.0 à 1.0, écrite en chiffres avec un .chiffres facultatif ; les abonnés voient chaque rapport ; toute autre valeur arrête le démarrage
CYBERTRAIN_RELEASE release "" : la version ou le commit envoyé avec chaque rapport d’erreur
CYBERTRAIN_WORKER worker true ; 0 ou false empêche un processus server d’exécuter les tâches planifiées, les jobs et les flux WebSocket (voir Rôles des processus) ; ./<app> worker et feeds l’ignorent
CYBERTRAIN_JOB_THREADS job_threads 3 : le nombre de jobs qu’un processus exécute en même temps (voir Tâches de fond) ; au moins 1
CYBERTRAIN_TIME_ZONE time_zone "UTC" : le fuseau de l’application, un nom IANA comme Asia/Tokyo, pour Time.zone, les limites des jours et des mois, Date.current, l et time_tag (voir Fuseaux horaires) ; un fuseau absent du zoneinfo du système arrête le démarrage
CYBERTRAIN_SCHEDULER_TZ scheduler_tz time_zone quand il n’est pas réglé : le fuseau dans lequel se lit une tâche Scheduler.cron sans tz:, un nom IANA (voir Fuseaux horaires) ; un fuseau absent du zoneinfo du système arrête le démarrage
CYBERTRAIN_JOBS_PAGE_PER_PAGE jobs_page_per_page 50 : lignes par liste sur la page des jobs ; au moins 1
CYBERTRAIN_CACHE_PRUNE_INTERVAL cache_prune_interval 300 : secondes entre deux purges des lignes expirées du cache, lu quand cybertrain/cache est requis ; au moins 1
CYBERTRAIN_FEED_STATUS_INTERVAL feed_status_interval 10 : secondes entre deux écritures de la ligne d’état de chaque flux WebSocket (voir Santé des flux) ; au moins 1
CYBERTRAIN_FEED_RESTART_LIMIT feed_restart_limit 10 : redémarrages du thread d’un flux dans la fenêtre au-delà desquels un processus feeds se termine avec le statut 1 quand le flux meurt encore (voir Consommer des flux WebSocket) ; au moins 1
CYBERTRAIN_FEED_RESTART_WINDOW feed_restart_window 600 : cette fenêtre, en secondes ; au moins 1
CYBERTRAIN_STREAM_PATH stream_path "/cybertrain/stream" : le point d’entrée temps réel (voir Temps réel) ; une valeur vide désactive les flux ; il doit commencer par / et différer de health_path
CYBERTRAIN_REUSE_PORT reuse_port false ; 1 ou true lie le port avec SO_REUSEPORT, de sorte que plusieurs processus peuvent écouter sur un même port et que, sous Linux, le noyau répartit les connexions entre eux (ignoré en développement ; voir Running several processes). Mettez CYBERTRAIN_WORKER=0 dans tous les processus sauf un
CYBERTRAIN_HEALTH_PATH health_path "/up" ; le chemin du contrôle de santé intégré (voir Exploitation) ; une valeur vide le désactive ; une valeur sans / initial arrête le serveur au démarrage. health_worker_stale (300 s) se règle dans config/app.rb
CYBERTRAIN_HEALTH_FEEDS health_feeds true : le contrôle de santé répond aussi 503 feed stale pour un flux WebSocket qui a cessé de signaler son état ou s’est tu (voir Santé des flux) ; 0 ou false désactive cette partie
CYBERTRAIN_HEALTH_FEED_STALE health_feed_stale 180 : secondes de silence d’un flux, ou de son processus qui n’écrit plus son état, avant 503 feed stale ; au moins 1, et plus que feed_status_interval tant que health_feeds est actif (le démarrage le refuse sinon)
CYBERTRAIN_HTTP_ALLOW_PRIVATE http_allow_private false ; 1 ou true permet à Cybertrain::HttpClient de se connecter au loopback, aux adresses privées et aux autres adresses non publiques (voir HTTP sortant)
CYBERTRAIN_SMTP_HOST smtp_host "" ; le serveur SMTP par lequel envoie Cybertrain::Mailer (voir Envoyer des e-mails)
CYBERTRAIN_SMTP_PORT smtp_port 0 : le port du mode, 587 pour starttls, 465 pour tls, 25 pour none ; toute valeur hors de 1 à 65535 vaut 0
CYBERTRAIN_SMTP_USER smtp_user "" : pas d’AUTH ; s’il est défini, le mailer s’authentifie avec AUTH PLAIN
CYBERTRAIN_SMTP_PASSWORD smtp_password "" ; un secret, jamais journalisé, jamais dans la bannière de démarrage ni dans un message d’erreur
CYBERTRAIN_SMTP_FROM smtp_from "" : l’expéditeur qu’utilise Mailer.deliver quand from: n’est pas fourni
CYBERTRAIN_SMTP_TLS smtp_tls "starttls" ; aussi tls (TLS implicite) ou none (texte en clair, identifiants vers le loopback uniquement) ; les deux modes TLS demandent require "cybertrain/net/tls", que require "cybertrain" charge
CYBERTRAIN_MAIL_DELIVERY_METHOD mail_delivery_method :test dans l’environnement de test, :smtp dans tous les autres : :test garde chaque courriel dans Cybertrain::Mailer.deliveries au lieu de l’envoyer (Tester les courriels) ; hors de l’environnement de test il démarre avec un avertissement et n’envoie rien ; toute autre valeur arrête le démarrage ; cybertrain test utilise :test sauf si config/app.rb le règle, quoi que dise la variable.
CYBERTRAIN_TEST_DATABASE — "" : le fichier que cybertrain test supprime, migre et sur lequel il exécute les tests, à la place de storage/test.sqlite3 ; un chemin de fichier (pas :memory: ni une URI file:). Un fichier existant n’est supprimé que si cybertrain test l’a créé (il marque ses bases), s’il est le storage/test.sqlite3 de cette application ou s’il est vide ; tout autre, et la base de développement ou de production, est refusé avec le code de sortie 2 sans rien supprimer (Exécuter les tests)
CYBERTRAIN_I18N_DEFAULT_LOCALE i18n_default_locale :en : la locale dans laquelle commence chaque requête, un nom comme ja ou pt-BR (voir Locales) ; toute autre valeur arrête le démarrage
CYBERTRAIN_AUTH_LOCKOUT_ATTEMPTS auth_lockout_attempts 10 : mauvais mots de passe avant qu’un compte soit verrouillé ; 0 désactive le verrouillage (voir Réglages de l’authentification)
CYBERTRAIN_AUTH_LOCKOUT_PERIOD auth_lockout_period 3600 : durée d’un verrouillage en secondes ; au moins 1
CYBERTRAIN_AUTH_REMEMBER_FOR auth_remember_for 2592000 (30 jours) : durée en secondes d’une connexion « rester connecté » ; au moins 1
CYBERTRAIN_AUTH_IDLE_TIMEOUT auth_idle_timeout 604800 (7 jours) : secondes sans requête après lesquelles une connexion prend fin ; 0 le désactive

N’utilisez None (avec CYBERTRAIN_SESSION_PARTITIONED=1) que pour une application affichée dans un cadre d’un autre site ; le navigateur doit atteindre l’application en HTTPS.

Autres attributs aux valeurs par défaut fixes et modifiables : views_root ("app/views"), public_root ("public"), layout ("layouts/application"), log_tags ([:request_id] : les étiquettes de la requête sur chaque ligne de journal ; :remote_ip ajoute l’adresse du client, [] n’en montre aucune, et toute autre valeur arrête le démarrage ; voir Identifiants de requête), session_cookie_name, session_max_age (2 semaines), session_secure (true en production, ce qui marque le cookie de session Secure ; false ailleurs, mais SameSite=None et Partitioned ajoutent Secure de toute façon), pool_size (4), static_files/csrf (true), csrf_exempt_prefixes ([] : des préfixes de chemin comme "/api/" dont les requêtes autres que GET sautent la vérification CSRF, pour un point d’accès que des programmes appellent avec un identifiant qui leur est propre ; chacun doit commencer et finir par / et ne pas être / seul, sinon le démarrage échoue ; le préfixe est comparé au chemin tel qu’envoyé, donc une graphie encodée en pourcent reste vérifiée ; aucune autre route ne doit correspondre à un chemin sous ce préfixe, et le contrôleur exempté ne doit pas compter sur la session pour l’authentification, puisque la session y est tout de même chargée), max_body_bytes (10 Mio : un corps de requête plus long, tel qu’envoyé, reçoit une 413 avant d’être lu ; augmentez-le pour les gros envois de fichiers ; la taille décompressée d’un corps gzip est bornée séparément par request.decoded_body(limit)), max_render_depth (12 rendus ouverts à la fois : la page et ses partiels ; augmentez-le pour des partiels qui s’appellent récursivement plus profondément à juste titre ; il doit valoir au moins 1, sinon le démarrage échoue). Note de mise à niveau : l’imbrication des rendus, illimitée auparavant, est désormais plafonnée à 12 par défaut (la page est à la profondeur 1, les partiels peuvent donc s’imbriquer sur 11 niveaux ; le layout est rendu après la page et ne s’imbrique pas), et une application avec un arbre plus profond (commentaires en fil, menu de catégories) obtient une erreur de template tant qu’elle ne définit pas max_render_depth. Envois de fichiers : max_upload_bytes (5 Mio par fichier envoyé ; ne doit pas dépasser max_body_bytes), max_multipart_parts (128 parties, champs texte compris, au plus 4096), upload_root ("storage/uploads", où écrit Cybertrain::BlobStore ; créé au premier envoi, pas au démarrage).

Jobs et flux : en plus des variables ci-dessus, config/app.rb règle scheduler_interval (1 s, le tick du scheduler), job_poll_interval (1 s, l’attente d’un thread de jobs inoccupé ; c’était 5 avant les threads de jobs), job_max_attempts (5), job_heartbeat_interval (30 s), job_heartbeat_stale (300 s, plus que l’intervalle), job_drain_timeout (10 s, le temps que SIGTERM attend les jobs en cours) et scheduler_lease_ttl (30 s, au moins deux fois scheduler_interval), ainsi que les réglages des flux stream_poll_ms, stream_retention, stream_ping_interval, stream_max_connections, stream_max_message et stream_max_backlog (Limites et réglages). Une valeur hors limites arrête le démarrage avec un message qui la nomme.

En-têtes de sécurité : chaque réponse qu’écrit le serveur (actions, middleware des fichiers statiques, pages d’erreur et page de diagnostic de développement, les 400/411/413/500 propres au serveur, et HEAD) porte X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN et Permissions-Policy: camera=(), microphone=(), geolocation=(), sauf si la réponse définit déjà un en-tête de ce nom (quelle que soit la casse) : Response#to_http les ajoute après les en-têtes propres à la réponse et seulement s’ils manquent, donc response.set_header("X-Frame-Options", "DENY") dans une action envoie exactement votre valeur, une seule fois. c.permissions_policy remplace la valeur du troisième ("camera=(), microphone=(), geolocation=(self)"), "" n’en envoie aucun, et un CR ou un LF dedans arrête le démarrage. Il n’y a délibérément pas de réglage Config pour désactiver les deux premiers dans toute l’application ; un widget intégrable remplace l’en-tête sur ses propres réponses (un en-tête Content-Security-Policy: frame-ancestors ... l’emporte sur X-Frame-Options dans les navigateurs actuels). À cause de nosniff, les navigateurs prennent Content-Type au pied de la lettre : le middleware des fichiers statiques connaît les extensions habituelles de public/ (html, css, js/mjs, images dont webp et avif, polices, wasm, pdf, audio et vidéo, json, csv, xml), et tout le reste est servi en application/octet-stream, c’est-à-dire en téléchargement ; ajoutez l’extension à Cybertrain::Static::EXTENSIONS si une application en a besoin d’une autre affichée directement. Un reverse proxy qui sert lui-même public/ contourne ces en-têtes (voir docs/deploy.en.md). Cybertrain::Test::Client appelle l’application dans le même processus et ne sérialise jamais la réponse : il ne montre donc pas ces valeurs par défaut ; vérifiez-les sur response.to_http.

Content Security Policy : désactivée par défaut, comme dans Rails ; cybertrain new écrit le bloc ci-dessous en commentaire dans config/app.rb. c.content_security_policy do |p| ... end déclare la politique (une méthode par directive, p.script_src :self, "https://cdn.jsdelivr.net" ; un second appel complète la même politique), c.content_security_policy_nonce_directives ([]) nomme les directives qui reçoivent le nonce de la requête (un nom qui n’est pas une directive arrête le démarrage), et c.content_security_policy_report_only (false) envoie l’en-tête sous la forme Content-Security-Policy-Report-Only. Un contrôleur déclare sa propre copie avec content_security_policy do |p| ; voir Content Security Policy.

Paramètres filtrés : la ligne Started GET "/login?..." du journal des requêtes et la page d’erreur de développement (sa ligne de requête, et son affichage des params et d’un corps JSON) montrent la valeur de chaque paramètre nommé dans config.filter_parameters sous la forme [FILTERED], comme le fait le filter_parameters de Rails, de sorte qu’un ?token= dans une URL ou un mot de passe posté à un formulaire qui échoue n’apparaît ni dans le journal des requêtes du framework ni sur la page d’erreur de développement. Seules les valeurs sont remplacées : le reste de la chaîne de requête est journalisé tel qu’envoyé (caractères de contrôle échappés). La liste compare par sous-chaîne, sans tenir compte de la casse ; étendez-la dans config/app.rb (c.filter_parameters = c.filter_parameters + ["otp", "ssn"]) ou remplacez-la avec CYBERTRAIN_FILTER_PARAMETERS. Les valeurs qu’une action journalise elle-même ne sont pas filtrées ; interrogez-y Cybertrain::ParameterFilter.filter?(name) ou ParameterFilter.filter_query(text).

Déploiement : cybertrain build produit dist/ : le binaire dist/NAME avec les vues intégrées, dist/public/ (ressources statiques, ou laissez un reverse proxy le servir), ainsi que dist/storage/ (le fichier SQLite par défaut) et dist/tmp/. Lancez-le depuis dist/ avec CYBERTRAIN_SECRET_KEY_BASE défini ; il est en production sauf si CYBERTRAIN_ENV indique autre chose, et ./NAME migrate applique les migrations compilées dans le binaire. Le binaire ne parle que du HTTP/1.1 simple ; placez nginx/Caddy devant pour le TLS et HTTP/2 (le cookie de session est Secure en production, servez donc l’application en HTTPS). En production, une exception renvoie une 500, et une réponse d’erreur brute (la 404 en texte brut du routeur, head :not_found, render plain:) est remplacée par public/<status>.html quand ce fichier existe ; les erreurs qu’une action rend en HTML ou en JSON passent telles quelles. SIGTERM cesse d’accepter des connexions, laisse se terminer les requêtes déjà en cours (auxquelles il est répondu avec Connection: close ; les connexions keep-alive inactives sont fermées immédiatement) et quitte quand elles sont terminées, ou après le drain_timeout du serveur (10 s). La boucle de surveillance et de recompilation ne tourne jamais en production. docs/deploy.en.md (en japonais : docs/deploy.md) en décrit tout le parcours : cybertrain new, un serveur Ubuntu, systemd, Caddy avec HTTPS, les redéploiements, les retours arrière et les sauvegardes.

Kamal : cybertrain new écrit aussi ce dont Kamal 2 a besoin : un Dockerfile qui exécute cybertrain setup et cybertrain build dans une étape de build Ubuntu et copie dist/ dans une étape allégée de la même version (migration au démarrage, puis service sur 0.0.0.0:3000), un .dockerignore, config/deploy.yml (kamal-proxy avec Let’s Encrypt en façade, le contrôle de santé sur public/up.html, le fichier SQLite sur un volume en /app/storage) et .kamal/secrets (KAMAL_REGISTRY_PASSWORD et CYBERTRAIN_SECRET_KEY_BASE tirés de l’environnement). Renseignez les valeurs marquées CHANGE ME, committez, puis lancez kamal setup ; docs/deploy-kamal.md donne les détails (partie 8 du tutoriel de déploiement). examples/blog embarque la même configuration, construite avec le framework de cette copie du dépôt.

Réglages de l’application

Les réglages propres à une application (une URL de base publique, un interrupteur de fonctionnalité, un intervalle, un hôte SMTP) sont déclarés sur le même Config, avec un type, une variable d’environnement et une valeur par défaut :

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.setting_string :base_url, env: "MYAPP_BASE_URL", default: ""
  c.setting_string :smtp_password, env: "MYAPP_SMTP_PASSWORD", default: "", secret: true
  c.setting_bool :worker, env: "MYAPP_WORKER", default: true
  c.setting_int :prune_interval, env: "MYAPP_PRUNE_INTERVAL", default: 3600, min: 1, max: 9_999_999
end

Cybertrain.config.string_setting(:base_url)
Cybertrain.config.bool_setting(:worker)
Cybertrain.config.int_setting(:prune_interval)

Chaque valeur est lue une seule fois, quand config/app.rb s’exécute au démarrage. Une variable vide ou non définie signifie la valeur par défaut. Un booléen accepte 1/true ou 0/false ; un entier accepte des chiffres décimaux (avec un - initial facultatif) compris dans min..max (tous deux facultatifs). Toute autre valeur se rabat sur la valeur par défaut et journalise une ligne WARN qui le signale (une ligne de texte quel que soit log_format : config/app.rb est encore en cours). Lire un nom non déclaré, ou déclaré avec un autre type, lève ArgumentError, tout comme déclarer deux fois un même nom. Les tests changent une valeur avec set_string_setting, set_int_setting et set_bool_setting. ./NAME help liste chaque réglage déclaré avec sa variable et sa valeur par défaut, et la bannière de démarrage affiche les valeurs courantes (=> Settings: base_url="" worker=true ...) ; un réglage secret: true n’apparaît dans les deux que par son nom, sous la forme [FILTERED]. Il n’y a pas d’accesseur Cybertrain.config.base_url : Spinel n’a pas de define_method, les lecteurs sont donc des méthodes typées qui prennent le nom.

Locales

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.i18n_default_locale = :en               # ou CYBERTRAIN_I18N_DEFAULT_LOCALE
  c.i18n_available_locales = [:en, :ja]
  c.i18n_raise_on_missing = true if c.test?
end

i18n_available_locales ([], la seule locale par défaut) liste les locales qu’acceptent I18n.locale= et I18n.locale_available? ; le démarrage refuse une entrée qui n’est pas un nom de locale, et une locale par défaut absente d’une liste non vide. i18n_raise_on_missing (false) fait lever I18n::MissingTranslationData à une traduction manquante au lieu de répondre un marqueur (développement et test) ou la clé rendue lisible (production). Les dictionnaires et la locale par requête sont dans Internationalisation.

Réglages de l’authentification

Le code qu’écrit cybertrain generate authentication lit quatre réglages (les variables sont dans le tableau ci-dessus) : auth_lockout_attempts (10) et auth_lockout_period (3600 s) pour le verrouillage, auth_remember_for (30 jours) pour une connexion « rester connecté », et auth_idle_timeout (7 jours) pour une connexion inutilisée (Rester connecté) ; une connexion non mémorisée dure session_absolute_max_age (deux semaines). Une valeur hors limites arrête le démarrage. Le générateur déclare aussi le réglage d’application base_url, issu de <APP>_BASE_URL, par lequel commencent les liens des courriels ; définissez-le, en https, partout où l’application est servie (Liens dans les courriels).

Fuseaux horaires

Spinel n’embarque pas de base de données tz, et définir ENV["TZ"] pour convertir une heure la change pour tous les threads du processus. Cybertrain::TimeZone lit plutôt les fichiers de fuseaux du système : /usr/share/zoneinfo/<name>, ou $TZDIR/<name> quand TZDIR est défini (installez le paquet tzdata dans une image de conteneur allégée). Il analyse les versions 1 à 4 de TZif (RFC 8536), y compris la règle TZ POSIX dont dépend un fichier « slim » après sa dernière transition, et met chaque fuseau en cache pour toute la durée de vie du processus (copie à l’écriture, donc les recherches depuis plusieurs workers ne prennent aucun verrou).

Tout est exprimé en secondes epoch Integer. Une epoch locale est une lecture d’horloge murale comptée comme si c’était de l’UTC, de sorte que l’arithmétique sur l’heure murale est une simple addition, et que TimeZone.civil_to_epoch / TimeZone.epoch_to_civil passent de cette valeur à [year, month, day, hour, minute, second] et inversement :

ruby
tokyo = Cybertrain::TimeZone.find("Asia/Tokyo")
tokyo.found?                         # false pour un nom inconnu : le fuseau se comporte alors comme UTC
tokyo.utc_offset_at(Time.now.to_i)   # => 32400
tokyo.abbreviation_at(Time.now.to_i) # => "JST"

# Le prochain 09:00 à Tokyo :
now = Time.now.to_i
today = Cybertrain::TimeZone.epoch_to_civil(tokyo.utc_to_local(now))
run = tokyo.local_to_utc(Cybertrain::TimeZone.civil_to_epoch(today[0], today[1], today[2], 9, 0, 0))
run = tokyo.local_to_utc(Cybertrain::TimeZone.civil_to_epoch(today[0], today[1], today[2] + 1, 9, 0, 0)) if run <= now

Lors d’un changement d’heure, local_to_utc est déterministe : une heure murale qu’un saut en avant fait sauter (02:30 le jour du passage à l’heure d’été aux États-Unis) est lue avec le décalage d’avant le saut, et tombe donc après lui (03:30 EDT) ; une heure murale qu’un recul répète donne l’instant le plus tôt. find n’accepte qu’un nom relatif composé de A-Za-z0-9_+-./ sans segment vide, . ou .., de sorte qu’un nom de fuseau tiré du profil d’un utilisateur ne peut pas atteindre un fichier hors du répertoire des fuseaux ; un fuseau inconnu ou mal formé n’est pas mis en cache, et "UTC" n’a besoin d’aucun fichier.

Le fuseau de l’application

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.time_zone = "Asia/Tokyo"   # ou CYBERTRAIN_TIME_ZONE ; "UTC" par défaut
end

c.time_zone prend un nom IANA (les noms propres à Rails, comme « Tokyo », ne sont pas lus), et le démarrage s’arrête sur un fuseau que le système n’a pas. Les valeurs restent des instants UTC : une colonne, Time.current et les méthodes de calendrier renvoient un Time UTC, et time.hour est l’heure UTC. Le fuseau décide du calendrier (beginning_of_day et consorts, Date.current ; Les heures et le fuseau horaire) et de l’affichage : l(time) et time_tag(time) montrent un Time dans ce fuseau, %z et %Z compris, et le datetime de time_tag est en ISO 8601 avec le décalage du fuseau (2026-11-12T05:00:00+09:00). l(time, zone: "America/New_York") et time_tag(time, zone: "...") montrent une valeur dans un autre fuseau. Un Time au décalage 0, c’est-à-dire tout Time que le framework fournit, est montré dans le fuseau ; un Time qui porte un autre décalage qui lui est propre (time.getlocal("+05:30")) le garde sauf si zone: est donné ; une Date est montrée telle quelle. Les tâches cron sans tz: suivent aussi le fuseau, sauf si scheduler_tz est réglé. Une commande enregistrée (Main.command), ./<app> jobs et ./<app> console installent aussi le fuseau avant de s’exécuter, et refusent un fuseau inconnu comme le démarrage, avec error: time_zone "Mars/Base" is not a known time zone et le code de sortie 1, avant d’ouvrir la base. Dans cybertrain test, chaque test commence dans le fuseau configuré. (Dates et heures donne les formats de l.)