chad/ECS-FullStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

swapped to a new db locally hosted

Browse Source
This commit is contained in:
Chad Doty
2025-10-06 00:25:29 -04:00
parent 097583ca0a
commit ca23c0ab8c
40 changed files with 2244 additions and 556 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
README.md
View File

@@ -4,6 +4,8 @@ A full-stack example project that integrates a React frontend, an Express backen
This README documents how to get the project running, what environment variables are required, where to get Discord keys, how the invite token flow works, and basic troubleshooting tips.
Note: The backend has been updated to support Postgres persistence (see `CHANGELOG.md`). The backend now requires `DATABASE_URL` to run in the default configuration; if you prefer the legacy encrypted file store, see the notes under "Developer notes".
## Repository layout
- `frontend/` — React (Create React App) frontend. Uses `REACT_APP_API_BASE` to communicate with the backend in dev and production.
@@ -17,6 +19,16 @@ This README documents how to get the project running, what environment variables
- Runs a Discord bot (discord.js) that performs moderation and server features. The backend and bot are closely integrated: the backend hosts the API and the bot client is shared to fetch guild data and manipulate invites/channels/roles.
- Uses a short-lived token flow to authorize invite deletions from the frontend without embedding long-lived secrets in the client.
Expanded: what this app does
- Hosts a dashboard (React) that lists Discord guilds where the bot is present and lets server admins:
- create and manage invites (create invites with options, view persisted invites, copy and revoke)
- configure Welcome and Leave messages and channels
- enable/disable bot commands per server
- set autorole behavior for new members
- Provides a backend API (Express) that coordinates with a discord.js bot to perform live guild operations (fetch channels/roles, create invites, leave guilds)
- Stores configuration and invites in Postgres (recommended) or a legacy encrypted `db.json`
## Quickstart — prerequisites
- Node.js (recommended 18.x or later) and npm
@@ -39,6 +51,9 @@ DISCORD_CLIENT_SECRET=your_discord_client_secret
ENCRYPTION_KEY=a-32-byte-or-longer-secret
INVITE_TOKEN_SECRET=optional-second-secret-for-invite-tokens
# Postgres example (optional but recommended)
# DATABASE_URL=postgres://dbuser:dbpass@100.111.50.59:5432/ecs_db
- `PORT` / `HOST`: where the backend listens.
- `BACKEND_BASE` and `FRONTEND_BASE`: used for constructing OAuth redirect URIs and links.
- `CORS_ORIGIN`: optional; set to your frontend origin to restrict CORS.
@@ -47,6 +62,27 @@ INVITE_TOKEN_SECRET=optional-second-secret-for-invite-tokens
Note: This project previously supported an `INVITE_API_KEY` static secret; that requirement has been removed. Invite deletes are authorized via short-lived invite tokens by default.
### Twitch Live Notifications (optional)
This project can detect when watched Twitch users go live and post notifications to a configured Discord channel for each guild. To enable this feature, add the following to `backend/.env`:
- `TWITCH_CLIENT_ID` — your Twitch app client id
- `TWITCH_CLIENT_SECRET` — your Twitch app client secret
- `TWITCH_POLL_INTERVAL_MS` — optional, poll interval in milliseconds (default 30000)
When configured, the backend exposes:
- GET /api/twitch/streams?users=user1,user2 — returns stream info for the listed usernames (used by the frontend and bot watcher)
The bot includes a watcher that polls watched usernames per-guild and posts a message to the configured channel when a streamer goes live. The message includes the stream title and a link to the Twitch stream.
If you run the backend and the bot on separate hosts, you can configure the backend to push setting updates to the bot so toggles and watched users propagate immediately:
- `BOT_PUSH_URL` — the URL the bot will expose for the backend to POST setting updates to (e.g., http://bot-host:4002)
- `BOT_SECRET` — a shared secret used by the backend and bot to secure push requests
- `BOT_PUSH_PORT` — optional, the port the bot listens on for push requests (if set the bot starts a small HTTP receiver)
### frontend/.env (example)
HOST=0.0.0.0
@@ -90,6 +126,16 @@ npm install
npm start
```
Optional: using Postgres (recommended)
1. Create a Postgres database and user (pgAdmin or psql)
2. Set `DATABASE_URL` in `backend/.env`, e.g.:
DATABASE_URL=postgres://dbuser:dbpass@100.111.50.59:5432/ecs_db
3. Start the backend; on startup the backend will create simple tables if missing.
Migration note:
- If you have existing data in `backend/db.json`, a migration script is planned to import invites and server settings into Postgres. I can add that script on request.
2. Frontend
```powershell
@@ -106,6 +152,7 @@ npm run start
## Troubleshooting
- Backend refuses to start or missing package.json: ensure you run `npm install` in the `backend` folder and run `npm start` from that folder.
- If the backend exits with "DATABASE_URL is not set": either set `DATABASE_URL` in `backend/.env` pointing to your Postgres DB, or restore the legacy behavior by editing `backend/index.js` to re-enable the encrypted `db.json` fallback (not recommended for production).
- CORS errors: verify `CORS_ORIGIN` and `REACT_APP_API_BASE` match your frontend origin.
- Invite delete unauthorized: ensure backend `INVITE_TOKEN_SECRET` or `ENCRYPTION_KEY` is present and token TTL has not expired. Check the backend logs for validation details.
- Token issues: clock skew can cause tokens to appear expired — ensure server and client clocks are reasonably in sync.
@@ -120,8 +167,87 @@ npm run start
- Harden `/api/servers/:guildId/invite-token` to require an authenticated user and verify the user has admin permissions for the guild.
- Add rate-limiting to token issuance and optionally keep the old `INVITE_API_KEY` option for server-to-server automation.
- Updated docs: the README and CHANGELOG were updated to reflect Postgres integration and recent frontend/backend changes. See `CHANGELOG.md` and `checklist.md` for details.
If you want, I can add step-by-step instructions to create the `.env` files from templates, or implement the production safe option of authenticating `/invite-token` requests. Tell me which you'd prefer.
---
Updated: Oct 4, 2025
Updated: Oct 4, 2025
## Full setup guide (detailed)
This section walks through the exact steps to get the project running locally or on a machine reachable via Tailscale/Nginx Proxy Manager.
Prerequisites
1. Node.js 18+ and npm
2. Postgres (local or remote) or use an existing Postgres server reachable over your network/Tailscale
3. Discord application + Bot credentials and (optional) Twitch app credentials
Database (Postgres) setup
1. Create a Postgres database and user. Example psql commands:
```bash
sudo -u postgres psql
CREATE DATABASE ecs_fullstack;
CREATE USER ecs_user WITH PASSWORD 'supersecret';
GRANT ALL PRIVILEGES ON DATABASE ecs_fullstack TO ecs_user;
\q
```
2. Set the `DATABASE_URL` in `backend/.env`:
```
DATABASE_URL=postgres://ecs_user:supersecret@127.0.0.1:5432/ecs_fullstack
```
3. Start the backend (it will run migrations / ensure tables at startup):
```powershell
cd backend
npm install
npm start
```
Backend configuration (.env)
- `DATABASE_URL` - required for Postgres persistence
- `DISCORD_CLIENT_ID`, `DISCORD_CLIENT_SECRET`, `DISCORD_BOT_TOKEN` - from Discord Developer Portal
- `FRONTEND_BASE` - public frontend URL (used for OAuth redirect)
- `PORT`, `HOST` - where backend listens
- `CORS_ORIGIN` - optional restrict origin to your frontend URL
- `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET` - optional for Twitch integration
Frontend configuration
1. In `frontend/.env` set:
```
REACT_APP_API_BASE=https://your-domain-or-ip:3002
```
2. For development behind an HTTPS domain (Nginx Proxy Manager), ensure the CRA dev client uses `wss` by setting the `WDS_SOCKET_*` variables in `frontend/.env` (see docs if using a TLS domain)
Start the frontend dev server:
```powershell
cd frontend
npm install
npm start
```
Bot behaviour and deployment
- The `backend` process will boot the Discord bot client when valid `DISCORD_BOT_TOKEN` is present. The bot registers slash commands per guild on startup and responds to backend pushes for setting updates.
- If you prefer to run the bot separately, you can run the `discord-bot` module separately; ensure `BOT_PUSH_URL`/`BOT_SECRET` are configured if backend and bot are on different hosts.
Useful endpoints
- `GET /api/servers/:guildId/commands` — returns the authoritative list of commands and per-guild enabled/locked status.
- `GET/POST /api/servers/:guildId/live-notifications` — get/update live notification settings
- `GET /api/twitch/streams?users=user1,user2` — proxy to twitch helix for streams (backend caches app-token)
- `GET /api/events?guildId=...` — Server-Sent Events for real-time updates (ServerSettings subscribes to this)
Notes about Postgres requirement
- The backend now assumes Postgres persistence (via `DATABASE_URL`). If `DATABASE_URL` is not set the server will exit and complain. This change makes server settings authoritative and persistent across restarts.
Logs and verbosity
- The bot and watcher log messages have been reduced to avoid per-guild spam. You will see concise messages like "🔁 TwitchWatcher started" and "✅ ECS - Full Stack Bot Online!" rather than one-line-per-guild spam.
Troubleshooting
- If you see mixed-content errors in the browser when using a TLS domain with the CRA dev server, configure Nginx to proxy websockets and set CRA `WDS_SOCKET_*` env vars (see docs/nginx-proxy-manager.md)