bzl

self-hosted ephemeral community engine
Log | Files | Refs | README | LICENSE

SELF_HOSTED_INSTALLER_PLAN.md (5097B)

      1 # Bzl Self-Hosted Installer Plan
      2 
      3 ## Goal
      4 Turn Bzl into a replicable self-hosted package that a non-technical community admin can install and run with minimal setup.
      5 
      6 Target outcome:
      7 - Download one installer.
      8 - Enter a small set of config values.
      9 - Receive a working public URL backed by Cloudflare Tunnel.
     10 - Keep the server running automatically on reboot.
     11 
     12 ## Product Scope
     13 This version is intentionally scoped for small private communities:
     14 - Single host machine runs the server.
     15 - Host controls moderation and invites.
     16 - Persistence is local to the host.
     17 - Scaling beyond one host is not part of this phase.
     18 
     19 ## Ideal Operator Experience
     20 The install path should look like this for a new host:
     21 1. Download `Bzl-Setup` for their OS.
     22 2. Open installer and choose install location.
     23 3. Complete first-run wizard prompts:
     24    - Domain (example: `azakaela.com`)
     25    - Subdomain (example: `bzl`)
     26    - Cloudflare API token
     27    - Registration code
     28    - Initial admin username/password
     29    - App port (default `3000`)
     30 4. Click "Launch".
     31 5. Installer validates health and displays final URL.
     32 6. Host shares URL with their community.
     33 
     34 No manual DNS records, tunnel config edits, or service setup should be required in normal flow.
     35 
     36 ## Core Components To Build
     37 ### 1) Bootstrap CLI (`bzl-init`)
     38 Purpose: single command that performs all setup work.
     39 
     40 Responsibilities:
     41 - Validate prerequisites.
     42 - Create `.env` from template.
     43 - Create/update Cloudflare named tunnel.
     44 - Route hostname to tunnel.
     45 - Write `cloudflared` config.
     46 - Configure app and tunnel startup services.
     47 - Run health checks and print diagnostics.
     48 
     49 ### 2) Installer Wrapper
     50 Purpose: GUI around `bzl-init` for non-CLI users.
     51 
     52 Responsibilities:
     53 - Collect wizard inputs.
     54 - Run `bzl-init` with progress display.
     55 - Surface actionable errors (token permission, DNS, port in use).
     56 - Provide "Repair" and "Update" modes.
     57 
     58 ### 3) Service Runtime
     59 Purpose: keep Bzl online reliably.
     60 
     61 Responsibilities:
     62 - Auto-start app and tunnel on reboot.
     63 - Restart on crash.
     64 - Persist logs for debugging.
     65 
     66 ## Moderation Prerequisites (Before Wide Release)
     67 These need to exist before presenting Bzl as install-and-run for other communities.
     68 
     69 Required:
     70 - Report content (posts and chat messages).
     71 - Moderator role with ability to:
     72   - Remove posts
     73   - Remove chat messages
     74   - Suspend/ban users
     75 - Basic moderation log (who took action, when, what target).
     76 - Rate limiting and abuse protections:
     77   - Account creation rate limit
     78   - Post/chat spam throttle
     79   - Failed auth throttling
     80 
     81 Strongly recommended:
     82 - Optional invite-only mode.
     83 - Profanity and unsafe content filter hooks.
     84 - Temporary mute and timed bans.
     85 
     86 ## Phased Roadmap
     87 ## Phase 0: Hardening Current App
     88 - Finalize environment variable model.
     89 - Add stable config file templates.
     90 - Add startup validation checks and clearer error messages.
     91 - Improve backup/restore for local data.
     92 
     93 ## Phase 1: Moderation MVP
     94 - Ship moderator role + moderation actions.
     95 - Add report flow in UI.
     96 - Add moderation event log.
     97 - Add basic rate limiting.
     98 
     99 Release gate: no public installer until this phase is complete.
    100 
    101 ## Phase 2: CLI Installer (`bzl-init`)
    102 - Build interactive setup prompts.
    103 - Integrate Cloudflare API flow.
    104 - Generate tunnel + DNS + local config.
    105 - Add health checks and recovery hints.
    106 
    107 Release gate: repeatable setup on clean machines.
    108 
    109 ## Phase 3: GUI Installer
    110 - Wrap CLI in desktop installer UX.
    111 - Add guided setup, progress, and repair mode.
    112 - Add one-click launch and URL copy actions.
    113 
    114 Release gate: first user can complete setup without terminal usage.
    115 
    116 ## Phase 4: Operations and Updates
    117 - Versioned releases and upgrade path.
    118 - Auto-update or guided update utility.
    119 - Document rollback path.
    120 
    121 ## Config Inputs (Installer Wizard)
    122 Keep this list short and stable:
    123 - `DOMAIN`
    124 - `SUBDOMAIN`
    125 - `CF_API_TOKEN`
    126 - `PORT` (default `3000`)
    127 - `REGISTRATION_CODE`
    128 - `ADMIN_USERNAME`
    129 - `ADMIN_PASSWORD`
    130 
    131 Derived values should be generated automatically.
    132 
    133 ## Cloudflare Requirements
    134 Token must support:
    135 - Tunnel management
    136 - DNS record management for selected zone
    137 
    138 Installer should verify permissions before attempting setup and return a clear error when insufficient.
    139 
    140 ## Risks and Mitigations
    141 - Risk: API token mis-scoped.
    142   - Mitigation: preflight permission check before writes.
    143 - Risk: Local port already in use.
    144   - Mitigation: install-time port probe and alternative prompt.
    145 - Risk: stale DNS/tunnel mapping.
    146   - Mitigation: idempotent reconcile flow in repair mode.
    147 - Risk: weak moderation leads to abuse.
    148   - Mitigation: moderation MVP as release gate.
    149 
    150 ## Definition of Done for "Replicable"
    151 Bzl is considered replicable when:
    152 - New host can install from scratch in under 15 minutes.
    153 - No manual edits are required post-install.
    154 - Public URL works after reboot.
    155 - Host can recover setup using repair mode.
    156 - Core moderation controls are enabled by default.
    157 
    158 ## Immediate Next Steps
    159 1. Draft moderation MVP spec in detail (roles, actions, audit log schema).
    160 2. Implement moderation MVP and test with at least 3 users.
    161 3. Draft `.env.example` and startup validation checks.
    162 4. Start `bzl-init` CLI prototype.