dropbits Documentation

Install on server

Lean path: a PHP DocumentRoot that points at the kernel public/ folder, with one site tree and DROPBITS_SITE set for that vhost. Full recipe and flags: repository docs/DEPLOY.md.

What you need

  • PHP 8.2+ with pdo_sqlite and zip (Apache/mod_rewrite or equivalent front controller)
  • An install tree whose DocumentRoot is …/public (kernel front controller)
  • Per-site env: DROPBITS_SITE=<id>; for public hosts usually DROPBITS_LIVE=1 (via .htaccess SetEnv when HTACCESS_LIVE=1 in deploy)

First-time shape

  1. Place the kernel (dropbits/) on the host so public/index.php is the vhost root.
  2. Create sites/<id>/ (themes, data/, optional assets) — start from sites/minimal/ or Site directory layout.
  3. Register the site in the install registry (sites.production.json / install sites.json).
  4. Seed content once on the install (migrate + seed or restore) — not on every deploy.
  5. Set live knobs only when ready (live in registry, site_meta.live, HTACCESS_LIVE).

Routine updates after that: Content-owned deploy and Upgrade a deployed site — code + migrate; never re-upload site.db / uploads by default.

Same-host helper (operators)

On a developer host that already has the checkout and host-local ./deploy / scripts/install-site.sh:

cp dropbits/sites/_template/deploy.env.example dropbits/sites/<id>/deploy.env
# edit LOCAL_INSTALL_ROOT, HTACCESS_LIVE=1, CONTENT_OWNED=1
./deploy <id> --dry-run
./deploy <id>

Private customer trees stay out of tracked sites.json — use sites.local.json for dev overlays.

Fail-safe

If code is newer than the install schema, the site returns 503 upgrade_required until you run bin/site migrate on that install. That is intentional — run migrate after shipping code (Upgrade a deployed site).

See also