Tokora quickstart: install in minutes

TOKORA — QUICKSTART
===================

Self-hosted queue & token management with a waiting-room display board — PHP +
MySQL/SQLite. Manages a waiting queue only (no payments, no cards, no crypto,
no personal health records).


REQUIREMENTS
------------
  - PHP 8.1+ (tested on 8.3) with extensions: pdo, pdo_sqlite (or pdo_mysql)
  - MySQL 5.7+ / MariaDB 10+ OR SQLite 3 (SQLite requires no extra setup)
  - A web server (Apache with mod_rewrite, or Nginx with try_files)
  - No Composer packages, no API keys, no external services, no CDN.


SHARED HOSTING / CPANEL (RECOMMENDED FOR MOST BUYERS)
------------------------------------------------------
1. Upload the contents of the `app/` folder to your web root (e.g. public_html/)
   or a subdirectory (e.g. public_html/tokora/).

2. Make sure this directory is writable by PHP:
     data/

   Via cPanel File Manager: right-click -> Permissions -> set to 755 or 775.

3. Visit https://yourdomain.com/install/ in your browser.

4. Fill in the installer:
     - Database: choose MySQL (fill in host/name/user/pass) or SQLite (no setup)
     - Organization name (shown on the board) + timezone
     - Your admin name, email + password
   The installer seeds a few starter services and counters so you can start
   straight away.

5. Log in, then:
     - Setup > Services: name each line and give it a token prefix (P, C, R…)
     - Setup > Counters: name each desk; bind it to a service or "Any service"
     - Open the Display board and Ticket kiosk (links in the sidebar)


THE PUBLIC SCREENS (NO LOGIN)
-----------------------------
  - DISPLAY BOARD   /board   — put this on a lobby TV. Shows now-serving per
                               counter, each line's length, and recent calls.
                               Auto-refreshes (meta refresh + a tiny offline
                               polling script; falls back gracefully with no JS).
  - TICKET KIOSK    /kiosk   — put this on a tablet by the door. A visitor taps
                               a service and gets the next number.
  - TICKET STATUS   /t/{id}  — a visitor can watch their own place in line from
                               their phone; it updates until they're called.


RUNNING THE DESK (STAFF)
------------------------
  - Dashboard shows today's lines and every counter. Click a counter to open its
    console.
  - "Call next" completes whoever the counter was serving and calls the oldest
    waiter for its service (or the oldest across all services for an "Any" desk).
  - "Served" / "No-show" resolve the current caller; "Recall" re-announces them.


TRY IT WITH DEMO DATA FIRST
---------------------------
  - In Settings, click "Load demo data" for a sample clinic (3 services, 3
    counters, a day of tokens across every status), then "Reset all data".
  - Or from the command line:  php bin/demo.php
      (login: admin@tokora.app with the one-time password it prints)


VPS / SELF-HOSTED (APACHE)
--------------------------
  <VirtualHost *:80>
    DocumentRoot /var/www/tokora/app
    <Directory /var/www/tokora/app>
      AllowOverride All
      Require all granted
    </Directory>
  </VirtualHost>


DOCKER (QUICK TEST)
-------------------
  docker run --rm -p 8080:8080 \
    -v "$(pwd)/app:/var/www/html" \
    -w /var/www/html \
    php:8.3-cli \
    php -S 0.0.0.0:8080 router.php

  Then visit http://localhost:8080/install/


REPORTS & EXPORTS
-----------------
  - Daily report > pick a day > Export PDF or CSV.
  - The PDF is a genuine, dependency-free document (summary + per-service).
  - The CSV lists the day's tokens and is safe to open in Excel / Google Sheets
    (formula-injection hardened).


POST-INSTALL SECURITY CHECKLIST
--------------------------------
  [ ] config.php is protected (the .htaccess does this automatically)
  [ ] data/ is not web-accessible (.htaccess blocks it automatically)
  [ ] Use HTTPS in production
  [ ] Keep PHP updated


LOOKING AFTER IT (from 4.0)
---------------------------
  * Updates: open Updates in the menu, save your license key once, press Check for updates.
    Reaching 4.0 from 3.x is the last update by hand: replace the files; config.php and data/ stay.
  * Sample data: the installer offers to start with a sample; remove it later with one click.
  * Backups: "Back up once a day by itself" is on by default (/restore); add an S3-compatible bucket there for
    a copy somewhere else. The Health page (/health) says whether all of this is working.
  * On Nginx: use the server block in the manual ("On Nginx: keep data/ private", https://ownware.io/p/tokora/manual);
    it opens the installer and keeps data/ private.
  * One-line install for technical owners:
    curl -fsSL https://ownware.io/install.sh | sh -s -- tokora <your license key>

NOTES
-----
  * Token numbers are sequential per service and reset each day automatically —
    no cron job is required.
  * Tokora manages a waiting queue only. It processes no payments and stores no
    cards, bank details, cryptocurrency, or personal health records.