Alpha Installation and Operator Guide

Last updated: Sep 26, 2026Status: Current Alpha guidanceAudience: Operators and evaluatorsApplies to: DiscussionBridge Alpha

This is the current operator path for the DiscussionBridge Alpha. Start here, then use the platform-specific notes in Platform Profiles and the exact deployed identities in Versions And Live Status.

DiscussionBridge is a family of focused tools. DiscussionBridge for Discourse is the unified receiver plugin. A platform adapter or addon connects one publishing installation to that receiver; it does not become a second control plane. The Bridge is reserved for the dedicated public demo.

Astro Simple and Full are the sole current plugin-free Discourse integration paths in the supported platform family. Ghost, Hugo, Statamic, and WordPress installations require DiscussionBridge for Discourse and an enabled Content Connection for their DiscussionBridge integration.

The receiver performs authorized Discourse writes through the dedicated discussionbridge service account because Discourse requires an authenticated user identity. That constrained operating identity is not the former bot-driven architecture and is deliberately separate from the visible topic author. Do not configure new connections around the legacy discussbridge-bot user.

1. Choose The Systems And Job

Record the exact Discourse forum and publishing installation before installing anything. One Content Connection represents one installation, not an entire platform brand and not an arbitrary collection of origins.

Choose which jobs the connection may perform:

To Discourse creates or resolves one forum-governed discussion for an authoritatively published platform item.
From Discourse exposes a selected forum topic to that platform for safe presentation or, only when separately authorized, native materialization.
A connection may permit either direction or both. Each Bridge Record still has one direction and one stable identity.

Also choose the allowed canonical origin, lane, category, tags, visibility, comments presentation, visible author policy, and whether new To Discourse topics should receive a DiscoTOC marker.

2. Establish Recovery Before Installation

Do not use a successful build or container rebuild as rollback evidence.

For Discourse, preserve the protected container configuration and a database/uploads or whole-server recovery point. A launcher rebuild reuses persistent data.
For WordPress, preserve the database and wp-content.
For Ghost, preserve the database, content, protected config, theme, integration/webhook records, adapter state, service unit, and proxy config.
For Statamic Flat, preserve the application, content, users, environment, addon database, and web/PHP service configuration.
For Statamic DB, also preserve an authoritative database dump.
For Statamic SSG, preserve the protected authoring application and generated deployment identity separately.
For Astro and Hugo, preserve lockfiles, adapter state, generated binding data, deployment identity, and the last known-good artifact.

Record paths, byte counts, hashes, ownership/modes, and the restore sequence. Secrets may be referenced by protected location; never copy their values into the runbook.

3. Install DiscussionBridge For Discourse

Install DiscussionBridge for Discourse from its public GitHub repository in the intended Discourse container. Copy the exact published tag from Versions And Live Status and confirm it against the component’s release notes. Stop if those sources disagree. For the standard app layout, add one pinned clone command to app.yml and rebuild only that container:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone --branch <exact-release-tag> --depth 1 https://github.com/DiscussionBridge/discourse-discussion-bridge.git

Replace the placeholder with the exact tag; do not paste it literally. This is one clone command and needs no separate checkout. Record the installed tag, commit, and artifact in the site runbook. A moving main checkout is not an immutable deployment identity.

cd /var/discourse
./launcher rebuild app

For a two-container installation, change only the container that owns the Discourse application/plugin build. Follow the installation’s own runbook; do not copy a single-container command blindly.

After the rebuild, verify the installed plugin commit, migration state, PostgreSQL, Redis, web processes, HTTPS, and ordinary forum behavior while the DiscussionBridge switches remain disabled.

4. Configure Forum Policy

In Discourse admin, open Plugins → DiscussionBridge and the native DiscussionBridge settings.

Configure and verify:

plugin and endpoint switches;
a privileged service identity used only to execute authorized operations;
a non-system default visible author;
default category, tags, and visibility;
optional lane policy;
comments-only Interactive support;
the ordinary Discourse embedding and CORS settings required by the selected presentation modes.

Choose who may see per-topic publication badges and controls: administrators, staff, or a dedicated DiscussionBridge Editors group. Use the narrower group for paid or delegated publishing work instead of granting general staff access. The optional DiscussionBridge Operator service capability and the Request Operator service action are separate steps: enabling local capability does not submit a service request or activate a paid service. An enrolled operator identity is narrowly bound to DiscussionBridge inspection and approved publication mutations. It does not receive connection-secret, global-setting, user-management, credential, or general forum-administration authority.

Before testing an embedded discussion, add the publishing site’s exact public HTTPS origin in Discourse’s Embeddable Hosts. Keep Embed any origin disabled unless the forum operator has deliberately chosen that broader policy. For Interactive mode, also enable Embed full app and its sign-in flow. A Content Connection’s allowed origin authorizes Bridge requests; it does not itself create a Discourse Embeddable Host.

The operating identity and visible author are deliberately separate. Choosing a visible author does not grant that user service authority.

5. Create A Content Connection

Under Connections, create one connection for the exact platform installation. Set:

a clear name and adapter identity;
exact allowed origin or origins;
permitted direction or directions;
allowed lane or lanes;
fixed-author or mapped-source-author policy;
optional Generate topic table of contents behavior;
enabled state.

After saving, inspect the origin’s readiness label in Connections. Embed host ready means Discourse Core allows that exact origin; Embeddable Host missing means embedding is not ready even if the adapter credential verifies. Correct the host rule before the first iframe test.

The new secret is shown once. Transfer it directly to the adapter’s protected server-side store. Never put it in page content, browser JavaScript, a public environment file, a URL, a support bundle, or Git.

Use the selected connection’s Authors tab after the adapter reports real source identities. Map a source author to an existing Discourse user only when that mapping is desired. A connection may instead use one fixed Discourse author for all platform content. Mapping changes affect future topics and do not silently rewrite prior ownership.

6. Install And Bind The Platform Adapter

Obtain the appropriate adapter or addon from its public repository, follow that component’s installation instructions, and bind it to:

Configure the installed component with:

the DiscussionBridge for Discourse HTTPS origin;
the dbc_… connection ID;
the platform’s protected connection-secret store;
the exact publishing-site origin;
the allowed lane;
the platform’s durable state location;
the intended content types, collections, tags, or opt-in fields.

See the platform-specific install and operate guide for Astro, Ghost, Hugo, Statamic, or WordPress. Use Platform Profiles for a comparison of native boundaries. See Adapter Operating Models for each adapter’s native object, optional initial-population and steady-state behavior, claim limit, lease, acknowledgement, and recovery boundary.

For WordPress installations without server-file access, paste the one-time secret under Settings → DiscussionBridge. The plugin encrypts it with the installation’s authentication salts, stores only a non-autoloaded ciphertext, and never redisplays it. Protected server configuration remains the preferred override when available.

Allow time for delivery. WordPress schedules DiscussionBridge delivery in the background. Depending on WordPress Cron and network timing, a post may remain Queued or Delivering briefly. Refresh the DiscussionBridge settings page after a short wait. Do not select Retry while either status is shown. Retry only after the delivery reports Attention or Failed.

Establish destination structure when native publication is enabled

For From Discourse native materialization, install the destination’s native navigation and content structure before the first preview or initial population. Create the intended section routes, collections, categories, tags, or indexes and verify that every public route works while it is still empty. This gives operators stable URLs and understandable navigation before synchronized content arrives.

This step does not apply merely because an Astro site uses its plugin-free Simple or Full comments path, and it does not require an initial population when only new platform items will flow To Discourse.

The initial state must be truthful:

an empty index says that no synchronized publications exist yet;
navigation may link to an empty native route, but must not invent entries, counts, authors, or synchronization status;
do not copy forum posts manually merely to make a destination look populated;
do not replace an applicable forum-scale preview and initial population with topic-by-topic authorization.

After the structure is verified, configure the connection’s category and tag selection plus its destination mappings. When an existing forum corpus is in scope, the preview shows which eligible topics will populate each native destination. The optional resumable initial population creates those entries; later synchronization updates the same durable identities without duplicates.

Before starting an applicable initial population, publish one representative topic as a canary. Verify its native identity, public URL, content, authorship, source credit, discussion link, update-in-place behavior, and rollback path. Then use the adapter-specific bounded batch and unattended worker described in Adapter Operating Models; do not convert a successful one-topic canary into an unbounded loop.

An empty but working native section is readiness evidence, not a failed publication. Record its route and rollback boundary before starting the initial population. Platform-specific empty states differ: a WordPress category can exist without posts, while a Ghost integration may need an explicit route until its first tagged publication exists. Use the native mechanism documented in Platform Profiles; do not fabricate placeholder content to hide the distinction.

7. Test The Workflow

Use newly created demo content so existing content cannot hide an identity or collision error.

For To Discourse:

opt in one draft through the platform’s native control;
publish it through the authoritative platform lifecycle;
run the adapter worker/build where the platform requires one;
verify one Bridge Record and one topic;
verify meaningful content, canonical source attribution, selected author, category, tags, visibility, and optional TOC;
retry the exact identity and prove no duplicate topic or record is created;
verify ordinary edits do not claim synchronization the adapter does not implement.

This proves the new-publication path for one stable item. It does not prove a large historical platform-to-Discourse import. The current Alpha has not yet qualified that bulk path across the platform adapters.

For From Discourse:

make the topic eligible through the connection’s category/tag policy or an explicit per-topic decision;
open the topic wrench menu and choose DiscussionBridge Status;
review each connection independently and choose its default, include, or exclude state plus the exact mapped destination;
if an existing forum corpus is in scope, preview the eligible population and destination mappings before starting the optional initial population;
choose presentation-only or explicitly authorize native materialization;
run the bounded adapter retrieval/materialization path, including initial population only when the decision in step 4 applies;
confirm the Publishing queue moves through Queued/Delivering to Current and that no terminal attention condition is hidden by record-health filters;
verify the source first post appears once, source attribution is clear, and replies/comments remain attached to the same topic;
retry one genuinely recoverable item unchanged, then test one authorized source revision update.

Do not use generic Retry for terminal identity drift, ownership conflicts, or known over-limit content. Diagnose and correct the cause first; a blind retry does not change the unsafe input.

For either direction, verify reconciliation is clean and a credential never appears in HTML, JSON intended for browsers, logs, URLs, screenshots, or error messages.

The current native From Discourse source-body boundary is 256 KiB. Content above the admitted adapter limit must become a truthful operator-attention item; it must not be silently truncated into a misleading publication.

Changing publishing platforms while keeping the same topic, replies, and moderation history is a separate migration operation. See Change Platforms, Keep The Discussion for what is implemented, what the OBBBA exercise proves, and the live cutover proof still required—including a coordinated bidirectional replacement when a connection performs both jobs.

8. Verify Presentation

Test every mode the profile claims on desktop and mobile. The current modes are defined in Presentation Modes.

Check source content, headings/TOC, tables, code, links, images, Mermaid, math, author/provenance, the open-discussion route, Discourse branding, the DiscussionBridge credit, reply visibility, Show more behavior, iframe height and internal scroll, signed-in and signed-out behavior, and keyboard focus.

Do not infer support from a route returning 200. Confirm the visible product behavior.

9. Disable, Re-enable, Remove, And Roll Back

Before relying on the connection, test these operations against test data:

disable the connection and verify adapter requests fail closed;
re-enable it and verify the same identity resolves without duplication;
disable the forum-wide endpoint and verify no adapter can bypass it;
stop the adapter worker/build hook and verify platform publishing still fails or queues honestly rather than blocking ordinary page rendering;
remove presentation wiring and verify the host page remains usable;
restore the pre-install package and verify the documented rollback.

Disabling DiscussionBridge does not delete topics, posts, users, categories, tags, platform content, or Bridge records. Removal and data retention are separate operator decisions. Never delete durable data merely to make a test look clean.

10. Record The Acceptance Boundary

Record exact source commits, artifacts and hashes, installed paths, lockfile or Composer binding, runtime/service identity, public deployment identity, connection ID, directions, modes, test content and topic/resource IDs, backup, rollback result, and known exclusions.

Alpha demos prove working implementation profiles. They do not by themselves prove a managed host will install a companion service, that provider recovery has been rehearsed, that mail is accepted, or that a production release has been approved.

For help, use Support And Feedback. Never include a connection secret or other credential in a support request.