cgalo5758
71818de0bd
Implement the ux-first-run change: a state-derived setup checklist on /operator/setup with a landing region that recedes once required steps are done, and empty states that distinguish blocked from empty across operator and member surfaces. Also add production deployment and environment reference docs, plus a config-key completeness test.
149 lines
6.9 KiB
Markdown
149 lines
6.9 KiB
Markdown
# member-console
|
|
|
|
**One system for memberships and the hosted services they pay for.**
|
|
|
|
member-console is open-source software for offering hosted services on a paid
|
|
membership. In one place it handles the pieces that otherwise get stitched
|
|
together by hand — who each member is, what they're entitled to, what they pay —
|
|
then turns that into the actual, metered services running on their behalf, kept
|
|
in sync as members join, upgrade, and leave. New kinds of service attach through
|
|
a shared contract instead of reshaping how membership or billing work, so the
|
|
offering can grow on one foundation.
|
|
|
|
It has two sides: an **operator panel** where staff run the service, and a
|
|
**member panel** where members sign in to manage their own plan and workspace.
|
|
|
|
_Developed by the Wiki Cafe Multistakeholder Cooperative, and built for any organization to run._
|
|
|
|
|
|
|
|
_The operator landing surface_
|
|
|
|
> **Status: pre-production.** The engine is feature-complete for its first
|
|
> service tiers, but this is not yet a hardened, turnkey deployment. Expect
|
|
> rough edges in first-run setup. [docs/production-deployment.md](docs/production-deployment.md)
|
|
> sequences a real path to a running production instance, but it is a
|
|
> self-hoster's guide to follow and adapt, not a one-command install — the
|
|
> test stack remains the fastest way to see the console running. See
|
|
> [`status/`](status/) for the honest state of every milestone.
|
|
|
|
License: **AGPL-3.0** — see [LICENSE](LICENSE).
|
|
|
|
## What it does
|
|
|
|
- **Governance spine** — identity (via any OIDC provider) → organization → workspace,
|
|
with auto-provisioning of a default workspace for new members.
|
|
- **Entitlements** — grants resolve to numeric limits (e.g. FedWiki site count and
|
|
storage) materialized per resource pool; plan ladders model upgrade/downgrade
|
|
paths with a generic transition primitive.
|
|
- **Billing** — Stripe is the billing execution engine. Products, prices,
|
|
customers, subscriptions, and invoices are mirrored via a webhook pipeline;
|
|
the console never holds card data.
|
|
- **Integrations** — an integration contract (manifest, namespaced resource
|
|
keys, lifecycle verbs) lets a new hosted service conform without reshaping the
|
|
operator panel or entitlement layer. FedWiki is the first conforming integration.
|
|
|
|
## Architecture
|
|
|
|
- **Go 1.23**, server-rendered **HTMX** multi-page app — no SPA framework — under a
|
|
strict Content-Security-Policy (`script-src 'self'`, `style-src 'self'`; all JS
|
|
and CSS is self-hosted, no inline `<script>`/`style=`).
|
|
- **PostgreSQL** with a schema-ownership boundary between core and integrations:
|
|
the console's own data lives in a single `core` schema, and each integration
|
|
owns its schema (`fedwiki`, `stripe`) and its own migration ledger — so adding
|
|
one renumbers nothing (core-first is the only ordering rule). Queries are
|
|
generated with **sqlc**; migrations run with **goose**.
|
|
- **Temporal** for durable workflows (provisioning, integration sync, billing
|
|
sweeps).
|
|
- **OIDC** for authentication — member-console is identity-provider-agnostic and
|
|
works with any OIDC-compliant IDP (the test stack ships Keycloak).
|
|
|
|
Full documentation is indexed in [`docs/`](docs/README.md), grouped by audience
|
|
(developer / admin / user). Highlights:
|
|
[deployment architecture](docs/deployment-architecture.md),
|
|
[hosting](docs/hosting.md),
|
|
[building an integration](docs/building-an-integration.md),
|
|
[database management](docs/database-management.md), and [Stripe](docs/stripe.md).
|
|
|
|
## Running it
|
|
|
|
**What you need:**
|
|
|
|
- A **FedWiki farm** — FedWiki is the console's only conforming integration
|
|
today (see "What it does" above), so a deployment with no farm has no
|
|
product to actually deliver to a paying member. See
|
|
[fedwiki-setup.md](docs/fedwiki-setup.md).
|
|
- An **OIDC identity provider** — any OIDC-compliant provider; the console
|
|
authenticates members and operators against it and never stores passwords
|
|
itself. See [identity-provider-setup.md](docs/identity-provider-setup.md).
|
|
- **PostgreSQL**, **Valkey**, and **Temporal** — the console's own data
|
|
store, session store, and durable-workflow engine (provisioning,
|
|
integration sync, billing sweeps). See
|
|
[database-management.md](docs/database-management.md) and
|
|
[deployment-architecture.md](docs/deployment-architecture.md).
|
|
- **Stripe** — optional, only needed to sell paid products; a deployment
|
|
offering only free or unmetered products can skip it. See
|
|
[stripe.md](docs/stripe.md).
|
|
|
|
**First run, in order:**
|
|
|
|
1. Deploy the console and the dependencies above — see
|
|
[docs/production-deployment.md](docs/production-deployment.md) for the
|
|
sequenced path from a built image to a running instance.
|
|
2. Sign in as an operator (the account holding the `operator-member` role
|
|
configured on the identity provider).
|
|
3. Follow the in-app setup checklist at `/operator/setup`, which walks
|
|
through everything still needed to reach a deliverable product.
|
|
|
|
## Quickstart (local development)
|
|
|
|
Prerequisites: Docker (with Compose), Go 1.23+, and `make`.
|
|
|
|
The test stack brings up Postgres, Valkey, Temporal, and Keycloak in
|
|
containers, then runs the console from source against them. All commands run
|
|
from the `test/` directory:
|
|
|
|
```bash
|
|
cd test
|
|
./bootstrap-stack.sh # generate a per-worktree .env with collision-free ports
|
|
docker compose up -d # Postgres, Valkey, Temporal, Keycloak
|
|
set -a; . ./.env; set +a # load the generated host ports / secrets
|
|
go run .. start --config mc-config.yaml
|
|
```
|
|
|
|
Integrations are opt-in, not baked into the stack: a FedWiki farm or a live
|
|
Discourse forum is composed by adding its name to the `COMPOSE_PROFILES` knob
|
|
in the generated `test/.env` (and uncommenting that integration's `MC_*` block
|
|
in the same file). The console runs fine with neither.
|
|
|
|
`bootstrap-stack.sh` prints the URL table it allocated. With default ports the
|
|
console is at **http://member-console.localhost:9481**; sign in to the operator
|
|
panel as `alice` / `password`.
|
|
|
|
> On a fresh stack the console rides out Temporal's cold-start with a bounded
|
|
> connect retry, so the first `start` may pause briefly before the server comes
|
|
> up — no re-run needed.
|
|
|
|
See [`test/AGENTS.md`](test/AGENTS.md) for the full stack contract (idempotency,
|
|
Stripe webhook constraints, teardown, running multiple worktrees concurrently).
|
|
|
|
## Project status & roadmap
|
|
|
|
See [`status/`](status/) for the development roadmap, milestones, and notes.
|
|
Substantial changes are tracked as [OpenSpec](https://openspec.dev) proposals
|
|
under [`openspec/`](openspec/).
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
|
|
development workflow, building and testing, and the project conventions.
|
|
|
|
## Security
|
|
|
|
To report a vulnerability, see [SECURITY.md](SECURITY.md). Please do not open a
|
|
public issue for security reports.
|
|
|
|
## License
|
|
|
|
Licensed under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE).
|