https://github.com/openttd/survey-web
Results and information about OpenTTD's automated opt-in survey
https://github.com/openttd/survey-web
Last synced: 10 days ago
JSON representation
Results and information about OpenTTD's automated opt-in survey
- Host: GitHub
- URL: https://github.com/openttd/survey-web
- Owner: OpenTTD
- License: gpl-2.0
- Created: 2023-05-04T18:49:18.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-12T07:18:38.000Z (11 days ago)
- Last Synced: 2025-05-12T08:41:07.193Z (11 days ago)
- Language: HTML
- Homepage:
- Size: 21.3 MB
- Stars: 1
- Watchers: 6
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenTTD's Survey website
[](https://github.com/OpenTTD/survey-web/blob/main/LICENSE)
This is the [website](https://survey.openttd.org) to show the results of the survey analysis and the information and privacy statement of the participation.
This is a [Jekyll](https://jekyllrb.com/) website, and is served by nginx as a static site.
## Development
### Survey results
To summarize survey results, the Python application `analysis` processes a bundle of JSONs and outputs another JSON with the summary.
To run it:
- `git clone https://github.com/OpenTTD/BaNaNaS` to get the BaNaNaS dataset (needed to resolve NewGRFs).
- Create a Python virtual env run `pip install -r requirements.txt`.
- `python3 -m analysis ` to run the analysis.
### Running a local server
If you do not want to run a server, but just build the current site, replace `serve` with `build` in the examples below.
Under `_site` Jekyll will put the compiled result in both `serve` and `build`.
- Follow [jekyll installation](https://jekyllrb.com/docs/installation/)
- Run `bundle install`
- Run `JEKYLL_ENV=production jekyll serve`
### Workers
The survey makes use of a Cloudflare worker to process the survey results and to hand out new survey-keys.
- Install [wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/)
- Navigate into `workers` folder
- Run `npm install`
- Run `npx wrangler dev --local src/index.js`
## Survey keys
Security in Open Source is difficult, as all code is open for everyone to read, and everyone can compile their own binary.
This is especially an issue if the backend wants to trust information received from a client.
There is no waterproof method, but the survey makes use of a key to somewhat know the survey result was generated by a trusted client.
Make no mistake: it is trivial for anyone with ill intentions to retrieve the survey key from an official binary, and reuse it to submit fraudulent survey results.
There are other mitigations in place to decrease the impact of this.
Mostly, the survey key is used to know when the survey result was created by, for example, a development build.
These are very likely to have no key at all.
That all said, survey keys are simply [JWT](https://jwt.io)s, signed with HS256.
This signature is used to validate that a survey result is, most likely, send by a trusted client.
### Getting a survey key
When an official binary is built, the GitHub workflow requests a new survey key.
This is done by sending the OpenTTD version together with a signature of that request (based on RSA private/public key).
The public key of this RSA is under `workers/src/public_keys/`.
The private key is, of course, a secret within the GitHub workflow of the project itself.
Based on this, the worker can validate that the request is valid, and create a survey key based on the request.
This is then used by the GitHub workflow to embed in the binaries.
### Patch-pack support
The survey fully supports patch-packs, including the ability for them to get a survey key.
First, an RSA private/public key is needed.
This can be generated in various of ways, but for example via `openssl`:
- Private key: `openssl genrsa -out privatekey.pem 2048`
- Public key (based on the private key above): `openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem`
Now the public key (without the lines starting with `----`) needs to be added under `workers/src/public_keys/` and `workers/src/public_keys/index.js` needs to be adjusted to import the new key.
The name of the file under `public_keys/` is important, as this is part of the URL to retrieve a new survey key.
Requests to this URL have to be signed with the private key of which the public key is in this repository.
Make a Pull Request out of this change, and point to where your patch-pack can be found etc.
Next, the contents of the private key file (`privatekey.pem`) needs to be added as the `SURVEY_SIGNING_KEY` secret to the GitHub Actions of your repository.
Now for the last part, add the `SURVEY_TYPE` variable to the GitHub Actions of your repository matching the name of the file above.
The patch-pack can now safely create new survey keys.
See OpenTTD's workflow (`release-source.yml`) for more details exactly how.