Requirements
- A current maintained Node.js installation and npm; the repository does not pin a precise engines minimum.
- A persistent host for Express and Socket.IO, with disk space for projects, users, and recovery copies.
- A public HTTPS origin for normal remote use and Scratch Auth callbacks. Localhost HTTP is supported for development.
- A reverse proxy that forwards both HTTP requests and Socket.IO/WebSocket traffic.
Install the backend
Edit .env before starting. Use the same release for the backend and extension when diagnosing compatibility. Commands below match the included PM2 setup.
git clone https://github.com/Waakul/CoBlocks.git
cd CoBlocks
cd backend
npm ci
cp .env.example .envEnvironment reference
| Variable | Configuration |
|---|---|
| PORT | Listener port, for example 4000. |
| PUBLIC_BASE_URL | Public API origin used to construct Scratch Auth callbacks. Example: https://collab.example.org; use http://localhost:4000 for local development. |
| TRUST_PROXY | Express proxy-trust setting. The template uses loopback; match your actual proxy topology. |
| API_RATE_LIMIT | API request cap used by the limiter; template/default 300. Inspect the source window and adjust to real traffic. |
| CHAT_WEBHOOK_URL | Optional Discord-compatible destination for chat/operational logs. Messages can contain user/project content. |
| ADMIN_USER | JSON object configuring operator HTTP Basic Auth credentials. Template: {}. |
| ADMIN | JSON array of privileged Scratch usernames. Template: []. |
Run and inspect the service
The included ecosystem configuration names the process CoBlocks and sets its working configuration from .env. Starting it with PM2 alone does not configure startup at boot, TLS, backups, or a reverse proxy; provision these separately on your host.
npm run start
npx pm2 status
npx pm2 logs CoBlocks
# Stop or remove the PM2 process
npm run stop
npm run deletePersist and back up the data directories
- backend/storage/ contains project/session data, Scratch-to-CoBlocks links, users, and related records.
- backend/storage-redundancy/ contains mirrors and bounded recovery snapshots.
- Preserve both directories across redeployments. Use separate off-host backups; redundant files on one disk do not protect against losing that disk.
- Review the bundled 60-day inactive-project cleanup before running a community service.
Connect the extension to your server
The popup validates a plain HTTP(S) hostname with an optional port. Switching server clears login credentials; projects and accounts are not migrated between backends.
- Open the popup → Settings → Custom Server.
- Enter the server origin, such as https://collab.example.org or http://localhost:4000. Do not enter an /apiv2 path.
- Enable Custom Server and approve the requested permission for that origin.
- Wait for the extension to reload, then sign in again through Scratch Auth.
- Have every collaborator configure the same server before sharing invitations.
Verify before using it with a team
- The HTTPS origin matches PUBLIC_BASE_URL and Scratch Auth completes a fresh login.
- Two separate Scratch accounts can create/accept an invitation and see each other online.
- Blocks, chat, backpack items, and reconnects work through your proxy.
- Owner-only access operations are rejected for collaborators.
- Data survives a controlled restart, and a tested backup can be restored.
- Logs and webhooks have an appropriate access and retention policy.