README.md (4532B)
1 # My Heats 2 Live heats, scoring and leaderboard for sport events. 3 4 This React application was build using [Vite](https://vitejs.dev) (`npm create 5 vite@latest . --template react`) and the following core componentes: 6 * [`react-router-dom`](https://reactrouter.com) for routing between the React 7 components 8 * [`postgres`](https://github.com/porsager/postgres#realtime-subscribe) for 9 realtime subscription to leaderboard changes with PostgreSQL publication 10 * [`react-select`](https://react-select.com) for the selectbox widgets 11 12 ## Running the App 13 ```bash 14 # Install dependencies 15 npm install 16 17 # Export all required environment variables, see example in .env 18 19 # Start authentication API backend 20 npm run api 21 22 # Start app frontend 23 npm run dev 24 ``` 25 26 See `./docs` for more detailed developer documentation. 27 28 ## Scoring and ranking logic 29 The scoring and ranking logic is defined in `utils.js` inside the `rankByHeat` 30 function. Following ranking options can be selected. Rank by: 31 * Start number: Rank by athlete start number 32 * Best heat: Rank by best heat (and by least worst if "best" is equally good) 33 * Worst heat: Ranks worst heats only (no further comparison by best if equally 34 bad) 35 * Total: Ranks by sum of all selected heats 36 37 ## Database schema 38 The PostgreSQL database schema is stored in the `schema` folder and can be 39 created using plain psql. 40 41 To update the schema files from the current database, use (example for table 42 `startlist`): 43 ```bash 44 pg_dump -h 127.0.0.1 -U postgres -t 'public.startlist' --schema-only > schema/04-startlist.sql 45 ``` 46 47 The views and functions from `./schema/99-init-db.sql` are required. Among 48 others, this enables [PostgreSQL 49 publication](https://www.postgresql.org/docs/current/logical-replication-publication.html) 50 so the leaderboard can automatically update scores when they are created or 51 changed by judges ("realtime functionality"). 52 53 ### Schema migrations 54 Schema migrations are documented in the [CHANGELOG.md](./CHANGELOG.md) and are 55 required when upgrading from older releases. 56 57 Example upgrade from v0.8 to v0.9: 58 ```bash 59 psql < schema/migrations/01-heats.sql 60 ``` 61 62 ## Authentication with magic links 63 Authentication of judges is performed using Magic links. 64 65 Sign up process for new judges: 66 * The judge is required to have a valid email address 67 * Judges can be invied to the scoring backend by invite only (table `public.judges`) 68 69 Sign in process: 70 * For sign in, the judge enters her email adress and receives a login link 71 * The login information is stored in the browser session until sign out 72 73 ## Real-time replication 74 The database user needs permissions to start `walsender`. Otherwise you 75 encounter this error: 76 ``` 77 must be superuser or replication role to start walsender 78 ``` 79 80 To give the permissions: 81 ```sql 82 ALTER USER myheats REPLICATION; 83 \du 84 ``` 85 86 Also, the wal level needs to be set to `logical` in the postgresql config. 87 Otherwise, this is the error message you will receive: 88 ``` 89 logical decoding requires wal_level >= logical 90 ``` 91 92 To set it in `postgresql.conf`: 93 ``` 94 # postgresql.conf 95 wal_level = logical # minimal, replica, or logical 96 ``` 97 98 Restart database. 99 100 ## Bulk import/export 101 Use direct postgres database access: 102 ```bash 103 psql -h 127.0.0.1 -U postgres 104 ``` 105 106 To import data from local csv: 107 ```sql 108 \copy public.scores from 'scores_rows.csv' DELIMITER ',' CSV HEADER; 109 ``` 110 111 To export data to local csv: 112 ```sql 113 \copy public.scores to 'scores_rows.csv' DELIMITER ',' CSV HEADER; 114 ``` 115 116 ## Settings 117 The following settings can be applied in `/settings` as parameters to configure 118 the them and appearance of the leaderboard: 119 * `style`: The color of the navigation elements, one of `yellow`, `blue` or `red` 120 * `logoUrl`: Add url to a logo to replace the default logo in the footer 121 * `showLogo`: Set to "false" to hide the logo in the footer 122 * `showVersion`: Set to "false" to hide the version in the footer 123 * `title`: Set header title for the event 124 125 ## Development & contributions 126 For a list of contributors see the [AUTHORS.md](./AUTHORS.md). 127 128 * All source code is available in this repository. Contributions are always 129 welcome! Pull requests at https://pr.in0rdr.ch/repos/myheats 130 * A [Kanban 131 board](https://board.in0rdr.ch/public/board/c445667f1c999857f6149cad967fa44f196f2e9fef02069c5f5136e036dd) 132 documents plans, todos and decisions for further development of the project. 133 134 ## Community and support 135 For question and support visit 136 [#p0c/libera](https://web.libera.chat/gamja/#p0c) on IRC. 137 138 ## License 139 This work uses the MIT License. See [LICENSE](./LICENSE) for details.