Configuration and environment variables
# config/app.rb
Cybertrain.configure do |c|
c.port = 3000
c.workers = 1
end
Cybertrain::Config reads the environment first; config/app.rb overrides:
| Variable | Attribute | Default |
|---|---|---|
CYBERTRAIN_ENV |
env |
"development"; "production" in a binary from cybertrain build (also "test") |
PORT |
port |
3000 |
CYBERTRAIN_DATABASE |
database_path |
storage/#{env}.sqlite3 |
CYBERTRAIN_SECRET_KEY_BASE |
secret_key_base |
required in production; dev/test auto-generate one into tmp/secret_key |
CYBERTRAIN_ENCRYPTION_KEY |
encryption_key |
""; 64 hex characters (cybertrain secret --hex), the key of the columns a model encrypts. Boot fails when it is malformed, or empty once a model declares encrypts (see Encrypted columns) |
CYBERTRAIN_ENCRYPTION_KEY_PREVIOUS |
encryption_keys_previous |
[]; comma-separated earlier keys, tried for decryption only, so a key can be rotated by saving the records again; a malformed entry stops the boot |
SPINEL_WORKERS |
workers |
1; the development server always serves with one and ignores this (why) |
CYBERTRAIN_HOST |
host |
"127.0.0.1"; 0.0.0.0 listens on every interface (containers) |
CYBERTRAIN_ALLOWED_HOSTS |
allowed_hosts |
Development accepts localhost, 127.0.0.1, [::1]; comma-separated exact hostnames extend this list (no scheme, port or wildcard). Other hosts get 403 before static files, sessions, routing or diagnostics. This is separate from the listening address; production and test apply this list only once CYBERTRAIN_HOSTS turns the check on there |
CYBERTRAIN_HOSTS |
hosts_from_env (appended to allowed_hosts) |
[]; comma-separated exact host names (an IPv6 address in brackets; no scheme, path, port or wildcard, or boot fails), appended after the loopback names in every environment. Set, they turn the host check on in production and test too: another Host answers 403 Blocked host and is logged. A GET or HEAD of the health path passes whatever the Host (see Hosts) |
CYBERTRAIN_FORCE_SSL |
force_ssl |
false; 1 or true redirects http to https (301 for GET and HEAD, 307 otherwise; by X-Forwarded-Proto behind a proxy), sends Strict-Transport-Security: max-age=63072000; includeSubDomains and writes every cookie Secure; the health path is never redirected. Anything but 1, true, 0, false or empty stops the boot. Behind a proxy, also set CYBERTRAIN_TRUSTED_PROXY or CYBERTRAIN_TRUSTED_PROXIES, or the URLs the app builds stay http |
CYBERTRAIN_SESSION_SAME_SITE |
session_same_site |
"Lax"; also Strict or None (None always adds Secure); anything else stops the server at boot |
CYBERTRAIN_SESSION_PARTITIONED |
session_partitioned |
false; 1 or true adds Partitioned (and Secure) |
CYBERTRAIN_TRUSTED_PROXY |
trusted_proxy |
false; 1 or true makes request.client_ip (what rate_limit counts) the last X-Forwarded-For address of a connection from loopback, for a reverse proxy on the same host (see Rate limiting); shorthand for CYBERTRAIN_TRUSTED_PROXIES=127.0.0.0/8,::1 |
CYBERTRAIN_TRUSTED_PROXIES |
trusted_proxies |
[]; comma-separated IPv4/IPv6 addresses or CIDRs (172.16.0.0/12,10.0.0.0/8) whose connections have request.client_ip taken from the last X-Forwarded-For address, for a proxy reached over a network, such as kamal-proxy in its container; a bad entry stops the server at boot |
CYBERTRAIN_MAX_PAGE |
max_page |
10000: the largest page params.page_number gives and Relation#page accepts (see Pagination); a value that is not a number of at most 18 digits, or below 1, is the default |
CYBERTRAIN_FILTER_PARAMETERS |
filter_parameters |
["password", "password_confirmation", "token", "secret", "secret_key_base", "session_key", "api_key", "authorization"]; comma-separated names replace the list. A parameter whose name contains one of them (ASCII case-insensitively: password also matches user[password]) has its value written as [FILTERED] in the request log and on the development error page; [] in config/app.rb turns this off |
CYBERTRAIN_LOG_LEVEL |
log_level |
:info: the least important level written, debug, info, warn, error, fatal or none (in any case; none turns the request log off and still writes error lines); anything else stops the boot (see Logs). cybertrain test uses :none unless config/app.rb sets it |
CYBERTRAIN_LOG_FORMAT |
log_format |
:text; json writes one JSON object per line, for a log collector; anything else stops the boot. cybertrain test keeps text lines unless config/app.rb sets it, whatever the variable says |
CYBERTRAIN_SENTRY_DSN |
sentry_dsn |
"": nothing is sent. A Sentry or GlitchTip DSN sends each error report there (see Error reporting); it needs require "cybertrain/error_reporter/sentry" (or require "cybertrain") in bin/<app>.rb, or the boot is refused. One that does not parse stops the boot, naming the part and never the key. cybertrain test empties it unless config/app.rb assigns it |
CYBERTRAIN_ERROR_SAMPLE_RATE |
error_sample_rate |
1.0: the share of error reports sent to Sentry, from 0.0 to 1.0, written as digits with an optional .digits; subscribers see every report; anything else stops the boot |
CYBERTRAIN_RELEASE |
release |
"": the version or commit sent with each error report |
CYBERTRAIN_WORKER |
worker |
true; 0 or false keeps a server process from running scheduled tasks, jobs and WebSocket feeds (see Process roles); ./<app> worker and feeds ignore it |
CYBERTRAIN_JOB_THREADS |
job_threads |
3: how many jobs one process runs at once (see Background work); at least 1 |
CYBERTRAIN_TIME_ZONE |
time_zone |
"UTC": the application's zone, an IANA name such as Asia/Tokyo, for Time.zone, the day and month boundaries, Date.current, l and time_tag (see Time zones); one the system's zoneinfo does not have stops the boot |
CYBERTRAIN_SCHEDULER_TZ |
scheduler_tz |
time_zone when unset: the zone a Scheduler.cron task without tz: is read in, an IANA name (see Time zones); one the system's zoneinfo does not have stops the boot |
CYBERTRAIN_JOBS_PAGE_PER_PAGE |
jobs_page_per_page |
50: rows per list on the jobs page; at least 1 |
CYBERTRAIN_CACHE_PRUNE_INTERVAL |
cache_prune_interval |
300: seconds between the prunes of expired cache rows, read when cybertrain/cache is required; at least 1 |
CYBERTRAIN_FEED_STATUS_INTERVAL |
feed_status_interval |
10: seconds between the writes of each WebSocket feed's status row (see Feed health); at least 1 |
CYBERTRAIN_FEED_RESTART_LIMIT |
feed_restart_limit |
10: restarts of one feed's thread within the window after which a feeds process exits with status 1 when it dies again (see Consuming WebSocket feeds); at least 1 |
CYBERTRAIN_FEED_RESTART_WINDOW |
feed_restart_window |
600: that window, in seconds; at least 1 |
CYBERTRAIN_STREAM_PATH |
stream_path |
"/cybertrain/stream": the realtime endpoint (see Realtime); an empty value turns streams off; it must start with / and differ from health_path |
CYBERTRAIN_REUSE_PORT |
reuse_port |
false; 1 or true binds with SO_REUSEPORT, so several processes can listen on one port and, on Linux, the kernel splits connections between them (ignored in development; see Running several processes). Run CYBERTRAIN_WORKER=0 on all but one |
CYBERTRAIN_HEALTH_PATH |
health_path |
"/up"; the built-in health check's path (see Operations); an empty value turns it off; one without a leading / stops the server at boot. health_worker_stale (300 s) is set in config/app.rb |
CYBERTRAIN_HEALTH_FEEDS |
health_feeds |
true: the health check also answers 503 feed stale for a WebSocket feed that stopped reporting or went silent (see Feed health); 0 or false turns that part off |
CYBERTRAIN_HEALTH_FEED_STALE |
health_feed_stale |
180: seconds of a feed's silence, or of its process not writing its status, before 503 feed stale; at least 1, and more than feed_status_interval while health_feeds is on (boot refuses it otherwise) |
CYBERTRAIN_HTTP_ALLOW_PRIVATE |
http_allow_private |
false; 1 or true lets Cybertrain::HttpClient connect to loopback, private and other non-public addresses (see Outbound HTTP) |
CYBERTRAIN_SMTP_HOST |
smtp_host |
""; the SMTP server Cybertrain::Mailer sends through (see Sending e-mail) |
CYBERTRAIN_SMTP_PORT |
smtp_port |
0: the mode's port, 587 for starttls, 465 for tls, 25 for none; anything but 1 to 65535 is 0 |
CYBERTRAIN_SMTP_USER |
smtp_user |
"": no AUTH; set, the mailer authenticates with AUTH PLAIN |
CYBERTRAIN_SMTP_PASSWORD |
smtp_password |
""; a secret, never logged, never in the boot banner or an error message |
CYBERTRAIN_SMTP_FROM |
smtp_from |
"": the sender Mailer.deliver uses when it is not given from: |
CYBERTRAIN_SMTP_TLS |
smtp_tls |
"starttls"; also tls (implicit TLS) or none (plain text, credentials to loopback only); both TLS modes need require "cybertrain/net/tls", which require "cybertrain" loads |
CYBERTRAIN_MAIL_DELIVERY_METHOD |
mail_delivery_method |
:test in the test environment, :smtp in every other: :test keeps each mail in Cybertrain::Mailer.deliveries instead of sending it (Testing mail); outside the test environment it boots with a warning and sends nothing; anything else stops the boot. cybertrain test uses :test unless config/app.rb sets it, whatever the variable says |
CYBERTRAIN_TEST_DATABASE |
— | "": the file cybertrain test deletes, migrates and runs the tests on, instead of storage/test.sqlite3; a file path (not :memory: or a file: URI). An existing file is deleted only when cybertrain test created it (it marks its databases), is this application's own storage/test.sqlite3 or is empty; any other, and the development or production database, is refused with exit status 2 and nothing deleted (Running the tests) |
CYBERTRAIN_I18N_DEFAULT_LOCALE |
i18n_default_locale |
:en: the locale every request starts in, a name such as ja or pt-BR (see Locales); anything else stops the boot |
CYBERTRAIN_AUTH_LOCKOUT_ATTEMPTS |
auth_lockout_attempts |
10: wrong passwords before an account is locked; 0 turns lockout off (see Authentication settings) |
CYBERTRAIN_AUTH_LOCKOUT_PERIOD |
auth_lockout_period |
3600: seconds a lockout lasts; at least 1 |
CYBERTRAIN_AUTH_REMEMBER_FOR |
auth_remember_for |
2592000 (30 days): seconds a "keep me signed in" sign-in lasts; at least 1 |
CYBERTRAIN_AUTH_IDLE_TIMEOUT |
auth_idle_timeout |
604800 (7 days): seconds without a request after which a sign-in ends; 0 turns it off |
Use None (with CYBERTRAIN_SESSION_PARTITIONED=1) only for an app shown
inside another site's frame; the browser must reach the app over HTTPS.
Other attributes with fixed, overridable defaults: views_root
("app/views"), public_root ("public"), layout
("layouts/application"), log_tags ([:request_id]: the request's tags
on each log line; :remote_ip adds the client's address, [] shows none,
and anything else stops the boot; see
Request ids), session_cookie_name,
session_max_age (2 weeks), session_secure (true in production, which
marks the session cookie Secure; false elsewhere, though SameSite=None
and Partitioned add Secure anyway), pool_size (4), static_files/csrf
(true), csrf_exempt_prefixes ([]: path prefixes such as "/api/" whose
non-GET requests skip the CSRF check, for an endpoint that programs call with
a credential of their own; each must start and end with / and not be /
alone, or boot fails; the prefix is matched on the path as sent, so a
percent-encoded spelling is still checked; no other route may match a path
under the prefix, and the exempt controller must not rely on the session
for authentication, since the session is still loaded there), max_body_bytes
(10 MiB: a longer request body, as sent, is answered 413 before it is read;
raise it for large uploads; a gzip body's inflated size is bounded separately
by request.decoded_body(limit)), max_render_depth (12 renders open at once: the page and its
partials; raise it for partials that legitimately recurse deeper; it must be
at least 1, or boot fails). Upgrade note: render nesting, unlimited before, is
now capped at 12 by default (the page is depth 1, so partials can nest 11
levels; the layout renders after the page and does not nest), and an app with
a deeper tree (threaded comments, a category menu) gets a template error until
it sets max_render_depth. File uploads: max_upload_bytes (5 MiB per
uploaded file; it must not exceed max_body_bytes), max_multipart_parts
(128 parts, text fields included, at most 4096), upload_root
("storage/uploads", where Cybertrain::BlobStore writes; created on the
first upload, not at boot).
Jobs and streams: besides the variables above, config/app.rb sets
scheduler_interval (1 s, the scheduler's tick), job_poll_interval (1 s,
how long an idle job thread waits; it was 5 before job threads),
job_max_attempts (5), job_heartbeat_interval (30 s),
job_heartbeat_stale (300 s, more than the interval),
job_drain_timeout (10 s, how long SIGTERM waits for running jobs) and
scheduler_lease_ttl (30 s, at least twice scheduler_interval), and the
stream settings stream_poll_ms, stream_retention,
stream_ping_interval, stream_max_connections, stream_max_message and
stream_max_backlog (Limits and settings).
A value out of range stops the boot with a message naming it.
Security headers: every response the server writes (actions, the
static-file middleware, error pages and the development diagnostics page,
the server's own 400/411/413/500, and HEAD) carries
X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN and
Permissions-Policy: camera=(), microphone=(), geolocation=(), unless
the response already sets a header of that name (any case): Response#to_http
adds them after the response's own headers and only when missing, so
response.set_header("X-Frame-Options", "DENY") in an action sends exactly
your value, once. c.permissions_policy replaces the third one's value
("camera=(), microphone=(), geolocation=(self)"), "" sends none, and a
CR or LF in it stops the boot. There is deliberately no Config
switch to turn the first two off app-wide; an embeddable widget overrides the header
on its own responses (a Content-Security-Policy: frame-ancestors ... header
takes precedence over X-Frame-Options in current browsers). Because of
nosniff, browsers take Content-Type literally: the static-file middleware
knows the usual public/ extensions (html, css, js/mjs, images including
webp and avif, fonts, wasm, pdf, audio and video, json, csv, xml), and
anything else is served as application/octet-stream, a download; add the
extension to Cybertrain::Static::EXTENSIONS if an app needs another one
inline. A reverse proxy that serves public/ itself bypasses these headers
(see docs/deploy.en.md). Cybertrain::Test::Client calls the
app in-process and never serializes the response, so it does not show these
defaults; assert them on response.to_http.
Content Security Policy: off by default, as in Rails; cybertrain new
writes the block below commented out in config/app.rb.
c.content_security_policy do |p| ... end declares the policy (one method
per directive, p.script_src :self, "https://cdn.jsdelivr.net"; a second
call adds to the same policy), c.content_security_policy_nonce_directives
([]) names the directives that get the request's nonce (a name that is not
a directive stops the boot), and c.content_security_policy_report_only
(false) sends the header as Content-Security-Policy-Report-Only. A
controller declares its own copy with content_security_policy do |p|; see
Content Security Policy.
Filtered parameters: the request log's Started GET "/login?..." line
and the development error page (its request line, and its dump of the
params and of a JSON body) show the value of every parameter named in
config.filter_parameters as [FILTERED], as Rails' filter_parameters
does, so a ?token= in a URL or a password posted to a form that fails
does not appear in the framework's request log or on the development
error page. Only the values are replaced: the rest of the
query string is logged as sent (control characters escaped). The list
matches by substring, case-insensitively; extend it in config/app.rb
(c.filter_parameters = c.filter_parameters + ["otp", "ssn"]) or replace
it with CYBERTRAIN_FILTER_PARAMETERS. Values an action logs itself are not
filtered; ask Cybertrain::ParameterFilter.filter?(name) or
ParameterFilter.filter_query(text) there.
Deployment: cybertrain build produces dist/: the binary dist/NAME
with the views embedded, dist/public/ (static assets, or let a reverse
proxy serve it), and dist/storage/ (the SQLite file by default) and
dist/tmp/. Run it from dist/ with CYBERTRAIN_SECRET_KEY_BASE set;
it is production unless CYBERTRAIN_ENV says otherwise, and ./NAME
migrate applies the migrations compiled into it. The binary
speaks plain HTTP/1.1 only; put nginx/Caddy in front for TLS and HTTP/2 (the
session cookie is Secure in production, so serve it over HTTPS). In
production an exception answers 500 and a bare error response (the router's
plain-text 404, head :not_found, render plain:) is replaced by
public/<status>.html when that file exists; errors an action renders as HTML
or JSON pass through. SIGTERM stops accepting, lets requests already in
flight finish (answered with Connection: close; idle keep-alive connections
are closed at once) and exits when they are done, or after the server's
drain_timeout (10 s). The watcher/rebuild loop never runs in production. docs/deploy.en.md
(in Japanese: docs/deploy.md) walks through it end to end: cybertrain new, an Ubuntu server,
systemd, Caddy with HTTPS, redeploys, rollbacks and backups.
Kamal: cybertrain new also writes what Kamal 2
needs: a Dockerfile that runs cybertrain setup and cybertrain build in an
Ubuntu build stage and copies dist/ into a slim stage of the same release
(migrate on boot, then serve on 0.0.0.0:3000), a .dockerignore,
config/deploy.yml (kamal-proxy with Let's Encrypt in front, the
health check on public/up.html, the SQLite file on a volume at
/app/storage) and .kamal/secrets (KAMAL_REGISTRY_PASSWORD and
CYBERTRAIN_SECRET_KEY_BASE from the environment). Fill in the values marked
CHANGE ME, commit, and kamal setup;
docs/deploy-kamal.md has the details (part 8 of
the deployment tutorial).
examples/blog carries the same setup,
built against this checkout's framework.
Application settings
An application's own settings (a public base URL, a feature switch, an
interval, an SMTP host) are declared on the same Config, with a type, an
environment variable and a default:
# 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)
Each value is read once, when config/app.rb runs at startup. An empty or
unset variable means the default. A boolean takes 1/true or
0/false; an integer takes decimal digits (an optional leading -) within
min..max (both optional). Any other value falls back to the default and
logs a WARN line saying so (a text line, whatever log_format says:
config/app.rb is still running). Reading an undeclared name, or one declared
with another type, raises ArgumentError, as does declaring a name twice.
Tests change a value with set_string_setting, set_int_setting and
set_bool_setting. ./NAME help lists every declared setting with its
variable and default, and the boot banner prints the current values
(=> Settings: base_url="" worker=true ...); a secret: true setting shows
up in both only by name, as [FILTERED]. There is no
Cybertrain.config.base_url accessor: Spinel has no define_method, so the
readers are typed methods that take the name.
Locales
# config/app.rb
Cybertrain.configure do |c|
c.i18n_default_locale = :en # or CYBERTRAIN_I18N_DEFAULT_LOCALE
c.i18n_available_locales = [:en, :ja]
c.i18n_raise_on_missing = true if c.test?
end
i18n_available_locales ([], the default locale alone) lists the
locales I18n.locale= and I18n.locale_available? accept; boot refuses an
entry that is not a locale name, and a default that is not in a non-empty
list. i18n_raise_on_missing (false) makes a missing translation raise
I18n::MissingTranslationData instead of answering a marker (development
and test) or the humanised key (production). The dictionaries and the
locale per request are in Internationalization.
Authentication settings
The code cybertrain generate authentication writes reads four settings
(the variables are in the table above): auth_lockout_attempts (10) and
auth_lockout_period (3600 s) for lockout,
auth_remember_for (30 days) for a "keep me signed in" sign-in, and
auth_idle_timeout (7 days) for an unused one
(Remember me); an
unremembered sign-in lasts session_absolute_max_age (two weeks). A value
out of range stops the boot. The generator also declares the application
setting base_url, from <APP>_BASE_URL, where links in mails start; set
it, with https, wherever the application is served
(Links in mails).
Time zones
Spinel ships no tz database, and setting ENV["TZ"] to convert a time
changes it for every thread of the process. Cybertrain::TimeZone reads the
system's zone files instead: /usr/share/zoneinfo/<name>, or $TZDIR/<name>
when TZDIR is set (install the tzdata package in a slim container image).
It parses TZif versions 1 to 4 (RFC 8536), including the POSIX TZ rule a
"slim" file relies on after its last transition, and caches each zone for the
life of the process (copy-on-write, so lookups from several workers take no
lock).
Everything is Integer epoch seconds. A local epoch is a wall-clock reading
counted as if it were UTC, so wall-clock arithmetic is plain addition and
TimeZone.civil_to_epoch / TimeZone.epoch_to_civil move between it and
[year, month, day, hour, minute, second]:
tokyo = Cybertrain::TimeZone.find("Asia/Tokyo")
tokyo.found? # false for an unknown name: the zone then behaves as UTC
tokyo.utc_offset_at(Time.now.to_i) # => 32400
tokyo.abbreviation_at(Time.now.to_i) # => "JST"
# The next 09:00 in 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
At a daylight-saving transition local_to_utc is deterministic: a wall time
that a forward jump skips (02:30 on a US spring-forward day) is read with the
offset before the jump, so it lands after it (03:30 EDT); a wall time that a
backward jump repeats gives the earlier instant. find accepts only a
relative name made of A-Za-z0-9_+-./ with no empty, . or .. segment, so
a zone name taken from a user's profile cannot reach a file outside the zone
directory; an unknown or malformed zone is not cached, and "UTC" needs no
file.
The application's zone
# config/app.rb
Cybertrain.configure do |c|
c.time_zone = "Asia/Tokyo" # or CYBERTRAIN_TIME_ZONE; "UTC" by default
end
c.time_zone takes an IANA name (Rails' own names, such as "Tokyo", are not
read), and boot stops on one the system does not have. Values stay UTC
instants: a column, Time.current and the calendar methods answer a UTC
Time, and time.hour is the UTC hour. The zone decides the calendar
(beginning_of_day and its kin, Date.current;
Times and the time zone) and the
display: l(time) and time_tag(time) show a Time in it, %z and %Z
included, and time_tag's datetime is ISO 8601 with the zone's offset
(2026-11-12T05:00:00+09:00). l(time, zone: "America/New_York") and
time_tag(time, zone: "...") show one value in another zone. A Time at
offset 0, which is every Time the framework hands out, is shown in the
zone; a Time that carries another offset of its own
(time.getlocal("+05:30")) keeps it unless zone: is given; a Date is
shown as it is. Cron tasks without tz: follow the zone too, unless scheduler_tz is set. A
registered command (Main.command), ./<app> jobs and ./<app> console
install the zone before they run as well, and refuse an unknown one as boot
does, with error: time_zone "Mars/Base" is not a known time zone and exit
status 1, before the database is opened. In cybertrain test every test
starts in the configured zone. (Dates and times has l's
formats.)