Skip to main content
Version: Sprint 4

Installing and Running fla--

These instructions target application dev at 01c423c. The application and this documentation site are separate repositories and use different scripts.

Application​

Requires Node.js >=24 and npm. Clone the application:

git clone https://sdp.ms.wits.ac.za/sudoers-2/fla--.git
cd fla--
git switch dev
npm ci

For a complete persistent runtime, also install the dedicated room service's dependencies:

cd yjs
npm install
cd ..

Its separate lockfile is currently behind its manifest, so npm ci there is not a reproducible installation until the application maintainers reconcile it. Do not silently remove or regenerate that lockfile as a documentation step.

Runtime Services​

  • PostgreSQL for authentication, documents, invitations, learning content, daily progress, and Yjs update history.
  • External file storage configured by FILE_SERVER_URL and INTERNAL_SECRET.
  • A dedicated Yjs WebSocket process (development defaults to port 1234).
  • OAuth provider credentials for sign-in.
  • Optional Groq credentials for the AI inspector.

Database provisioning is a prerequisite: the checkout refers to SQL setup files, but does not track them. Obtain the actual schema/migrations from the maintainers; do not run a documentation example against a nonexistent SQL file.

Configuration​

Supply values through the environment files/process configuration expected by Vite, Better Auth and the standalone service. Keep credentials out of source control. The Yjs process uses dotenv independently; Vite's environment loading does not automatically configure another Node process.

VariablePurpose
DATABASE_URLPostgreSQL connection used by app and room persistence
BETTER_AUTH_SECRET, BETTER_AUTH_URLAuth signing and public callback base
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETGitHub OAuth
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETGoogle OAuth
FILE_SERVER_URL, INTERNAL_SECRETInternal byte storage endpoint and key
GROQ_API_KEYOptional server AI key; user keys can be entered in AI settings
DAILY_TIMEZONEDaily date/rollover zone; default Africa/Johannesburg
YJS_WS_PORT, YJS_COMPACT_AFTERRoom-service port and compaction threshold; defaults 1234/1000
YJS_WS_UPSTREAMNitro proxy target; default host.docker.internal:1234
VITE_YJS_WS_URLOptional public build-time WebSocket URL override, not a secret
NITRO_PRESETDeployment adapter selection

The existing container workflow names GitHub secrets HUB_CLIENT_ID/ HUB_CLIENT_SECRET, while auth code reads GITHUB_CLIENT_ID/ GITHUB_CLIENT_SECRET. Resolve this configuration mismatch in deployment; the documentation does not change the application workflow.

Run and Build​

npm run dev

This launches vite dev and node yjs/yjs-server.mjs concurrently. Use Vite's printed URL for the web app; verify both processes start with the required environment. The direct development room URL defaults to ws://localhost:1234.

npm run build
npm start

npm start runs the built Node application only. Start/deploy the separate Yjs service as well for collaboration. For deployment differences, see the physical view.

Documentation Site​

git clone https://sdp.ms.wits.ac.za/sudoers-2/fla-docs--.git
cd fla-docs--
npm ci
npm start

Docusaurus serves the documentation, not the application backend. Its production build uses npm run build. Sprint 4 is the current documentation; earlier sprint snapshots are selected using the version dropdown.