https://github.com/podverse/metaboost
A message collection and viewing system, intended for use with RSS value tag implementations
https://github.com/podverse/metaboost
Last synced: 3 months ago
JSON representation
A message collection and viewing system, intended for use with RSS value tag implementations
- Host: GitHub
- URL: https://github.com/podverse/metaboost
- Owner: podverse
- License: agpl-3.0
- Created: 2026-04-10T00:59:58.000Z (4 months ago)
- Default Branch: develop
- Last Pushed: 2026-04-29T05:52:18.000Z (3 months ago)
- Last Synced: 2026-04-29T07:05:49.940Z (3 months ago)
- Language: TypeScript
- Size: 3.26 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Metaboost
HTTP API and Next.js app. Structure and tooling follow the repository standards used in this project.
## Structure
- **apps/api** – Standalone Express API (port 4000 by default)
- **apps/web** – Next.js app (default **4002** on host; see `PORT` in `apps/web/package.json`)
- **apps/web/sidecar** – Runtime-config sidecar (`WEB_SIDECAR_PORT`, default **4001** on host)
- **Infra (database, management database, Docker):** See [infra/INFRA.md](infra/INFRA.md).
## Setup
**Quick path (clone → running):** See [docs/QUICK-START.md](docs/QUICK-START.md) (Make + Docker for Postgres/Valkey, API and web on host).
**With Nix (Linux / macOS):** If you use [direnv](https://direnv.net/), run `direnv allow` in the repo root once. The flake provides Node 24 and the shell loads automatically. Without direnv: `nix develop` to enter the dev shell.
```bash
npm install
```
**Local env:** App and infra `.env` files are generated by **`make local_env_setup`**, not by copying
`.env.example` alone. See
[docs/development/env/LOCAL-ENV-OVERRIDES.md](docs/development/env/LOCAL-ENV-OVERRIDES.md) for secrets,
overrides, and optional `local_env_prepare` / `local_env_link`.
[docs/QUICK-START.md](docs/QUICK-START.md) is the shortest path from clone to running (Docker infra +
`npm run dev:all`).
## Run
From the repo root, run **`make local_env_setup`** before commands that need generated env files
(API, sidecars, `infra/config/local/*`). Do not rely on manual `cp` from `.env.example` for a full
local stack.
**API and web on host (Postgres and Valkey in Docker):** After `npm install` and `make local_env_setup`,
run `make local_infra_up` then `npm run dev:all` (or `npm run dev:all:watch`). See
[docs/QUICK-START.md](docs/QUICK-START.md).
**API only:**
```bash
make local_env_setup
npm run dev:api
```
**Web only (no sidecar):**
```bash
make local_env_setup
npm run dev:web
```
**Web with sidecar (runtime config from env):**
```bash
make local_env_setup
npm run dev:web-sidecar
```
This builds the sidecar, then starts the sidecar (default **4001**) and the Next.js app (**4002**).
`RUNTIME_CONFIG_URL` and sidecar env are written by `local_env_setup`; the app loads config from the
sidecar at startup.
## Env examples
- **API**: `API_PORT`, `BRAND_NAME`, `AUTH_JWT_SECRET`, and optionally `ACCOUNT_SIGNUP_MODE`, `MAILER_ENABLED`
(env templates / generated `apps/api/.env`)
- **Web**: `RUNTIME_CONFIG_URL` in app (see `apps/web/.env.example`); sidecar templates under each app’s `sidecar/` when present
- **Exhaustive variable names, merge defaults (`local_docker` vs `remote_k8s`), and Kubernetes placement:**
[docs/development/env/ENV-VARS-REFERENCE.md](docs/development/env/ENV-VARS-REFERENCE.md) (regenerate after env template changes: `make env_catalog`)
- **Groups, merge order, and semantics:**
[docs/development/env/ENV-REFERENCE.md](docs/development/env/ENV-REFERENCE.md)
## API auth
The API is versioned under a path prefix (default **/v1**; set `API_VERSION_PATH` to change, e.g. `API_VERSION_PATH=/v2`). Example: `GET /v1/health`, `POST /v1/auth/login`. Use JWT: send `Authorization: Bearer ` for protected routes (e.g. `GET /v1/auth/me`, `POST /v1/auth/change-password`). Set `MAILER_ENABLED=true` for self-service signup (`POST /v1/auth/signup`). When mailer is disabled (default or `ACCOUNT_SIGNUP_MODE=admin_only`), signup is disabled; user creation is handled by the Management API when the Management track (plans 31–33) is in use.
**AUTH_JWT_SECRET** (separate values for API vs management-api) and all other passwords (DB, Valkey) are generated and written by `make local_env_setup` (or `make env_setup`). Do not put placeholder passwords in env examples; re-run `make local_env_setup` to create or refresh local env files. Override files (brand.env, management-superuser.env) are applied when present; use prepare/link to share them across work trees. See [docs/development/env/LOCAL-ENV-OVERRIDES.md](docs/development/env/LOCAL-ENV-OVERRIDES.md).
**API docs (Swagger):** With the API running, open [http://localhost:4000/v1/api-docs](http://localhost:4000/v1/api-docs) for interactive OpenAPI docs (prefix follows `API_VERSION_PATH`, default `/v1`). Use **Authorize** to set a Bearer token from login/signup, then try protected endpoints.
## Gitflow and CI
Default branch is **develop**; open PRs against `develop`. Use `npm run start-feature` to create branches (e.g. `feature/name`, `fix/name`). CI runs when a PR targets develop (on open/update) and when a maintainer comments **/test** on a PR. See [docs/GITFLOW.md](docs/GITFLOW.md).
## Scripts
- `npm run build` – Build all workspaces
- `npm run dev:api` – API only (port 4000)
- `npm run dev:web` – Web only (default port **4002**)
- `npm run dev:web-sidecar` – Build sidecar, then run sidecar (**4001**) and web (**4002**)
- `npm run dev:all` – Build sidecar, then run API, sidecar, and web together
- `npm run dev:api:watch` – API with auto-rebuild on change (tsc --watch + nodemon)
- `npm run dev:web:watch` – Web (Next.js dev; already hot-reloads)
- `npm run dev:all:watch` – API, sidecar, and web with auto-rebuild on change
- `npm run lint` – ESLint + Prettier check (TS/JS, YAML, JSON, MD, etc.)
- `npm run lint:fix` – ESLint --fix + Prettier --write (fixes all supported files, including docker-compose)
- `npm run prettier:check` / `npm run prettier:write` – Prettier only
**Version bump:** Run `./scripts/publish/bump-version.sh` when cutting a release. It updates root and all workspace `package.json` versions, then commits and pushes (no npm publish or image push).
**Alpha publish:** Merging to the `alpha` branch runs the Publish Alpha workflow and pushes Docker images (api, web, web-sidecar) to GHCR. See [docs/PUBLISH.md](docs/PUBLISH.md).
**GitHub labels:** Run `./scripts/github/setup-all-labels.sh` to create or update repo labels (requires `gh auth login`). See [scripts/github/SCRIPTS-GITHUB.md](scripts/github/SCRIPTS-GITHUB.md) and [docs/repo-management/GITHUB-LABELS.md](docs/repo-management/GITHUB-LABELS.md). For one-time repo setup (labels, branch protection, default branch), see [docs/repo-management/GITHUB-SETUP.md](docs/repo-management/GITHUB-SETUP.md). Dependency update policy and Dependabot (npm, Docker, Actions; Node LTS ≥ 24): [docs/repo-management/DEPENDABOT.md](docs/repo-management/DEPENDABOT.md).
## LLM / Cursor
See [.llm/LLM.md](.llm/LLM.md) and [AGENTS.md](AGENTS.md) for history tracking and agent guidelines.