
meetplus
io.github.rakaaaa/meetplus
Create and publish timed MeetPlus meetups and questionnaires from ChatGPT or Claude.
Documentation
MeetPlus
MeetPlus is a pnpm monorepo for server-authoritative timed meetups. The backend uses Fastify, TypeScript, PostgreSQL, Redis pub/sub, secure cookie sessions, Argon2, Zod, multipart image uploads, and SMTP.
Prerequisites
- Node.js 20 or newer
- Corepack (included with standard Node.js 20 installations)
- Docker Desktop or another Docker installation with Compose v2
If node, corepack, or docker compose is unavailable, install or enable the
missing prerequisite and ensure it is on PATH. Docker must be running before
the startup script is used.
Quick start
Single command (validates prerequisites, starts Docker services, migrates, runs API + web):
node run.mjs
Or use any of these equivalents:
| Platform | Command |
|---|---|
| Any (recommended) | corepack pnpm start |
| Windows | run.bat |
| macOS / Linux | chmod +x run.sh && ./run.sh |
The script is safe to run repeatedly. It:
- Validates Node.js 20+, Docker, and Compose v2.
- Creates
.envfrom.env.exampleonly when.envdoes not exist. - Installs packages with the pinned Corepack-managed pnpm version.
- Starts PostgreSQL 16, Redis 7, and Mailpit and waits until they are healthy.
- Runs database migrations.
- Starts the API and web dev servers (
pnpm dev).
When startup finishes, open the web app at http://localhost:5173 (or your
WEB_ORIGIN in .env).
The API is available at http://localhost:3001; health is at /health.
Services
- PostgreSQL:
localhost:5432 - Redis:
localhost:6379 - Mailpit SMTP:
localhost:1025 - Mailpit UI: http://localhost:8025
Values can be changed in .env. Existing .env files are never overwritten by
the startup scripts.
Workspace layout
apps/api— Fastify API, SQL migrations, media adapter, and maintenance jobsapps/web— React/Vite admin and participant web applicationapps/android— Kotlin/Compose hardened WebView shellpackages/shared— Zod schemas, inferred API types, and shared utilities
Commands
Run commands through Corepack to ensure the pinned pnpm version is used:
corepack pnpm dev
corepack pnpm build
corepack pnpm typecheck
corepack pnpm lint
corepack pnpm test
corepack pnpm migrate
Stack verification
These are stack-level checks, not unit tests. Both commands require a running Docker daemon with Compose v2. They start PostgreSQL, Redis, and Mailpit, apply migrations, launch the required application processes, and fail early with a clear prerequisite message when Docker is unavailable.
Install the Playwright Chromium browser once before the browser checks:
corepack pnpm exec playwright install chromium
Run the real API integration scenario:
corepack pnpm test:integration
It registers two admins and two participants and verifies owner isolation, meetup creation, code/link joining and join idempotency, server-timed active questions, immutable/idempotent answers, selected-count privacy, a question boundary transition, completion, and owner-grouped results against PostgreSQL, Redis, and the running API.
Run browser smoke and workflow checks:
corepack pnpm test:e2e
Playwright runs Chromium in desktop and mobile viewport projects. It covers the
public authentication routes plus key admin creation and participant joining
flows, and treats uncaught page errors, console errors, failed requests, and
HTTP 5xx responses as failures. To point an already configured invocation at
other endpoints, set PLAYWRIGHT_BASE_URL and PLAYWRIGHT_API_URL.
MCP server
mcp-servers/meetplus is an MCP server for AI clients. It lets ChatGPT/Claude/Gemini-style
clients ask the right planning questions, create draft meetups and questionnaires,
append a questionnaire to a draft, preview deterministic timing, validate, publish/cancel
with explicit confirmation, and fetch the host-only invitation only when asked.
- stdio for trusted local clients such as Claude Desktop, Cursor, Claude Code and Gemini CLI.
- Streamable HTTP at
https://<host>/mcpfor ChatGPT and Claude.ai connectors, with OAuth 2.1 (dynamic client registration, PKCE, scoped tokens, rotation and revocation). SetMCP_PUBLIC_URLto enable it; it stays off when unset.
It reuses the real API and shared contracts; it does not query PostgreSQL or Redis.
Setup, client configuration and security notes are in
mcp-servers/meetplus/README.md and
docs/mcp/.
ChatGPT, Claude.ai and Claude Code setup is in
docs/mcp/client-setup.md. The remote connector uses the
existing api and gateway containers; no separate MCP container is required. The public
integration page is /integrations/mcp, and the official MCP Registry listing is built
from mcp-servers/meetplus/server.json.
Naming
- Workspace packages are
@meetplus/*; usecorepack pnpm --filter @meetplus/api. - The ops CLI is
deploy/meetplus.sh.deploy/meetcon.shremains as a compatibility shim. MEETPLUS_*ops variables are accepted first, withMEETCON_*fallbacks.- Docker project/image names, database names, the session cookie and the Android
application ID intentionally keep their historical
meetconvalues so existing deployments, data volumes and Play updates keep working.
Backend
Copy .env.example to .env and replace TOKEN_ENCRYPTION_KEY outside local
development. Generate it with:
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
Run corepack pnpm migrate after PostgreSQL is healthy. Migrations are
checksummed and serialized with a PostgreSQL advisory lock.
The API exposes:
- Email/password plus LinkedIn, Google, X, Facebook and Instagram registration, login/logout/session restoration, password reset/change, LinkedIn-account password setup, and active-session revoke
- Social invitation sharing to LinkedIn, X, Facebook and Gmail, plus native-share/copy fallback for Instagram
- Profile editing, image upload/removal, theme/time-zone settings, LinkedIn disconnect, consent history/export, and anonymized deletion
- Owner-isolated draft/published meetup CRUD with version checks, descriptions, locations, meeting links, cover URLs, duplication, draft deletion, and cancellation reasons
- Code/token invitation preview, including anonymous preview before sign-in, and idempotent participant joining
- Joined meetup lists with cancelled-meetup history, leaving, calendar export, server-authoritative active state, immutable answers, and live SSE updates
- Live host controls for start now, pause/resume, next question, next questionnaire, and end meetup now
- Owner-only grouped results, participant rosters/non-responders, live display mode, and raw or summary CSV exports
- Question reminders, cancellation notifications, AI drafting through OAuth or a personal API key, and participant end-of-meetup recaps
Social sign-in setup
Each provider is optional. Set the client id and secret in .env (or the Jenkins
secret file in production). The default callback URL is
${WEB_ORIGIN}/api/auth/<provider>/callback.
| Provider | Scopes | Notes |
|---|---|---|
openid profile email | Requires “Sign In with LinkedIn using OpenID Connect”. | |
openid email profile | Uses Google OpenID userinfo. | |
| X | users.read tweet.read | PKCE; X does not return an email address. |
email,public_profile | Email is used when Facebook returns it. | |
instagram_business_basic | Instagram Login requires a professional account; no email is returned. |
X and Instagram accounts are created with a private placeholder address when the
provider does not return an email. The user can replace it from Profile. Social
sign-in identities are stored in user_social_identities; existing LinkedIn
identities are backfilled by migration 003_social_identities.sql.
Production website (port 30098)
Production is a separate Docker stack from local development. Local run.bat
starts project meetcon (PostgreSQL, Redis, Mailpit only) and runs the app on
the host. Production starts project meetcon-prod and runs the API, web, and
database entirely in Docker.
| Local | Production | Simulation | |
|---|---|---|---|
| Start | run.bat / node run.mjs | run-production.bat / node run-production.mjs | ./deploy/meetplus.sh simulate |
| Compose project | meetcon | meetcon-prod | meetcon-sim |
| Env file | .env | .env.production | .env.simulation |
| What Docker runs | Postgres, Redis, Mailpit | Gateway, API, Postgres, Redis | Same services, isolated volumes |
| App images | none (host pnpm dev) | meetcon-api:<git-sha>, meetcon-gateway:<git-sha> | meetcon-api:simulation, meetcon-gateway:simulation |
| URL | http://localhost:5173 | https://meetcon.aiadoptionecosystem.com | https://127.0.0.1:30998 |
run-production refuses to start when .env.production still has the local
password, a localhost database URL, or an http:// origin. Compose is started
with COMPOSE_DISABLE_ENV_FILE=1, so the local .env cannot override it.
Each production deploy tags images with the git commit. meetcon-api:production
is an alias of that commit. Roll back with MEETCON_IMAGE_TAG=<older-sha>.
For an Ubuntu VM with Docker, use the production stack documented in
deploy/DEPLOYMENT.md. It exposes only HTTPS port
30098 on the gateway, serves the React build, and proxies /api and /media to
the internal API.
Quick start on the VM:
cp .env.production.example .env.production
# edit secrets. WEB_ORIGIN=https://meetcon.aiadoptionecosystem.com (port 30098 stays internal)
# add deploy/certs/fullchain.pem and deploy/certs/privkey.pem
chmod +x deploy/meetplus.sh
./deploy/meetplus.sh up
Or: corepack pnpm deploy:up. Ops guide: deploy/README.md. Jenkins: Build Now (deploy/jenkins/README.md).
Files added for production:
docker-compose.prod.yml— gateway, API, migrate, PostgreSQL, Redisapps/api/Dockerfile— API imagedeploy/gateway/Dockerfile— Nginx + static web build on:30098deploy/nginx.conf— SPA, SSE-friendly/apiproxy, TLS.env.production.example— template environment
Session cookies are Secure in production. WEB_ORIGIN is the public site
https://meetcon.aiadoptionecosystem.com. Docker still listens on port 30098
behind that name.
The Android release app uses the same origin in a full-screen WebView with no URL bar.
Forgot-password mail is captured locally at http://localhost:8025. Expired sessions and reset tokens are cleaned hourly while the API is running.
To stop local services:
docker compose down
Add --volumes to that command only when you intentionally want to delete
local PostgreSQL and Redis data.
No installation packages available.