Update documentation for API, configuration, and model
API.md: - Add export formats (JSON, XML, EGF, FFG, CSV) - Document /explain endpoint for pairing analysis - Add PUT /standings for freezing - Improve parameter documentation - Fix typos (regitration -> registration, #tip -> #tid) configuration.md: - Add property loading hierarchy - Document SSL/TLS configuration - Add OAuth provider configuration - Add ratings.path property - Include example configurations model.md: - Complete entity diagram with Team, external IDs - Document all tournament types (PAIRGO, RENGO, TEAM) - Add TimeSystem types and parameters - Document all pairing parameters - List all 39 tiebreak criteria - Add external database (AGA, EGF, FFG) documentation
This commit is contained in:
Claude Brisson
@@ -2,39 +2,96 @@
|
||||
|
||||
Pairgoth general configuration is done using the `pairgoth.properties` file in the installation folder.
|
||||
|
||||
## environment
|
||||
Properties are loaded in this order (later overrides earlier):
|
||||
|
||||
Controls the running environment: `dev` for development, `prod` for distributed instances.
|
||||
1. Default properties embedded in WAR/JAR
|
||||
2. User properties file (`./pairgoth.properties`) in current working directory
|
||||
3. System properties prefixed with `pairgoth.` (command-line: `-Dpairgoth.key=value`)
|
||||
|
||||
## Environment
|
||||
|
||||
Controls the running environment.
|
||||
|
||||
```
|
||||
env = prod
|
||||
```
|
||||
|
||||
## mode
|
||||
Values:
|
||||
- `dev` - Development mode: enables CORS headers and additional logging
|
||||
- `prod` - Production: for distributed instances
|
||||
|
||||
Running mode: `standalone`, `client` or `server`.
|
||||
## Mode
|
||||
|
||||
Running mode for the application.
|
||||
|
||||
```
|
||||
mode = standalone
|
||||
```
|
||||
|
||||
## authentication
|
||||
Values:
|
||||
- `standalone` - Both web and API in a single process (default for jar execution)
|
||||
- `server` - API only
|
||||
- `client` - Web UI only (connects to remote API)
|
||||
|
||||
Authentication: `none`, `sesame` for a shared unique password, `oauth` for email and/or oauth accounts.
|
||||
## Authentication
|
||||
|
||||
Authentication method for the application.
|
||||
|
||||
```
|
||||
auth = none
|
||||
```
|
||||
|
||||
When running in client or server mode, if `auth` is not `none`, the following extra property is needed:
|
||||
Values:
|
||||
- `none` - No authentication required
|
||||
- `sesame` - Shared unique password
|
||||
- `oauth` - Email and/or OAuth accounts
|
||||
|
||||
### Shared secret
|
||||
|
||||
When running in client or server mode with authentication enabled:
|
||||
|
||||
```
|
||||
auth.shared_secret = <16 ascii characters string>
|
||||
```
|
||||
|
||||
## webapp connector
|
||||
This secret is shared between API and View webapps. Auto-generated in standalone mode.
|
||||
|
||||
Pairgoth webapp connector configuration.
|
||||
### Sesame password
|
||||
|
||||
When using sesame authentication:
|
||||
|
||||
```
|
||||
auth.sesame = <password>
|
||||
```
|
||||
|
||||
## OAuth configuration
|
||||
|
||||
When using OAuth authentication:
|
||||
|
||||
```
|
||||
oauth.providers = ffg,google,facebook
|
||||
```
|
||||
|
||||
Comma-separated list of enabled providers: `ffg`, `facebook`, `google`, `instagram`, `twitter`
|
||||
|
||||
For each enabled provider, configure credentials:
|
||||
|
||||
```
|
||||
oauth.<provider>.client_id = <client_id>
|
||||
oauth.<provider>.secret = <client_secret>
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
oauth.ffg.client_id = your-ffg-client-id
|
||||
oauth.ffg.secret = your-ffg-client-secret
|
||||
oauth.google.client_id = your-google-client-id
|
||||
oauth.google.secret = your-google-client-secret
|
||||
```
|
||||
|
||||
## Webapp connector
|
||||
|
||||
Pairgoth webapp (UI) connector configuration.
|
||||
|
||||
```
|
||||
webapp.protocol = http
|
||||
@@ -44,7 +101,10 @@ webapp.context = /
|
||||
webapp.external.url = http://localhost:8080
|
||||
```
|
||||
|
||||
## api connector
|
||||
- `webapp.host` (or `webapp.interface`) - Hostname/interface to bind to
|
||||
- `webapp.external.url` - External URL for OAuth redirects and client configuration
|
||||
|
||||
## API connector
|
||||
|
||||
Pairgoth API connector configuration.
|
||||
|
||||
@@ -56,28 +116,91 @@ api.context = /api
|
||||
api.external.url = http://localhost:8085/api
|
||||
```
|
||||
|
||||
## store
|
||||
Note: In standalone mode, API port defaults to 8080 and context to `/api/tour`.
|
||||
|
||||
Persistent storage for tournaments, `memory` (mainly used for tests) or `file`.
|
||||
## SSL/TLS configuration
|
||||
|
||||
For HTTPS connections:
|
||||
|
||||
```
|
||||
webapp.ssl.key = path/to/localhost.key
|
||||
webapp.ssl.cert = path/to/localhost.crt
|
||||
webapp.ssl.pass = <key passphrase>
|
||||
```
|
||||
|
||||
Supports `jar:` URLs for embedded resources.
|
||||
|
||||
## Store
|
||||
|
||||
Persistent storage for tournaments.
|
||||
|
||||
```
|
||||
store = file
|
||||
store.file.path = tournamentfiles
|
||||
```
|
||||
|
||||
## smtp
|
||||
Values for `store`:
|
||||
- `file` - Persistent XML files (default)
|
||||
- `memory` - RAM-based (mainly for tests)
|
||||
|
||||
SMTP configuration. Not yet functional.
|
||||
The `store.file.path` is relative to the current working directory.
|
||||
|
||||
## Ratings
|
||||
|
||||
### Ratings directory
|
||||
|
||||
```
|
||||
smtp.sender =
|
||||
smtp.host =
|
||||
ratings.path = ratings
|
||||
```
|
||||
|
||||
Directory for caching downloaded ratings files.
|
||||
|
||||
### Rating sources
|
||||
|
||||
For each rating source (`aga`, `egf`, `ffg`):
|
||||
|
||||
```
|
||||
ratings.<source> = <url or file path>
|
||||
```
|
||||
|
||||
If not set, ratings are auto-downloaded from the default URL. Set to a local file path to freeze ratings at a specific date.
|
||||
|
||||
Example to freeze EGF ratings:
|
||||
```
|
||||
ratings.egf = ratings/EGF-20240115.json
|
||||
```
|
||||
|
||||
### Enable/disable ratings
|
||||
|
||||
```
|
||||
ratings.<source>.enable = true | false
|
||||
```
|
||||
|
||||
Whether to display the rating source button in the Add Player popup.
|
||||
|
||||
```
|
||||
ratings.<source>.show = true | false
|
||||
```
|
||||
|
||||
Whether to show player IDs from this rating source on the registration page.
|
||||
|
||||
Defaults:
|
||||
- For tournaments in France: FFG enabled and shown by default
|
||||
- Otherwise: all disabled by default
|
||||
|
||||
## SMTP
|
||||
|
||||
SMTP configuration for email notifications. Not yet functional.
|
||||
|
||||
```
|
||||
smtp.sender = sender@example.com
|
||||
smtp.host = smtp.example.com
|
||||
smtp.port = 587
|
||||
smtp.user =
|
||||
smtp.password =
|
||||
smtp.user = username
|
||||
smtp.password = password
|
||||
```
|
||||
|
||||
## logging
|
||||
## Logging
|
||||
|
||||
Logging configuration.
|
||||
|
||||
@@ -86,34 +209,48 @@ logger.level = info
|
||||
logger.format = [%level] %ip [%logger] %message
|
||||
```
|
||||
|
||||
## ratings
|
||||
Log levels: `trace`, `debug`, `info`, `warn`, `error`
|
||||
|
||||
Ratings configuration. `<ratings>` stands for `egf` or `ffg` in the following.
|
||||
Format placeholders: `%level`, `%ip`, `%logger`, `%message`
|
||||
|
||||
### freeze ratings date
|
||||
## Example configurations
|
||||
|
||||
If the following property is given:
|
||||
### Standalone development
|
||||
|
||||
```
|
||||
ratings.<ratings>.file = ...
|
||||
```properties
|
||||
env = dev
|
||||
mode = standalone
|
||||
auth = none
|
||||
store = file
|
||||
store.file.path = tournamentfiles
|
||||
logger.level = trace
|
||||
```
|
||||
|
||||
then the given ratings file will be used (it must use the Pairgoth ratings json format). If not, the corresponding ratings will be automatically downloaded and stored into `ratings/EGF-yyyymmdd.json` or `ratings/FFG-yyyymmdd.json`.
|
||||
### Client-server deployment
|
||||
|
||||
The typical use case, for a big tournament lasting several days or a congress, is to let Pairgoth download the latest expected ratings, then to add this property to freeze the ratings at a specific date.
|
||||
|
||||
### enable or disable ratings
|
||||
|
||||
Whether to display the EGF or FFG ratings button in the Add Player popup:
|
||||
|
||||
```
|
||||
ratings.<ratings>.enable = true | false
|
||||
**Server (API):**
|
||||
```properties
|
||||
env = prod
|
||||
mode = server
|
||||
auth = oauth
|
||||
auth.shared_secret = 1234567890abcdef
|
||||
api.port = 8085
|
||||
store = file
|
||||
store.file.path = /var/tournaments
|
||||
logger.level = info
|
||||
```
|
||||
|
||||
Whether to show the ratings player IDs on the registration page:
|
||||
|
||||
**Client (Web UI):**
|
||||
```properties
|
||||
env = prod
|
||||
mode = client
|
||||
auth = oauth
|
||||
auth.shared_secret = 1234567890abcdef
|
||||
oauth.providers = ffg,google
|
||||
oauth.ffg.client_id = your-ffg-id
|
||||
oauth.ffg.secret = your-ffg-secret
|
||||
oauth.google.client_id = your-google-id
|
||||
oauth.google.secret = your-google-secret
|
||||
webapp.port = 8080
|
||||
api.external.url = http://api-server:8085/api
|
||||
```
|
||||
ratings.<ratings>.show = true | false
|
||||
```
|
||||
|
||||
For a tournament in France, both are true for `ffg` by default, false otherwise.
|
||||
|
||||
Reference in New Issue
Block a user