Installing plugins

There are two ways a plugin reaches a running Railbase:

1. Marketplace (recommended). Browse, buy or trial, and install plugins from railbase.app without leaving your admin — the marketplace is built in and always available. This is the path most operators use.
2. Self-hosted build. If you compile your own binary, you can register a plugin's Go module at build time instead — handy for development or a fully self-contained build you control.

Most people want the marketplace — skip to The marketplace. The build-time method is documented first, for self-compilers.

Add a plugin to a self-hosted build

A first-party plugin is a Go module (e.g. github.com/railbase/railbase-cms) that exposes a Register(app) entry point. Installing it is three steps.

1. Add the dependency. Pre-release, pin it to your local checkout in go.mod (same reason railbase/vault are pinned — see Project setup):

replace github.com/railbase/railbase-cms => /path/to/plugins/railbase-cms

2. Register it in your cmd/<app>/main.go, inside the ExecuteWith callback:

import cms "github.com/railbase/railbase-cms"

cli.ExecuteWith(func(app *railbase.App) {
    if err := cms.Register(app); err != nil { // installs the plugin
        panic(err)
    }
})

Register registers the plugin's collections with the schema registry (so the core auto-generates CRUD at /api/collections/<prefix>_*) and mounts its custom verbs (for CMS, under /api/cms/*).

3. Migrate. The plugin's collections are now part of your schema, so generate and apply a vault-schema migration, then run:

go build ./cmd/myapp
./myapp migrate diff install_cms
./myapp migrate up
./myapp serve

The plugin's collections and routes are live. For CMS, /api/collections/cms_posts, /api/collections/cms_categories, … respond immediately, and /api/cms/_health returns {"plugin":"cms","status":"ok"}. See the CMS plugin.

Frontend: the plugin's user-facing pages

A marketplace install (or Register(app) for an embedder) wires the backend (collections + verbs). The plugin's user-facing screens ship with it, automatically: they live inside the plugin bundle as a declarative widget descriptor (widgets.json — pages + widgets bound to the plugin's own verbs), and the core's site shell mounts them at /<slug> on the site SPA (/), never the admin panel. There is no codegen, no rebuild, and no wizard — one marketplace action delivers backend, schema and UI together (ADR-002, invariant 7).

On install the plugin's pages appear at clean /<slug> URLs — public pages open, app-user pages behind the site's sign-in gate — with collision/reserved-prefix checks at install and only license-enabled plugins' UIs served. The CMS plugin, for example, comes up at /blog, /blog/:slug, /videos, … with no rebuild.

The marketplace

The marketplace is built in and always on. Open Marketplace in your Railbase admin and you're browsing the live catalogue from railbase.app — every plugin, its price, and its licensing terms. There's nothing to switch on and no address to configure; your binary already knows where to look, and it only ever pulls from railbase.app.

From the catalogue, getting a plugin is one continuous flow — you never leave Railbase:

1. Pick a plugin and review its price and licensing terms — pricing varies by plugin (per-seat is the default, but some are flat per-company, per-host, or usage-based).
2. Buy, or try it free.
   • Buy — payment is embedded in the page: you choose Individual or Business (a business adds its legal name and, optionally, a VAT/tax ID for reverse charge), any applicable tax is shown before you pay, and you enter your card in a secure form served by railbase.app. Your server is never a card processor and stores no card data.
   • Try free — where a plugin offers a trial, this starts a time-boxed trial (one per plugin) that installs right away and needs no card. Buy any time before it ends to keep it running.
3. Install. On a successful purchase or trial, your instance pulls the plugin, verifies it's authentic and unmodified before it runs, and brings it online.

Update

When a newer version is available the Marketplace shows it. Updating stops the running version and installs the new one — reusing your existing license, so there's no second checkout. Core and plugin updates and the compatibility rules are covered in Updating. (For a build-time install, you update by bumping the dependency and rebuilding.)

Stop, uninstall, purge

For marketplace-managed plugins, Railbase's plugin manager exposes three distinct "turn it off" actions — they are not the same:

Action	What it does	Your data
Stop	Disables the plugin (its code stays encrypted at rest, no longer decrypted/run)	Untouched; re-enable anytime
Uninstall	Backs up, then disables the plugin	Left dormant — reinstall restores it
Purge	Permanently removes the plugin's collections	Deleted (backup taken first)

Where licenses are enforced

A marketplace plugin only runs while it holds a valid license. On a release build, a paid plugin installs only with a valid license — without one it lands dormant (inert) rather than running unpaid, and activates the moment a valid license binds. Your instance re-checks each bound license against railbase.app on a heartbeat, so a renewal flows in with no action from you. If a license lapses past its grace window — or a payment is refunded or charged back, which revokes immediately — the plugin goes dormant: its code is no longer decrypted or run and its data is preserved, exactly like a manual Stop, until the license is restored. Renew or reinstate before the grace window closes to avoid the interruption — see Licensing & seats. To change seats or cancel, use Managing billing.