Installing

Nibble is installed by cloning it. There is no gem to add and no package to install: the repository is the application. That sounds unusual, and it has one large consequence — upgrades arrive as releases you merge into your own repository, which is covered in Upgrading.

Plan for about ten minutes, most of it spent downloading dependencies.

What your machine needs

Tool	Why
git	the code, and how upgrades arrive
Ruby	the application
Node and npm	the asset build, and server-side rendering
SQLite	the database — it also holds the cache and the job queue
libvips	resizing images
ffmpeg	thumbnails for video

You do not have to install these one by one and guess versions. Ruby and Node are pinned in mise.toml, and mise installs exactly those with mise install.

If something is missing, the installer stops before doing anything and names everything that is missing at once, with the command that installs it on your operating system. It will never get halfway and leave you with a broken directory.

There is no separate database server to set up, no Redis, and no search service. SQLite holds all of it.

Running the installer

./install.sh my-site

my-site is the directory it creates. The installer then:

1. Checks the tools above.
2. Clones Nibble into my-site.
3. Installs the gems and npm packages — this is the slow part.
4. Hands over to bin/rails nibble:install, which asks you the questions below.

The questions

Each one has a sensible default in brackets; pressing Enter takes it.

Application name. Used to name the containers, image and volume when you deploy. Lowercase, no spaces — acme-site rather than Acme Site.

Public site URL. Where the site will live, such as https://example.com. This is not cosmetic: canonical URLs, the sitemap, robots.txt and links in emails are all built from it. In production it must be https.

Theme handle. Which theme the site uses. crumbs ships with Nibble, so take it now and build your own later.

Whether you deploy with Kamal. Say yes and it asks for your hosts, registry user and SSH user, and writes config/deploy.yml and config/deploy.staging.yml for you. Say no and nothing is lost — add them whenever you are ready with bin/rails nibble:install --only=deploy.

An administrator. A name, an email address and a password. This one is not optional: a site with no administrator has no way in. The password must be at least 12 characters and contain a lowercase letter, an uppercase letter, a number and a symbol. The same rule applies everywhere a password is set later.

Whether to import the theme’s example content. The theme can ship a few pages and posts so the site is not an empty shell while you find your feet. Decline it for a site that is going straight into real use.

What it writes

File	What it is	Commit it?
config/nibble.yml	how your site behaves	yes
.env	secrets and addresses for this machine	no — it is already ignored
config/credentials.yml.enc	encrypted secrets	yes
config/master.key	the key that decrypts them	no — keep a copy somewhere safe
.nibble/install.yml	which release this site was installed from	yes
config/deploy*.yml	Kamal deploy files, if you asked for them	yes

Everything it wrote is yours from that moment. Nibble generates these once and never writes them again, so you can edit them freely without an upgrade fighting you.

Checking it worked

bin/rails nibble:check

This reads your schema, your theme, the roles and the settings, and reports anything wrong — a blueprint that names a field type that does not exist, a collection pointing at a template the theme does not have, a missing setting. A clean site prints one line:

nibble:check passed (20 schema files)

Then start it:

bin/dev

• The site: http://localhost:3100
• The control panel: http://localhost:3100/admin

Sign in with the administrator you just created.

If something goes wrong

The installer says a tool is missing. Install everything it lists, then run it again — it refuses to start in a directory that already exists, so either delete my-site or pass a different name.

bin/dev starts but the site is blank or unstyled. The asset build is probably still running; give it a few seconds on the first boot.

The control panel says the password is wrong. Passwords are case-sensitive and must meet the rules above. You can always make another administrator with bin/rails nibble:admin:create.

Something else. bin/rails nibble:check first — it explains most misconfigurations in plain language.

Next steps

• Settings — everything you can change about how the site behaves.
• Users and roles — let other people in.
• Building a theme — make it look like your site rather than ours.
• Deployment — put it on a server.