CyberTrainTutoriel

Premiers pas : le blog

Calqué sur le guide Getting Started de Rails : un blog avec des articles et des commentaires. Vous allez générer le scaffold des articles, ajouter des validations, imbriquer les commentaires sous les articles, pousser les nouveaux commentaires vers toutes les pages ouvertes avec Turbo, mettre en file un job d’arrière-plan, répondre en JSON, écrire des tests qui pilotent l’application dans le même processus, ajouter la connexion, joindre une image envoyée, et compiler l’application dans un dossier dist/ déployable. L’application à laquelle mène ce tutoriel est examples/blog, testée par la CI sous Linux et macOS.

Prérequis
Ruby 3.2+, cc, make, git, curl, en-têtes SQLite 3, zlib et OpenSSL (Spinel est installé pour vous) Étape 00
Point de départ
gem install cybertrain
Résultat
dist/blog

Vous êtes ici :Installation Ruby, cc, SQLite

Prérequis

PourquoiCyberTrain compile via Spinel vers du C : il lui faut donc une chaîne de compilation C et les en-têtes SQLite ; la commande cybertrain est une gem, il lui faut donc Ruby.

  • Ruby 3.2+ et RubyGems, pour la commande cybertrain et pour l’aperçu CRuby du serveur de développement (qui demande fiddle, la bibliothèque de Ruby) ; une application déployée ne tourne jamais sur CRuby. Avec Ruby 3.2, ajoutez aussi gem install prism.
  • Spinel, à la version qu’épingle CyberTrain (cybertrain doctor l’affiche), du fork saeki-mototsune/spinel, qui intègre les corrections dont CyberTrain a besoin avant une version amont ; non testé avec d’autres versions. Vous ne l’installez pas à la main : la première commande qui en a besoin compile cette version dans ~/.cybertrain (quelques minutes, une seule fois), sauf si un spinel de cette version est déjà dans le PATH.
  • Une chaîne de compilation C (cc, ou le compilateur désigné par CC) et make, plus git et curl, pour compiler Spinel, qui compile chaque programme en C.
  • En-têtes et bibliothèques SQLite 3, zlib et OpenSSL : libsqlite3-dev, zlib1g-dev et libssl-dev sous Debian/Ubuntu. Sous macOS, SQLite et zlib sont fournis avec les Command Line Tools de Xcode, et OpenSSL par Homebrew (brew install openssl@3, puis les deux chemins qu’indique Prérequis).

cybertrain doctor vérifie tout cela et affiche la commande d’installation de ce qui manque. La liste complète et ce qui est facultatif : Prérequis ; où Spinel est placé et comment utiliser une autre installation : comment Spinel est installé.

Pas de machine sur laquelle installer ? Le bac à sable ouvre ce blog dans un GitHub Codespace avec les étapes 02, 03, 04 et 07 déjà faites.

Vous êtes ici :Installation la CLI cybertrain

Installer la CLI

Pourquoicybertrain est la commande qui crée les applications, génère les scaffolds de ressources, migre, sert et compile.

La première ligne l’installe depuis RubyGems. Le reste est le tutoriel entier en un coup d’œil ; les étapes ci-dessous le reprennent une commande à la fois.

terminal — n’importe quel répertoire, puis blog/shell
gem install cybertrain
cybertrain new blog          # installe Spinel la première fois (quelques minutes)
cd blog
cybertrain g scaffold article title:string body:text
cybertrain db migrate
cybertrain server            # http://127.0.0.1:3000
cybertrain build             # production: dist/blog, dist/public/, dist/storage/, dist/tmp/

Toutes les commandes, avec leurs options, sont listées dans le guide d’installation.

Vous êtes ici :Vous écrivez blog/

Créer l’application

PourquoiVous obtenez les conventions de répertoires de Rails, plus trois programmes dans bin/ : bin/blog.rb (l’application), bin/gen.rb (le générateur) et bin/db.rb (les migrations en développement).

terminal — n’importe quel répertoireshell
cybertrain new blog
cd blog

cybertrain new écrit l’application avec un spin.toml qui pointe vers la version correspondant à la CLI (X.Y.Z est ce qu’affiche cybertrain version) :

spin.tomltoml
[package]
name = "blog"
version = "0.1.0"

[dependencies]
cybertrain = { git = "https://github.com/saeki-mototsune/cybertrain", ref = "vX.Y.Z" }

Ensuite, il s’assure que Spinel est installé (la première fois, cela signifie compiler la version épinglée de Spinel dans ~/.cybertrain : quelques minutes, une seule fois ; voir l’étape 00) et lance spin lock (spin récupère le framework dans son cache, ~/.cache/spin/packages/, et épingle le commit dans spin.lock) et SPIN_DEBUG=1 spin run gen (gen compilé dans le mode debug de spin), un peu comme rails new lance bundle install, pour que cybertrain server fonctionne tout de suite. Il termine en affichant les étapes suivantes. Rien du framework n’est copié dans l’application ; commitez spin.toml et spin.lock.

Si Spinel ou l’une des deux étapes spin échoue, les fichiers restent en place, new sort avec le code 1 et affiche ce qu’il faut lancer une fois la cause corrigée (pour Spinel : cybertrain setup, puis cybertrain spin lock && SPIN_DEBUG=1 cybertrain spin run gen dans le nouveau répertoire). --skip-spin se contente d’écrire les fichiers ; --path DIR fait plutôt dépendre l’application d’une copie locale du dépôt, --git URL [--ref R] du framework situé à URL (à la branche ou au tag R), et --version V d’une version de l’index, une fois que cybertrain sera sur un spin-index.

Les noms d’application utilisent des lettres minuscules, des chiffres et _, et commencent par une lettre. L’arborescence générée :

blog/text
blog/
  spin.toml  config/app.rb  config/routes.rb  config/locales/en.yml  .env.example
  db/schema.rb  db/migrate/
  app/controllers/application_controller.rb  app/models/  app/views/  app/helpers/  app/jobs/
  app/assets/stylesheets/application.css  app/assets/images/
  app/javascript/application.js  config/importmap.rb
  public/  bin/blog.rb  bin/gen.rb  bin/db.rb
  gen/  storage/  tmp/  test/  .github/workflows/ci.yml
  Dockerfile  config/deploy.yml  .kamal/secrets

bin/blog.rb est l’unique point d’entrée de l’application, le programme que compile spin build blog : ./blog sert l’application, ./blog migrate et ./blog db status gèrent la base de données. bin/gen.rb lance le générateur (spin run gen), et bin/db.rb lance le migrateur pendant le développement (cybertrain db migrate l’utilise, car bin/blog.rb ne peut pas compiler tant que la première migration n’a pas généré gen/models/). gen/ contient déjà ce qu’a écrit spin run gen, dont views.rb : la table des vues intégrées, versionnée et vide.

bin/blog.rb et bin/db.rb commencent tous deux par require "cybertrain/core" : le framework sans ses sous-systèmes optionnels (les jobs, Turbo Streams, le mailer, le cache et les autres), ce qui raccourcit chaque build. Les étapes suivantes qui en utilisent un ajoutent sa ligne (Sous-systèmes).

Le layout lie app/assets/stylesheets/application.css avec stylesheet_link_tag et charge app/javascript/application.js via l’import map de config/importmap.rb avec javascript_importmap_tags ; spin run gen écrit les deux avec une empreinte dans public/assets/, ignoré par git (voir Assets). .env.example liste les variables que lit l’application, .github/workflows/ci.yml lance les tests sur GitHub (Intégration continue), et la dernière ligne de l’arborescence est la configuration Kamal de l’étape 19.

ApplicationController commence ainsi, pour qu’un enregistrement introuvable donne une 404 via rescue_from :

app/controllers/application_controller.rbruby
class ApplicationController < Cybertrain::Controller
  rescue_from Cybertrain::RecordNotFound, with: :record_not_found

  private

  def record_not_found
    render plain: "Not Found", status: :not_found
  end
end

Vous êtes ici :Vous écrivez app/, db/migrate/

Scaffold d’un article

PourquoiUne seule commande écrit toute la tranche CRUD, à la Rails.

terminal — blog/shell
cybertrain generate scaffold article title:string body:text

Elle écrit une migration, un modèle, un contrôleur, cinq vues (index, show, new, edit, _form), un fichier de fixtures et des tests (étape 16), et insère resources :articles dans config/routes.rb. Les types de champ sont string, text, integer, float, boolean, date, datetime, references et attachment (un fichier envoyé, étape 18) ; le type par défaut est string. Le cybertrain g scaffold du démarrage rapide est la même commande.

Les fichiers existants ne sont jamais écrasés : chaque fichier est signalé comme create, identical ou exist.

Vous êtes ici :Vous écrivez config/routes.rb

Définir la route racine

Pourquoi/ doit afficher la liste des articles.

config/routes.rbruby
# config/routes.rb
Cybertrain::Routes.draw do
  root "articles#index"
  resources :articles
  # jobs_page "/admin/jobs", before_action: :require_admin
end

Les routes sont lues à la compilation : spin run gen les transforme en gen/routes.rb. cybertrain server, cybertrain db migrate et cybertrain build le lancent pour vous.

Vous êtes ici :Vous écrivez app/models/

Ajouter des validations au modèle

PourquoiComme dans le guide Rails, ajoutez à la main une validation de longueur.

app/models/article.rbruby
# app/models/article.rb -- only the first string field gets a default
# presence validation; add anything past that yourself.
class Article
  validates :title, presence: true
  validates :title, uniqueness: true
  validates :body, presence: true, length: { minimum: 10 }
end

class Article n’a pas de superclasse écrite : la superclasse Cybertrain::Model, les colonnes et les finders viennent de gen/models/article.rb. Un enregistrement qui échoue signale des messages tels que « Title can't be blank », « Title has already been taken » et « Body is too short (minimum is 10 characters) ». Les autres validateurs (format, inclusion, numericality, ...) sont dans Validations.

Vous êtes ici :Vous écrivez app/controllers/

Le contrôleur ArticlesController

PourquoiUn CRUD complet, à la Rails jusqu’aux strong params et au flash suivi d’une redirection, à deux choses près que Spinel impose partout.

app/controllers/articles_controller.rbruby
# app/controllers/articles_controller.rb (index/show/edit are as plain as
# Rails' own scaffold; update mirrors create)
class ArticlesController < ApplicationController
  before_action :set_article, only: [:show, :edit, :update, :destroy]

  def new_action   # a `new` method would shadow ArticlesController.new
    @article = Article.new
  end

  def create
    @article = Article.new(article_params)
    if @article.save
      flash[:notice] = "Article was successfully created."
      redirect_to article_path(@article), status: :see_other
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def set_article
    @article = Article.find(params[:id])
  end

  def article_params
    params.require(:article).permit(:title, :body)
  end
end

Le scaffold écrit le contrôleur complet, avec aussi index, show, edit, update et destroy ; l’extrait ci-dessus les omet. Dans index, @articles = Article.all.to_a : le .to_a est obligatoire.

Les variables d’instance sont trouvées par un balayage lexical des @ivar = : relancez donc cybertrain spin run gen après en avoir ajouté une ; le serveur de développement le fait pour vous.

Vous êtes ici :Compilation, puis exécution gen/ → build/bin/blog

Générer, migrer, lancer

PourquoiTransformer le schéma et les routes en gen/, créer la base SQLite, démarrer le serveur.

terminal — blog/shell
cybertrain db migrate    # spin run gen; spin run db -- migrate; spin run gen (gen et db en mode debug)
cybertrain server        # http://127.0.0.1:3000; une modification Ruby s’affiche tout de suite (CRuby), puis compilée; les vues n’ont besoin ni de l’un ni de l’autre

spin run gen lit db/schema.rb et config/routes.rb, analyse app/ et écrit gen/ ; spin run db -- migrate applique db/migrate/*.rb et réécrit db/schema.rb. L’ordre compte : le premier spin run gen place la nouvelle migration dans gen/migrations.rb, que requiert bin/db.rb, et le second construit les modèles à partir du db/schema.rb réécrit.

cybertrain server sert l’application depuis CRuby en moins d’une seconde et la compile avec Spinel en arrière-plan. La première compilation compile toute l’application, ce qui prend quelques minutes ; d’ici là, c’est l’aperçu CRuby qui répond, et chaque page le dit dans son coin inférieur droit :

sortie — cybertrain servertext
=> Booting cybertrain X.Y.Z
=> preview: CRuby 3.3.6
* Listening on http://127.0.0.1:3000
=> spinel: building (log: tmp/rebuild.log)
=> preview: CRuby (0.5s)

Une fois la compilation terminée, le serveur affiche => spinel: ready in …s; serving the compiled binary, et le binaire compilé répond à partir de là. Après une modification Ruby, il affiche Changed et le fichier, répond de nouveau tout de suite depuis CRuby et recompile (La boucle de développement). Ctrl-C l’arrête.

  • Relancez cybertrain spin run gen et commitez gen/ après avoir modifié le schéma, les routes, les callbacks et ivars d’un contrôleur ou d’un modèle, un helper, un composant ou un job, ou un asset. Le serveur de développement le fait pour vous, et cybertrain spin run gen -- --check liste ce qui est périmé sans rien écrire.
  • Changez le port avec cybertrain server 4000 (ou PORT=4000).
  • cybertrain db ajoute le -- dont spin run db a besoin avant ses arguments ; cybertrain db status et les autres commandes de base de données fonctionnent de la même façon.

Vous êtes ici :Vous écrivez db/migrate/, app/

Scaffold des commentaires

PourquoiLe type references vous donne la clé étrangère dont l’association est déduite.

terminal — blog/shell
cybertrain generate scaffold comment commenter:string body:text article:references
cybertrain db migrate    # le scaffold a écrit une migration pour la table comments

article:references ajoute une colonne article_id, un index et une clé étrangère — de quoi donner à Article/Comment leur association : spin run gen lit Article#comments et Comment#article dans la clé étrangère. Le schéma obtenu :

db/schema.rb (extrait)ruby
  s.create_table "comments" do |t|
    t.string "commenter"
    t.text "body"
    t.integer "article_id", null: false
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
  end

  s.add_index "comments", ["article_id"], name: "index_comments_on_article_id"

  s.add_foreign_key "comments", "articles", column: "article_id"

Le scaffold insère une ligne resources :comments indépendante, que l’étape suivante remplace.

Un cybertrain server laissé en marche prend en compte les fichiers du scaffold dès qu’ils sont écrits, avant que la table n’existe. Le nouveau modèle Comment tient ses colonnes de gen/models/comment.rb, que gen n’écrit qu’une fois la table présente dans db/schema.rb : l’aperçu CRuby ne peut donc pas le charger (une NoMethodError), le serveur répond par sa propre page 503 qui nomme l’erreur, et la compilation Spinel échoue aussi. Une fois que cybertrain db migrate a réécrit db/schema.rb, le serveur répond de nouveau.

Vous êtes ici :Vous écrivez config/routes.rb

Imbriquer les routes

PourquoiLe guide Rails imbrique les commentaires sous les articles.

config/routes.rbruby
Cybertrain::Routes.draw do
  root "articles#index"

  # A nested block takes the mapper explicitly (Spinel's instance_eval
  # trampoline only rewires `self` for the outermost block): `articles.resources`.
  resources :articles do |articles|
    articles.resources :comments, only: [:create, :destroy]
  end
  # jobs_page "/admin/jobs", before_action: :require_admin
end

Vous êtes ici :Vous écrivez app/controllers/

Le contrôleur CommentsController

PourquoiSeules deux actions sont accessibles, et l’article parent vient de l’URL (params[:article_id]), pas de :id.

app/controllers/comments_controller.rbruby
class CommentsController < ApplicationController
  before_action :set_article

  def create
    @comment = Comment.new(comment_params)
    @comment.article_id = @article.id
    if @comment.save
      flash[:notice] = "Comment was successfully created."
    else
      flash[:alert] = "Comment could not be saved: #{@comment.errors.full_messages.join(", ")}"
    end
    redirect_to article_path(@article), status: :see_other
  end

  def destroy
    @comment = @article.comments.find(params[:id])
    @comment.destroy
    flash[:notice] = "Comment was successfully destroyed."
    redirect_to article_path(@article), status: :see_other
  end

  private

  def set_article
    @article = Article.find(params[:article_id])
  end

  def comment_params
    params.require(:comment).permit(:commenter, :body)
  end
end

Ajoutez ensuite des validations au modèle de commentaire :

app/models/comment.rbruby
class Comment
  validates :commenter, presence: true
  validates :body, presence: true

  belongs_to :article
end

La déclaration belongs_to rend aussi invalide un commentaire sans article (« Article can't be blank »), avant que la base ne le refuse.

Article#comments est la relation des commentaires : le @article.comments.find(params[:id]) de Rails fonctionne donc tel quel dans destroy, et un commentaire placé sous le mauvais article renvoie une 404.

Vous êtes ici :Exécution app/views/, lues depuis le disque en développement, intégrées par cybertrain build

Vues et partiels

PourquoiLa page d’un article liste ses commentaires et se termine par un formulaire lié à [@article, @comment].

Supprimez d’abord les vues de commentaire index, show, new et edit, désormais inaccessibles, et donnez à ArticlesController#show un @comment vide :

app/controllers/articles_controller.rb (extrait)ruby
  def show
    @comment = Comment.new
  end

Affichez ensuite les commentaires et le formulaire à la fin de la page de l’article, et remplacez le formulaire de commentaire du scaffold :

app/views/articles/show.html.erb · app/views/comments/_form.html.erberb
<%# app/views/articles/show.html.erb %>
<h2>Comments</h2>
<% @article.comments.each do |comment| %>
  <%= render "comments/comment", comment: comment %>
<% end %>

<h2>Add a comment:</h2>
<%= render "comments/form", comment: @comment %>

<%# app/views/comments/_form.html.erb %>
<%# locals: (comment:) %>
<%= form_with(model: [@article, comment]) do |f| %>
  <%= f.label :commenter %> <%= f.text_field :commenter %>
  <%= f.label :body %> <%= f.text_area :body %>
  <%= f.submit %>
<% end %>

Le partiel de commentaire :

app/views/comments/_comment.html.erberb
<%# locals: (comment:) %>
<div class="comment">
  <p>
    <strong>Commenter:</strong>
    <%= comment.commenter %>
  </p>

  <p>
    <strong>Comment:</strong>
    <%= comment.body %>
  </p>

  <%= button_to "Destroy comment", [@article, comment], method: :delete %>
</div>

Où pointent le formulaire et le bouton

button_to ... [@article, comment] et form_with(model: [@article, comment]) se résolvent tous deux selon la même règle [parent, child] : un nouvel enfant est routé vers la collection imbriquée (article_comments_path), un enfant persisté vers le membre imbriqué (article_comment_path), tous deux générés dans gen/routes.rb à partir du bloc resources imbriqué ci-dessus. Le formulaire reçoit son commentaire comme variable locale, pour que l’étape 13 puisse le rendre de nouveau avec un commentaire neuf.

Vous êtes ici :Vous écrivez app/components/, app/helpers/

Un composant et un helper

PourquoiÀ partir de l’étape suivante, un commentaire est rendu à deux endroits : sur la page, et dans une diffusion derrière laquelle il n’y a aucune requête. Un composant, une classe avec son template à côté, se rend de la même façon dans les deux cas ; un helper est une méthode que tout template peut appeler.

terminal — blog/shell
cybertrain generate component comment comment   # le nom, puis ses attributs : un seul, appelé lui aussi comment
cybertrain generate helper comments

La première écrit app/components/comment_component.rb, avec un mot-clé par attribut, et son template ; la seconde écrit un CommentsHelper vide. Chacune écrit aussi un test, sur lequel revient l’étape 16. La classe est déjà ce qu’il faut au blog :

app/components/comment_component.rbruby
class CommentComponent < Cybertrain::Component
  def initialize(comment:)
    @comment = comment
  end
end

Remplacez le template généré par le balisage du commentaire, et donnez au helper son unique méthode :

app/components/comment_component.html.erberb
<div class="comment" id="<%= dom_id(comment) %>">
  <p><%= comment_author(comment) %> wrote:</p>

  <p><%= comment.body %></p>

  <%= button_to "Destroy comment", article_comment_path(comment.article_id, comment), method: :delete %>
</div>
app/helpers/comments_helper.rbruby
module CommentsHelper
  # Le nom de l’auteur du commentaire dans un <strong>, échappé : <%= comment_author(c) %>
  def comment_author(comment)
    name = case comment
           when Comment then comment.commenter.to_s
           else ""
           end
    Cybertrain::Html.tag("strong", { class: "comment-author" }, name)
  end
end

Rendez ensuite le composant là où la page rendait le partiel, et supprimez app/views/comments/_comment.html.erb :

app/views/articles/show.html.erb (extrait)erb
<% @article.comments.each do |comment| %>
  <%= render component: "comment", comment: comment %>
<% end %>
  • Le template voit les variables d’instance du composant comme des variables locales (comment) et ses méthodes publiques sans paramètre par leur nom. Il ne reçoit que le commentaire, pas le @article de la page : le chemin du bouton est donc construit à partir de comment.article_id.
  • dom_id(comment) vaut comment_7 pour le commentaire d’id 7 : c’est l’id d’élément que visent les diffusions de l’étape suivante.
  • Un composant est désigné comme l’est un partiel, par son nom en snake_case sans _component : les templates ne peuvent pas nommer de constantes.
  • Cybertrain::Html.tag échappe son contenu et renvoie une SafeString, qu’un template affiche telle quelle ; une simple String renvoyée par un helper est échappée.

Vous êtes ici :Exécution Turbo Streams sur Server-Sent Events

Des commentaires en direct avec Turbo

PourquoiUn commentaire posté dans un navigateur doit apparaître sur toutes les pages ouvertes de cet article, sans rechargement. Comme dans une application Rails 8, c’est le rôle de Turbo Streams, et il n’y a rien à installer ni à démarrer à côté du serveur.

Charger Turbo

cybertrain new a laissé les deux lignes en commentaire ; décommentez-les :

config/importmap.rbruby
pin "application"
pin "@hotwired/turbo", to: "https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.12/dist/turbo.es2017-esm.js"
app/javascript/application.jsjavascript
import "@hotwired/turbo"

Le javascript_importmap_tags du layout écrit l’import map et import "application" : chaque page exécute donc désormais Turbo (L’import map).

Le côté serveur de Turbo Streams est un sous-système : ajoutez sa ligne sous celle du cœur dans bin/blog.rb, et la même ligne dans bin/db.rb. Sans elle, spin run gen s’arrête au turbo_stream_from ci-dessous et nomme la ligne.

bin/blog.rb (extrait)ruby
require "cybertrain/core"
require "cybertrain/streams"

Abonner la page

Donnez un id à la liste et un autre au formulaire, et abonnez la page au flux de l’article :

app/views/articles/show.html.erb (extrait)erb
<h2>Comments</h2>

<%= turbo_stream_from @article %>

<div id="comments">
  <% @article.comments.each do |comment| %>
    <%= render component: "comment", comment: comment %>
  <% end %>
</div>

<h2>Add a comment:</h2>

<div id="comment_form">
  <%= render "comments/form", comment: @comment %>
</div>

Diffuser et répondre

create diffuse le commentaire enregistré, puis répond au navigateur qui l’a posté ; destroy dit aux autres pages de retirer l’élément :

app/controllers/comments_controller.rb (extrait)ruby
  def create
    @comment = Comment.new(comment_params)
    @comment.article_id = @article.id
    unless @comment.save
      flash[:alert] = "Comment could not be saved: #{@comment.errors.full_messages.join(", ")}"
      redirect_to article_path(@article), status: :see_other
      return
    end

    # Chaque page abonnée avec turbo_stream_from @article ajoute le commentaire à la fin de sa liste.
    Cybertrain::Stream.broadcast_append_to(@article, target: "comments",
                                           component: CommentComponent.new(comment: @comment))
    @new_comment = Comment.new   # le formulaire vide que create.turbo_stream.erb remet en place
    respond_to do |format|
      format.turbo_stream   # app/views/comments/create.turbo_stream.erb
      format.html do
        flash[:notice] = "Comment was successfully created."
        redirect_to article_path(@article), status: :see_other
      end
    end
  end

  def destroy
    @comment = @article.comments.find(params[:id])
    target = Cybertrain::Html.dom_id(@comment)   # lu avant que destroy n’efface l’id
    @comment.destroy
    Cybertrain::Stream.broadcast_remove_to(@article, target: target)
    flash[:notice] = "Comment was successfully destroyed."
    redirect_to article_path(@article), status: :see_other
  end
app/views/comments/create.turbo_stream.erberb
<%= turbo_stream.append "comments", html: render(component: "comment", comment: @comment) %>
<%= turbo_stream.update "comment_form", partial: "comments/form", locals: { comment: @new_comment } %>

Ouvrez un article dans deux fenêtres et postez un commentaire dans l’une : il apparaît dans les deux, et le formulaire qui l’a envoyé revient vide.

Ce qui se passe

  • turbo_stream_from @article écrit un élément <turbo-stream-source> pour le flux articles:<id>, avec un jeton signé. Turbo l’ouvre comme un EventSource sur /cybertrain/stream, que le serveur sert déjà.
  • Une diffusion est une ligne dans cybertrain_messages, une table que le framework crée lui-même. Chaque processus serveur l’interroge et remet la ligne aux pages qu’il tient ouvertes, en un dixième de seconde environ.
  • Turbo soumet le formulaire en demandant un Turbo Stream : format.turbo_stream rend donc create.turbo_stream.erb, sans layout. Un envoi de formulaire ordinaire, JavaScript désactivé, passe par format.html et est redirigé comme avant.
  • La fenêtre qui a posté reçoit le commentaire deux fois, dans la réponse et dans la diffusion, et ne l’affiche qu’une fois : Turbo remplace un élément qui a le même id.

Pour en savoir plus, notamment sur WebSocket et sur les flux pour votre propre JavaScript : Temps réel.

Turbo est ici récupéré depuis jsDelivr. Pour le servir vous-même, copiez turbo.es2017-esm.js dans vendor/javascript/ et épinglez-le avec to: "turbo.es2017-esm.js". Si vous activez la Content Security Policy que config/app.rb contient en commentaire, son script_src doit autoriser l’origine qui sert Turbo, quelle qu’elle soit (Content Security Policy).

Vous êtes ici :Vous écrivez app/jobs/

Un job d’arrière-plan

PourquoiUn travail qui ne doit pas retarder la réponse, une notification par exemple, s’exécute à part de la requête : il peut commencer avant que la réponse soit écrite, ou après. Comme avec Active Job sur Solid Queue, un job est une classe dans app/jobs/ et une ligne dans la base de données de l’application elle-même : aucun autre service.

terminal — blog/shell
cybertrain generate job notify_comment --retry StandardError:30:3

Elle écrit app/jobs/notify_comment_job.rb, avec la ligne retry_on que demandait l’option et un perform vide, ainsi qu’un test, et ajoute require "cybertrain/jobs" à bin/blog.rb et bin/db.rb. Complétez perform ; celui-ci se contente de journaliser, là où une vraie application enverrait un e-mail :

app/jobs/notify_comment_job.rbruby
class NotifyCommentJob < Cybertrain::Job::Base
  retry_on StandardError, wait: 30, attempts: 3

  def perform(args)
    comment_id = Cybertrain::Cast.int(args["comment_id"])
    article_id = Cybertrain::Cast.int(args["article_id"])
    Cybertrain.logger.info("new comment #{comment_id} on article #{article_id}")
    nil
  end
end

Mettez-le en file depuis create, une fois le commentaire enregistré :

app/controllers/comments_controller.rb (extrait)ruby
    NotifyCommentJob.perform_later("comment_id" => @comment.id, "article_id" => @article.id)
    # Chaque page abonnée avec turbo_stream_from @article ajoute le commentaire à la fin de sa liste.
    Cybertrain::Stream.broadcast_append_to(@article, target: "comments",
                                           component: CommentComponent.new(comment: @comment))

Postez un commentaire : le journal du serveur montre le job qui s’exécute, ici après la réponse (un thread de jobs peut aussi prendre la ligne avant que la réponse soit écrite, si bien que l’ordre des lignes peut varier), ses lignes marquées du job et de l’identifiant de la requête qui l’a mis en file :

sortie — cybertrain servertext
2026-11-14T09:30:00.120Z INFO [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] Started POST "/articles/1/comments" for 127.0.0.1
2026-11-14T09:30:00.122Z INFO [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] Completed 200 in 2ms
2026-11-14T09:30:00.950Z INFO [NotifyCommentJob 1] [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] new comment 1 on article 1
2026-11-14T09:30:00.951Z INFO [NotifyCommentJob 1] [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] job 1 (NotifyCommentJob) done
  • args est le Hash donné à perform_later, stocké en JSON et relu avec des clés String : passez des ids, pas des enregistrements, et restreignez les valeurs avec Cybertrain::Cast. perform_in(seconds, args) et perform_at(time, args) le mettent en file pour plus tard.
  • Les jobs sont des lignes de cybertrain_jobs, exécutées par trois threads de jobs du processus qui sert, ou d’un processus distinct lancé avec ./blog worker (Rôles des processus).
  • retry_on StandardError, wait: 30, attempts: 3 remet en file une exécution qui a échoué 30 secondes plus tard, trois tentatives en tout ; la ligne est ensuite failed et conservée (Nouvelles tentatives et abandons).
  • Un job peut s’exécuter plus d’une fois (quand un processus meurt au milieu d’un job, celui-ci est exécuté de nouveau) : écrivez donc perform de sorte qu’il puisse être répété sans risque.
  • Les jobs en échec se listent, se réessaient et s’abandonnent avec ./blog jobs, ou sur la page que monte la ligne jobs_page de config/routes.rb une fois décommentée (les routes des étapes 04 et 09 la gardent) (La page des jobs).

Vous êtes ici :Vous écrivez app/controllers/

Répondre en JSON

PourquoiUne même action peut servir la page et une API : respond_to, comme dans Rails.

app/controllers/articles_controller.rb (extrait)ruby
  def index
    @articles = Article.all.to_a
    respond_to do |format|
      format.html
      format.json { render json: @articles.map(&:as_json) }
    end
  end

  def show
    @comment = Comment.new
    respond_to do |format|
      format.html
      format.json { render json: @article.as_json }
    end
  end
terminal — blog/console
curl http://127.0.0.1:3000/articles.json
[{"id":1,"title":"Hello Rails","body":"I am on Rails! This is my first article.","created_at":"2026-11-12T10:22:45.852Z","updated_at":"2026-11-12T10:22:45.852Z"}]
  • Le format vient de l’extension (/articles.json) ou, sans extension, de l’en-tête Accept. Un format que l’action ne liste pas, comme /articles.xml, reçoit la réponse 406 Not Acceptable.
  • format.html sans bloc rend le template de l’action, comme avant.
  • as_json donne les colonnes de l’enregistrement, les dates et heures en ISO 8601, en UTC. JSON n’a pas de templates : une action y répond avec render json:.
  • Limitez le bloc à ses lignes format. : quand une requête se replie sur html, le bloc s’exécute une seconde fois.

/articles/1.json renvoie un seul article, grâce au même bloc dans show. Tout sur les formats : Formats et respond_to.

Vous êtes ici :Compilation cybertrain test

Tester

Pourquoiminitest et RSpec trouvent les tests par réflexion, ce qu’un compilateur anticipé ne peut pas faire. Les tests sont tout de même les classes de Rails : spin run gen les réécrit en un seul programme, que cybertrain test compile et exécute.

Ce que les générateurs ont écrit

Les scaffolds des étapes 03 et 08 ont écrit les tests de scaffold de Rails : test/fixtures/articles.yml et comments.yml (les lignes one et two par lesquelles commence chaque test), test/models/article_test.rb et comment_test.rb (« the fixture is valid »), et test/controllers/articles_controller_test.rb et comments_controller_test.rb (une requête par action). L’étape 12 a écrit test/components/comment_component_test.rb et test/helpers/comments_helper_test.rb, l’étape 14 test/jobs/notify_comment_job_test.rb, et cybertrain new a écrit test/test_helper.rb, que chaque fichier charge, et test/integration/health_test.rb, une requête vers /up. Trois d’entre eux doivent suivre le blog tel qu’il a grandi depuis.

Des fixtures qui passent les validations

Les valeurs d’exemple du scaffold (MyString, MyText) échouent aux vérifications de l’étape 05 : deux articles avec un même titre, et des corps de moins de dix caractères. Donnez aux articles de vraies valeurs :

test/fixtures/articles.ymlyaml
one:
  title: Hello Rails
  body: I am on Rails! This is my first article.

two:
  title: Second article
  body: Another article, with no comments.

Le test de création envoie le titre de la fixture elle-même, désormais pris ; donnez-lui-en un nouveau :

test/controllers/articles_controller_test.rb (extrait)ruby
  test "should create article" do
    assert_difference(-> { Article.count }, 1) do
      post articles_url, params: { article: { body: @article.body, title: "A new title" } }
    end

    assert_redirected_to article_url(Article.last)
  end

Les lignes de comments.yml appartiennent à article: one. Comme dans Rails, une fixture qui pointe vers un article empêche de supprimer cet article : « should destroy article » échoue donc sur la clé étrangère sauf si Article déclare has_many :comments, dependent: :destroy (l’encadré à la fin de l’étape 08). Ajoutez-le à app/models/article.rb si ce n’est pas fait, comme examples/blog :

app/models/article.rb (extrait)ruby
  has_many :comments, dependent: :destroy

Les commentaires sous leur article

Le test des commentaires du scaffold demande les routes que l’étape 09 a imbriquées sous les articles, dont les helpers sont désormais article_comments_path et article_comment_path. Remplacez-le :

test/controllers/comments_controller_test.rbruby
require "test_helper"

class CommentsControllerTest < ActionDispatch::IntegrationTest
  test "a comment is added to its article" do
    article = articles(:one)
    assert_difference(-> { Comment.count }, 1) do
      post article_comments_path(article), params: { comment: { commenter: "Dave", body: "First!" } }
    end
    assert_redirected_to article_path(article)
  end

  test "a comment queues its notification" do
    post article_comments_path(articles(:one)), params: { comment: { commenter: "Dave", body: "First!" } }
    assert_enqueued_with "NotifyCommentJob", { "comment_id" => Comment.last.id }
    assert_equal 1, perform_enqueued_jobs
  end

  test "a form Turbo submits is answered with a Turbo Stream" do
    post article_comments_path(articles(:one)), params: { comment: { commenter: "Dave", body: "First!" } },
                                               headers: { "Accept" => "text/vnd.turbo-stream.html, text/html" }
    assert_response :ok
    assert_turbo_stream action: "append", target: "comments"
  end

  test "a destroyed comment leaves its article" do
    comment = comments(:one)
    assert_difference(-> { Comment.count }, -1) do
      delete article_comment_path(comment.article_id, comment)
    end
    assert_redirected_to article_path(comment.article_id)
  end
end

Un test ne lance aucun thread de jobs, donc un job en file attend que le test l’exécute (perform_enqueued_jobs). La protection contre la falsification de requêtes est désactivée dans les tests, comme dans Rails, si bien qu’un post n’a pas besoin de jeton.

Le composant

Le test de l’étape 12 rend CommentComponent avec une String là où le gabarit attend désormais un commentaire. Rendez plutôt le commentaire de fixture :

test/components/comment_component_test.rbruby
require "test_helper"

class CommentComponentTest < ViewComponent::TestCase
  test "renders the comment with its author" do
    render_inline(CommentComponent.new(comment: comments(:one)))
    assert_select "div.comment strong.comment-author", text: "MyString"
  end
end

render_inline rend comme le fait une diffusion, sans requête, et assert_select lit ce qu’il a rendu. Les autres assertions : Tester une application, Tester les jobs et Tester les flux et les composants.

Lancer les tests

terminal — blog/shell
cybertrain test
cybertrain test test/controllers/comments_controller_test.rb
cybertrain test -n /comment/

La première exécution compile tous les tests en un seul programme, ce qui prend des minutes (les 149 tests d’examples/blog en ont pris environ neuf sur une machine cloud à 4 vCPU) ; une exécution sans changement ne recompile pas le programme de test : elle peut reconstruire gen une fois (build gen, quelques secondes), puis démarre en bien moins d’une seconde. Un fichier ou -n choisit quels tests s’exécutent, pas ce qui est compilé : modifier n’importe quel test recompile le programme. Chaque fichier affiche un titre, chaque test une ligne (ok, ou FAIL et ERR avec la ligne du test et le message), puis les totaux, avec entre eux ce que le code testé affiche lui-même (la ligne de sortie d’une commande, par exemple) ; le code de sortie vaut 1 quand un test a échoué. Mesuré le 2026-11-13, le blog du tutoriel compte à cette étape 17 tests et 25 assertions.

Avant chaque test, toutes les tables sont vidées et les fixtures insérées de nouveau, si bien que les tests ne dépendent pas les uns des autres. gen/tests.rb et gen/test/ sont générés : validez-les avec le reste de gen/.

Vous êtes ici :Vous écrivez app/, db/migrate/, config/routes.rb, test/

Ajouter la connexion

PourquoiJusqu’ici, n’importe qui peut modifier ou supprimer un article. Comme bin/rails generate authentication dans Rails 8, une seule commande ajoute la connexion par adresse e-mail et mot de passe, écrite comme du code qui appartient à l’application plutôt qu’installée comme un moteur.

terminal — blog/shell
cybertrain generate authentication
cybertrain db migrate    # crée les tables users et sessions

Il écrit les migrations et les modèles users et sessions, le concern Authentication, qu’il inclut dans ApplicationController, les contrôleurs et les vues de la connexion, de l’inscription, de la réinitialisation du mot de passe et de la page de compte, un mailer, la commande ./blog user, et des tests. Il ajoute aussi les routes, un partial sessions/_nav en haut du layout, et un réglage base_url dans config/app.rb, par lequel commencent les liens des courriels. Il ajoute enfin à bin/blog.rb et bin/db.rb les lignes des sous-systèmes que son code utilise : cybertrain/jobs (la page des jobs et le thread qui envoie les courriels), cybertrain/mailer, cybertrain/mailer/later (les courriels partent avec deliver_later) et cybertrain/rate_limit (les tentatives de connexion sont limitées, plus bas). Chaque fichier est listé dans Authentification.

app/controllers/concerns/authentication.rb (extrait)ruby
module Authentication
  extend ActiveSupport::Concern

  included do
    before_action :resume_session          # sets @current_user and @current_session
    before_action :require_authentication  # 303 to /session/new unless signed in
    helper_method :authenticated?
  end

Désormais, chaque action exige un utilisateur connecté, et un visiteur est redirigé vers /session/new. Rouvrez les pages que tout le monde peut lire, comme le fait le guide de Rails :

app/controllers/articles_controller.rb (extrait)ruby
class ArticlesController < ApplicationController
  allow_unauthenticated_access only: [:index, :show]
  before_action :set_article, only: [:show, :edit, :update, :destroy]

resume_session s’exécute toujours sur ces pages, donc les templates peuvent lire @current_user. Masquez ce qu’un visiteur ne peut pas utiliser :

app/views/articles/show.html.erb (extrait)erb
<% if @current_user %>
  <%= button_to "Destroy this article", article_path(@article), method: :delete %>
<% end %>

<% if @current_user %>
  <h2>Add a comment:</h2>

  <div id="comment_form">
    <%= render "comments/form", comment: @comment %>
  </div>
<% end %>

Le composant de commentaire garde son bouton « Destroy comment » pour tout le monde : une diffusion le rend une seule fois pour tous ceux qui regardent la page, sans requête et donc sans utilisateur courant. Un visiteur qui clique dessus est envoyé vers la page de connexion, puisque CommentsController n’ouvre aucune action ; les nouveaux commentaires atteignent tout de même la page d’un visiteur, car le flux n’est pas une action d’un contrôleur.

Démarrez le serveur et ouvrez http://127.0.0.1:3000/sign_up pour créer le premier utilisateur. Le générateur de Rails n’a pas de page d’inscription et laisse cela à la console ; CyberTrain écrit RegistrationsController, si bien que le premier utilisateur s’inscrit dans le navigateur. Pour une application sur invitation, lancez plutôt le générateur avec --invite-only : il n’y a pas de page d’inscription, et le premier utilisateur vient de ./blog user EMAIL ou d’une page /setup que seule la machine du serveur peut ouvrir (Inscription, ou sur invitation).

La page de connexion renvoie aussi vers une réinitialisation du mot de passe par courriel, et la navigation vers une page de compte ; le guide Authentification les décrit, avec le verrouillage, « rester connecté », --confirmable et les administrateurs. Un courriel de réinitialisation a besoin des réglages SMTP et, en production, de BLOG_BASE_URL (Liens dans les courriels).

Mettre à jour les tests

Tout test de l’étape 16 qui ouvre un formulaire, en soumet un ou atteint une action autre que index et show tombe désormais sur la page de connexion. Le générateur a écrit test/fixtures/users.yml (one et two, dont le mot de passe est "password") et test/support/session_test_helper.rb, dont test/test_helper.rb donne maintenant le sign_in_as à chaque test d’intégration, et il a ajouté la connexion au setup du test des articles (il affiche insert test/controllers/articles_controller_test.rb (sign_in_as users(:one))) ; vous trouverez donc :

test/controllers/articles_controller_test.rb (extrait)ruby
  setup do
    sign_in_as users(:one)
    @article = articles(:one)
  end

Le test des commentaires n’a pas de setup auquel le générateur puisse ajouter la connexion, et chaque action de CommentsController (create et destroy) demande maintenant un utilisateur connecté, donc chacun de ses quatre tests aussi ; donnez-lui-en un :

test/controllers/comments_controller_test.rb (extrait)ruby
class CommentsControllerTest < ActionDispatch::IntegrationTest
  setup do
    sign_in_as users(:one)
  end

Un scaffold généré désormais se connecte de lui-même.

Les propres tests du générateur (test/controllers/sessions_controller_test.rb, registrations_controller_test.rb, passwords_controller_test.rb, accounts_controller_test.rb, test/integration/remember_me_test.rb, lockout_test.rb, admin_test.rb, Tests) s’exécutent avec les autres sous cybertrain test, en déplaçant l’horloge avec travel_to pour vérifier le jour 15 et le jour 30. Les tentatives de connexion sont limitées comme dans le générateur de Rails : dix par adresse cliente toutes les trois minutes, comptées dans la base de données de l’application, si bien que tous les processus comptent ensemble ; derrière un reverse proxy, configurez les proxys de confiance. examples/blog fait cette étape avec --invite-only et réserve ses pages /admin aux administrateurs.

Vous êtes ici :Vous écrivez app/, db/migrate/, config/routes.rb, test/

Ajouter une image de couverture

PourquoiUn article peut porter une image. Même partage des rôles que pour la connexion : le framework analyse multipart/form-data et stocke les octets, et une seule commande écrit le reste comme du code qui appartient à l’application, à la place du has_one_attached d’Active Storage.

L’image sera affichée sur la page de l’article, que les visiteurs peuvent lire depuis l’étape 17 : son téléchargement doit donc leur être ouvert aussi. Avant de lancer le générateur, ajoutez :cover à la liste écrite à l’étape 17 :

app/controllers/articles_controller.rb (extrait)ruby
  allow_unauthenticated_access only: [:index, :show, :cover]
terminal — blog/shell
cybertrain generate attachment article cover   # pour un nouveau modèle : generate scaffold NAME field:type ... cover:attachment
cybertrain db migrate                          # ajoute les colonnes cover_* à articles

Elle écrit une migration qui ajoute cinq colonnes à articles (cover_key, cover_filename, cover_content_type, cover_byte_size, cover_checksum ; le fichier lui-même n’est pas dans SQLite) et un bloc dans Article avec cover_file=, cover_attached?, cover_url, une validation et des callbacks de sauvegarde et de suppression. Dans ArticlesController, elle ajoute une action cover derrière before_action :set_article et une ligne dans create et dans update :

app/controllers/articles_controller.rb (extrait)ruby
class ArticlesController < ApplicationController
  allow_unauthenticated_access only: [:index, :show, :cover]   # step 17 wrote [:index, :show]; you added :cover
  before_action :set_article, only: [:show, :edit, :update, :destroy, :cover]

  # GET /articles/1/cover -- @article comes from before_action :set_article, so
  # the download is scoped exactly like show (and authentication applies).
  # send_blob is the one way to serve uploads: it sets the type from what the
  # server detected, nosniff, a locked-down CSP and Content-Disposition
  # (inline for images only, a download otherwise).
  def cover
    if @article.cover_attached? && Cybertrain::BlobStore.exist?(@article.cover_key)
      send_blob(Cybertrain::BlobStore.read(@article.cover_key), filename: @article.cover_filename, content_type: @article.cover_content_type)
    else
      head 404
    end
  end
  # ...
  def create
    @article = Article.new(article_params)
    @article.cover_file = params.nested(:article).upload(:cover)
    if @article.save
  # ...
  def update
    @article.cover_file = params.nested(:article).upload(:cover)
    if @article.update(article_params)

Le téléchargement trouve son article par set_article, comme show : tout ce que set_article fait pour limiter les articles qu’un utilisateur peut voir limite donc aussi le téléchargement. Parmi les lignes qu’il affiche, le générateur émet un avertissement, parce que ce show a du code qui lui est propre :

sortie — cybertrain generate attachmenttext
warning: app/controllers/articles_controller.rb: def show has code of its own, which def cover does not run; if that code limits who may see articles, check the same in def cover

Ici, ce code construit un commentaire et choisit un format ; il ne refuse personne, il n’y a donc rien à recopier dans cover.

Le générateur ajoute aussi get "/articles/:id/cover" à config/routes.rb, multipart: true et un champ de fichier au formulaire, au-dessus du bouton d’envoi, et l’image à la page d’affichage, juste après le <h1> :

app/views/articles/_form.html.erb (extrait)erb
<%= form_with(model: article, multipart: true) do |f| %>
  <%# ... %>
  <div class="field">
    <%= f.label :cover %>
    <%= f.file_field :cover, accept: "image/png,image/jpeg,image/gif,image/webp" %>
  </div>
app/views/articles/show.html.erb (extrait)erb
<h1>Article</h1>
<% if @article.cover_attached? %><p><img src="<%= @article.cover_url %>" alt="<%= @article.cover_filename %>"></p><% end %>

Le générateur copie les règles d’accès de show sur le téléchargement, mais seulement celles qu’il peut lire : les callbacks. Un before_action autre que set_article qui liste :show sans la nouvelle action l’arrête avec cannot preserve show's authorization for :cover, et rien n’est écrit. Le code placé dans def show, il ne peut pas lire ce qu’il vérifie, d’où l’avertissement. Avec un show vide, il ajoute de lui-même :cover à allow_unauthenticated_access là où :show figure ; avec du code dans show, il ne touche pas à cette ligne, et sans :cover à cet endroit l’image exige une connexion.

Comment les fichiers sont servis

  • Types. Par défaut, seuls PNG, JPEG, GIF et WebP jusqu’à 2 Mo sont acceptés (COVER_TYPES et COVER_MAX_BYTES dans le modèle ; --any accepte tous les types). Le type est détecté d’après les premiers octets du fichier, jamais repris du navigateur.
  • Stockage. Les octets vont dans storage/uploads/<2 hex>/<32 hex key> (Cybertrain::BlobStore, mode 0600). Remplacer un fichier supprime l’ancien, et supprimer l’article supprime son fichier. Sauvegardez storage/uploads/ avec le fichier SQLite.
  • Service. Les fichiers sortent par send_blob dans le contrôleur, jamais depuis public/. Les quatre types d’image sont servis en ligne ; tout le reste est un téléchargement (application/octet-stream). Chaque réponse porte X-Content-Type-Options: nosniff et Content-Security-Policy: default-src 'none'; sandbox.
  • Paramètres. params.nested(:article).upload(:cover) est un Cybertrain::UploadedFile, ou nil si aucun fichier n’a été choisi. permit ne renvoie jamais de fichiers, donc un fichier ne peut arriver que par cette ligne explicite. Le jeton CSRF est lu dans les corps multipart comme dans ceux de n’importe quel formulaire. Un corps cassé ou trop gros donne une 400 ; max_upload_bytes et max_multipart_parts dans config/app.rb fixent les limites, et upload_root le répertoire.

Lancez le serveur, modifiez un article et choisissez une image. Le générateur a aussi écrit test/integration/article_cover_attachment_test.rb et l’image test/fixtures/files/cover.png, qui testent tout le parcours et se connectent d’abord, puisque l’application a maintenant un User. Comme :cover est public ici, il vérifie qu’un visiteur peut télécharger l’image, et il remplit le corps avec "A article.", allongé jusqu’au minimum de 10 caractères de l’étape 05.

Lancez cybertrain test comme à l’étape 16 (mesuré le 2026-11-13, le blog du tutoriel compte alors 83 tests et 870 assertions). examples/blog comporte aussi cette étape, et son JSON n’inclut pas les colonnes cover_* (Article#public_json). Pas encore pris en charge : plusieurs fichiers par champ, S3 ou un autre stockage distant, les variantes d’image, et l’envoi de gros corps en flux vers le disque (le corps entier est lu en mémoire, jusqu’à max_body_bytes).

Vous êtes ici :Exécution dist/blog

Compiler pour le déploiement

PourquoiUne seule commande compile l’application dans un dossier dist/ déployable, avec toutes les vues intégrées.

terminal — blog/shell
cybertrain build

Elle écrit dist/ : le binaire de l’application avec toutes les vues intégrées, plus les fichiers qu’il utilise, à côté de lui. Elle lance SPIN_DEBUG=1 spin run gen -- --embed-views, spin build blog et SPIN_DEBUG=1 spin run gen (qui remet en place le gen/views.rb versionné et vide, même après un échec ou un Ctrl-C), puis assemble :

  • dist/blogle framework compilé, les contrôleurs, les modèles et l’interpréteur de templates, avec toutes les vues intégrées
  • dist/public/ressources statiques et pages d’erreur, ou laissez un reverse proxy le servir
  • dist/storage/créé vide ; contient le fichier SQLite par défaut (une recompilation ne le vide jamais)
  • dist/tmp/créé vide (une recompilation ne le vide jamais)

Copiez dist/ sur une machine avec le même OS et le même CPU (le binaire est lié à la SQLite du système) et lancez-le là-bas. Un binaire compilé est en mode production par défaut (CYBERTRAIN_ENV permet de le changer). Définissez CYBERTRAIN_SECRET_KEY_BASE (cybertrain secret en affiche un aussi) ; à titre d’illustration :

terminal — hôte de productionshell
cd dist
export CYBERTRAIN_SECRET_KEY_BASE="$(openssl rand -hex 32)"
./blog migrate && ./blog

./blog migrate applique les migrations compilées dans le binaire, et ./blog db status affiche leur état ; PORT définit le port. Gardez le même secret d’un redémarrage à l’autre : le changer met fin à toutes les sessions. ./blog help liste les autres commandes du binaire, parmi lesquelles worker, jobs, console et db backup.

Cybertrain::Config lit d’abord l’environnement ; config/app.rb a le dernier mot. Les variables que rencontre un premier déploiement (la liste complète : Configuration) :

VariableAttributPar défaut
CYBERTRAIN_ENVenv"development" ; "production" dans un binaire issu de cybertrain build (aussi "test")
PORTport3000
CYBERTRAIN_DATABASEdatabase_pathstorage/#{env}.sqlite3
CYBERTRAIN_SECRET_KEY_BASEsecret_key_baserequis en production ; en dev/test, un secret est généré automatiquement dans tmp/secret_key
SPINEL_WORKERSworkers1
CYBERTRAIN_HOSThost"127.0.0.1" ; 0.0.0.0 écoute sur toutes les interfaces (conteneurs)
CYBERTRAIN_SESSION_SAME_SITEsession_same_site"Lax" ; aussi Strict ou None (None ajoute toujours Secure) ; toute autre valeur arrête le serveur au démarrage
CYBERTRAIN_SESSION_PARTITIONEDsession_partitionedfalse ; 1 ou true ajoute Partitioned (et Secure)
config/app.rbruby
# config/app.rb
Cybertrain.configure do |c|
  c.port = 3000
  c.workers = 1
end
  • Le serveur parle du HTTP/1.1 simple : placez nginx ou Caddy devant pour le TLS et HTTP/2. Le cookie de session est Secure en production, servez donc l’application en HTTPS (ne définissez c.session_secure = false dans config/app.rb que si la production est vraiment en http simple). Derrière un tel proxy, CYBERTRAIN_FORCE_SSL=1 redirige http vers https et CYBERTRAIN_HOSTS nomme les hôtes auxquels l’application répond (hôtes et force_ssl).
  • Le processus qui sert exécute aussi les jobs, les tâches planifiées et le poller des flux des étapes 13 et 14 : un seul processus constitue un déploiement complet. ./blog worker déplace les jobs dans un processus à part (Rôles des processus).
  • En production, l’application refuse de démarrer sans CYBERTRAIN_SECRET_KEY_BASE.
  • 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 ; cybertrain new écrit 404.html et 500.html.
  • SIGTERM cesse d’accepter des connexions, laisse se terminer les requêtes en cours et quitte quand elles sont terminées, ou après le drain_timeout du serveur (10 s).
  • La surveillance des fichiers, l’aperçu CRuby et la boucle de recompilation ne tournent jamais en production. Un cybertrain server en cours d’exécution ne régénère et ne redémarre rien tant que cybertrain build détient tmp/cybertrain-build.lock.

cybertrain new écrit aussi une configuration Kamal 2. Le Dockerfile 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, qui applique les migrations au démarrage puis écoute sur 0.0.0.0:3000. À côté se trouvent .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 monté en /app/storage) et .kamal/secrets, qui lit KAMAL_REGISTRY_PASSWORD et CYBERTRAIN_SECRET_KEY_BASE dans l’environnement. Renseignez les valeurs marquées CHANGE ME dans config/deploy.yml, committez, puis :

terminal — blog/shell
kamal setup    # la première fois : installe Docker et kamal-proxy sur le serveur, construit, pousse et démarre
kamal deploy   # chaque déploiement suivant

Le binaire est compilé dans l’image, son OS correspond donc toujours à celui de l’image ; réglez builder.arch dans config/deploy.yml sur le CPU du serveur. Déployez sur un seul serveur : la base de données est un fichier SQLite sur le volume de ce serveur. La partie 8 de docs/deploy.md (en japonais ; version anglaise : docs/deploy-kamal.md) détaille la procédure, sauvegardes comprises.

L’application terminée, examples/blog, embarque cette configuration avec une différence : elle se construit avec le framework du dépôt (path = "../.." dans son spin.toml), donc son Dockerfile exécute cybertrain setup et cybertrain build depuis le dépôt au lieu d’installer la gem, et le contexte de build est la racine du dépôt (builder.context: ../.., Dockerfile.dockerignore n’envoyant que le framework et l’application). La CI (blog-image.yml) construit cette image à chaque version publiée, vérifie le contrôle de santé, la création d’un article via le formulaire, l’arrêt propre et la base conservée sur son volume, et charge config/deploy.yml avec Kamal.

Comment ces pièces s’assemblent, et Kamal comparé à un serveur derrière Caddy, sont expliqués sur la page Déployer.

Bon à savoir

PourquoiDes limites et particularités à connaître avant qu’elles ne vous surprennent.

  • Les sessions ne contiennent que des String, dans un cookie chiffré.
  • SQLite uniquement, via la FFI de Spinel.
  • Pas de backtraces : les erreurs affichent la classe, le message, la ligne de requête et le nom/la ligne du template.
  • Un attribut mal orthographié dans une vue lève une erreur (undefined method 'titel' for Article) ; une colonne qui contient nil s’affiche vide.
  • Les associations viennent des clés étrangères ou de déclarations d’une ligne ; pas de has_many :through, d’includes imbriqué, d’enums, de STI ni d’associations polymorphes.
  • Pas de constraints ni de mount ; on répond en JSON avec render json: (il n’y a pas de templates JSON).
  • Dans un modèle généré par scaffold, seul le premier champ string reçoit une validation de présence par défaut.
  • Le générateur utilise un balayage lexical (des regex), pas un parseur, sur app/controllers, app/models, app/helpers, app/components et app/jobs.
  • Les jobs s’exécutent au moins une fois, et une diffusion n’atteint que les pages ouvertes au moment de son envoi, ou qui se reconnectent dans la minute.
  • Les vues sont intégrées à la compilation : une modification qui ne touche que les vues nécessite cybertrain build et un redémarrage avant d’atteindre la production.
  • Compilez dist/ sur le même OS et le même CPU que la machine qui l’exécute : le binaire est lié à la SQLite du système.
  • SPINEL_WORKERS vaut 1 par défaut.
  • Seule la version épinglée de Spinel (Cybertrain::SPINEL_TAG) est testée.
  • D’autres différences avec Rails, dans un seul tableau : Différences avec Rails.

Pour aller plus loin