Settings

Nibble reads settings from three places, and each is for a different kind of thing. Getting this split right is most of what keeps a site easy to run.

Where	For	Goes in git?
config/nibble.yml	how the site behaves: theme, URL, locales, upload rules	yes — it is yours
Environment and credentials	secrets, and addresses that differ per machine	.env no, credentials yes
The control panel	what a person changes without a deploy	it lives in the database

The rule of thumb: if changing it should be reviewed, it belongs in a file. If it is a password, it belongs in the environment. If a colleague should be able to change it on a Tuesday afternoon, it belongs in the control panel.

config/nibble.yml

Written once at install and yours from then on. It holds only what you have set — everything else has a default in code, so the file stays short, and what is in it is what you are choosing to maintain.

default: &default
  load_defaults: "0.7.0"
  theme: crumbs
  url: https://example.com
  locales:
    - code: en
      default: true
      url_prefix: ""

production:
  <<: *default

That default: &default / <<: *default pair is ordinary YAML for “production is the same as the defaults”. Give an environment its own block when it genuinely differs.

What you can set

Key	What it does
load_defaults	which release’s behaviour you have opted into — see below
theme	the active theme’s handle, matching a directory under themes/
url	the public site URL; canonical links, sitemaps and mail all come from it
locales	the languages the site is in, and their URL prefixes
disable	features to switch off entirely
reserved_paths	paths content may never claim
trash.retention_days	how long trashed content is kept before it is really gone
assets.max_upload_mb	the largest file anyone may upload
assets.additional_extensions	file types beyond the ones allowed by default
assets.presets	named image sizes your theme asks for
outbound.allowed_hosts	the only hosts Nibble may call out to
outbound.secrets	names of secrets those calls may use
outbound.config	settings for those calls

load_defaults, and why it exists

A release never changes how your site behaves on its own. When a release introduces behaviour that would change something you can see, that behaviour stays off until you raise load_defaults to that version.

So upgrading is two decisions, not one: take the new code today, and turn on its new behaviour when you have read what it changes and have a moment to look. Raise it one release at a time and run the site after each.

reserved_paths is a floor

Whatever you list is added to Nibble’s own reserved paths, not substituted for them. You cannot free up /admin by leaving it out, because a site whose control panel is shadowed by a page cannot be fixed from inside.

Image presets

A preset is a named size your theme asks for by name, so the size lives in one place rather than being repeated through your templates:

assets:
  presets:
    og:
      w: 1200
      h: 630
      fit: crop
    content:
      w: 1440
      srcset: [640, 960, 1440]

The theme then asks for og or content and gets the right file. See Assets.

Environment and credentials

Secrets and per-machine addresses. In development these live in .env, which is never committed; in production they are real environment variables, and the sensitive ones come from encrypted credentials.

Variable	Purpose
SITE_URL	public site URL (development defaults to http://localhost:3100)
NIBBLE_THEME	the active theme, if you would rather not set it in config/nibble.yml
NIBBLE_BLOCK_INDEXING	any value disallows crawling, adds noindex and leaves analytics off
SMTP_ADDRESS, SMTP_PORT	outgoing mail; the username and password come from credentials
AWS_REGION, AWS_BUCKET_NAME	S3 storage for uploads
DB_SNAPSHOT_BUCKET, DB_SNAPSHOT_REGION	where the nightly backup is uploaded
BASIC_AUTH_USER, BASIC_AUTH_PASSWORD	the password wall in front of staging
INERTIA_SSR_PORT	the port server-side rendering listens on, if the default clashes
NIBBLE_SECRET_<NAME>	one per name listed in outbound.secrets

Set secrets with bin/rails credentials:edit, which opens the encrypted file in your editor.

In the control panel

Some settings are nobody’s business but the people using the site day to day, and asking for a deploy to change them would be absurd. Those live in the control panel:

• Integrations (a global): CAPTCHA keys, the address mail is sent from, analytics IDs.
• Updates: whether Nibble checks for new releases at all.

They are stored in the database and take effect immediately.

Settings are checked before the site serves

In production and staging, a missing or wrong setting stops the boot and names every problem at once rather than failing later on some unlucky request. It catches a missing SITE_URL, a URL that is not https, credentials that will not decrypt, S3 configured without a bucket, a theme that is named but absent.

A console and a migration still start, deliberately — otherwise a broken setting could not be fixed on the machine it is broken on.

You can ask for the same report at any time:

bin/rails nibble:check

Run it before you deploy and you will rarely be surprised after.