Installation Instructions

These notes describe a public-safe setup flow. They intentionally omit private hostnames, private IP addresses, exact server paths, SSH targets, user data, and credentials.

Requirements

  • Node.js.
  • npm.
  • A server or workstation capable of running a Node.js web app.
  • SQLite support through the Node sqlite3 package.
  • A reverse proxy if the app is hosted behind a custom domain or subpath.
  • Docker or another process manager for long-running deployment, if running outside local development.

Local Development

Install dependencies:

npm install

Create a local environment file for development or deployment:

JWT_SECRET="replace-with-a-strong-secret" NODE_ENV="development"

Start the app:

npm start

By default, the server listens on port 3000 and serves the frontend and API from the same Express app.

First Run

  1. Start the server.
  2. Confirm the SQLite database directory is created.
  3. Open the app in a browser using the configured host and subpath.
  4. Log in or register using an invite flow.
  5. Use the admin console to create competitions, tasks, roles, and household members.
  6. Set the system timezone if the default does not match the deployment.
  7. Test task claiming from a competitor account.

The source currently contains development-oriented seed behavior for an empty database. A production deployment should replace that with an explicit setup flow or remove the seed data before public reuse.

Deployment Notes

The project is designed to run as a self-hosted Node.js service behind a reverse proxy. The current deployment approach uses containers and separate environments for testing, acceptance, and production, selected by branch-aware deployment tooling.

For a public or reusable deployment guide:

  1. Build a container image or install dependencies on the target server.
  2. Set NODE_ENV=production.
  3. Set a strong JWT_SECRET through the runtime environment.
  4. Persist the SQLite data directory outside the application image.
  5. Configure the reverse proxy to serve the app under the intended subpath.
  6. Ensure the PWA manifest, icons, and service worker are served with correct MIME types.
  7. Keep database files and environment files out of version control.

Verification Checklist

  • The app loads from the configured route.
  • Login and invite registration work.
  • Authenticated API calls include a valid token.
  • Admin-only routes are blocked for non-admin users.
  • A competition can be created.
  • A task can be created with score, duration, and activation time.
  • A competitor can claim an active task only once per cycle.
  • Scoreboards update after claims and manual score adjustments.
  • Player history and score-card views load.
  • Championship scoreboards load when competitions are linked.
  • Translation strings load for English, Turkish, and Dutch.
  • The app can be installed as a PWA on a supported mobile browser.
  • Static assets continue to load after service-worker caching.

Public Release Cleanup

Before publishing this as a reusable repository or detailed deployment guide:

  • Remove or replace development seed accounts.
  • Do not publish real household members, email addresses, invite codes, database files, or screenshots containing private data.
  • Do not publish private hostnames, local IP addresses, SSH targets, or exact deployment paths.
  • Confirm the production token-signing secret is provided only through a private environment variable.
  • Add tests for task cycle boundaries, duplicate claims, password policy, scoring, and role checks.
  • Add documented backup and restore steps for the SQLite database.