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>; php playground/bin/deploy writes public/.htaccess (rewrite to index.php + SetEnv DROPBITS_SITE). DROPBITS_LIVE=1 only when HTACCESS_LIVE=1.

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. Turn live on only when this vhost should run live guards — 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

From a clone with playground/ beside dropbits/:

# hub form, or:
cp dropbits/sites/_template/deploy.env.example deployable/<id>/deploy.env
# edit LOCAL_INSTALL_ROOT and/or DEPLOY_HOST / FTP_*
php playground/bin/deploy <id> --dry-run
php playground/bin/deploy <id>

Staging smoke is /install/<id>/ on php playground/bin/serve. Nginx wildcard <id>-install.localhost is a maintainer shortcut, not required.

Private customer trees stay out of tracked sites.json — optional sites.local.json overlay only.

Live

Live means don't nuke or import-rewrite this public copy, not read-only. Widgets, pages, nav, and media still edit.

Two knobs, that's all. The process is live when install sites.json has "live": true or DROPBITS_LIVE=1 (env or Apache SetEnv). Either is enough. Resolved once in SiteContext::resolve(). Hub → Site → “Live site” (site_meta.live) is not read. deploy.env present is not live.

CopyLive?
Hub / playground / php -S checkoutNo — discovered sites default live: false
sites/minimalNo
php playground/bin/deploy installYes unless HTACCESS_LIVE=0 (default is 1)
Laptop deployable/No

On live: apply_recipe and import_site denied; migration-only tools denied; pending migrations → 503 upgrade_required until bin/site migrate; default admin password refused; log mailer refused. ZIP backup/restore stays allowed.

Deploy writes the two knobs when HTACCESS_LIVE=1. Recipe: DEPLOY.md.

See also