An unofficial web-based implementation of the Hitster card game by Koninklijke Jumbo B.V.
View Stable Demo
·
View Development Demo
·
Report Bug
·
Request Feature
Table of Contents
Hitster is a music quiz card game developed and released by Koninklijke Jumbo B.V. Its very easy to play and is fun to play for literally everyone. Here is a short rundown of how to play:
- Everyone receives a hit card at the beginning of a game. A hit contains information about a song, containing its title, the artist and year when it was released.
- A short snippet of a hit is played to you. You'll have to guess if it was released either before or after the hit that you already have in your collection.
- If you guessed correctly, you'll earn the hit card and add it to your collection. The game will continue to the next player.
- Next time it's your turn, you'll be played a hit again, but this time, you'll have to guess if it was released either before your earliest hit's release year, between your two hits, or after the latest hit release. Guess correctly to earn yourself another hit card, grow your collection, but also make it harder to guess your next hit correctly.
There is more to it, like tokens you can earn by also guessing title and artist of a hit, and paying them to intercept your opponents by correcting their guesses to earn their hit for your own. But see for yourself, you don't need to register, just visit the demo and play a game with at least one of your friends.
... and loads more
Hitster consists of multiple separate projects:
- a server component deploying a REST API, written in Rust and based on Rocket
- a client application responsible for displaying the game's UI and interacting with the server, written in React and TypeScript
- a cli helper to run some tasks that aren't necessary to have within the server itself
Follow these steps to get a dev environment ready to run the project locally.
The project is supposed to run inside a Docker container. As such, it holds a Dockerfile which builds the project. It also pushes docker images whenever a commit is created. If you just want to spin it up locally to give it a try, run the following command with Docker installed:
docker run -p 8000:8000 tonironaldbarth/hitster:latestMultiple containers are available to choose from:
| tag | purpose |
|---|---|
| latest | newest stable version |
| dev | bleeding edge dev (might break unpredictably, contains all newest features that haven't been merged into stable) |
| <release_name> | a specific release that won't change anymore, see the list of available tags for your possible options |
The Docker containers currently only automatically gets built for amd64 and arm64, feel free to open an issue or pull request to add/request more build targets.
If you want to build the container for yourself, clone the repository, open a command line and navigate into the project directory, then run the following commands:
docker build -t hitster .
docker run -p 8000:8000 hitsterThe Hitster application will be accessible on localhost Port 8000 afterwards. Please see below for a list of environment variables to further configure the container.
The Docker container exposes some volumes which you can connect to to persist your data. The following table holds information about the available paths:
| Path | Description |
|---|---|
| /hitster.sqlite | the database holding registered user information etc |
| /hits | the folder where downloaded hits are stored |
You can launch a docker container by specifying your volumes like follows:
docker run -v hits:/hits -v hitster.sqlite:/hitster.sqlite -p 8000:8000 tonironaldbarth/hitsterAn easier way of launching a Hitster server is by utilizing Docker Compose. You can find an example docker-compose.yml file below:
services:
hitster:
image: tonironaldbarth/hitster:latest
### comment above line and uncomment if you want to build from source
#build:
# context: .
restart: unless-stopped
volumes:
- ./hitster.sqlite:/hitster.sqlite
- ./hits:/hits
environment:
- ROCKET_SECRET_KEY=generate_me_a_secret_key
- ROCKET_ADDRESS=0.0.0.0
- ALTCHA_KEY=GENERATE_ME_ANOTHER_SECRET_KEY
ports:
- "8000:8000"Setting up the project locally will requires several tools, which need to be accessible on your PATH environment variable to be called without having to know their exact path. We strictly recommend to stick to a Docker-based development environment instead. Should you want to still go for a local setup, please find the instructions below.
You'll need the following tools to be installed:
- Node.js v20
- Rust: we recommend to install the most recent stable version, that'll most likely be the version we're developing with as well
- FFMpeg: we recommend installing the yt-dlp compatible static builds from its corresponding GitHub repository
- FFMpeg-normalize
- (optional) yt-dlp. Make sure to check the section on yt-dlp to enable the usage of yt-dlp (disabled by default)
Ensure that everything is working by running the following test commands and ensuring proper output:
node -v
rustup show
ffmpeg -version
ffmpeg-normalize
yt-dlp -vStart by cloning this repository. Open a command line and navigate into the folder of the cloned repository. Afterwards, run those commands to build all components of the Hitster project:
- client:
cd client npm install npm run build cd ..
- cli:
cargo build -p hitster-cli
- server:
cargo run
Please note that you'll need to specify a certain set of environment variables when running the application locally in order for it to start. You can find the list of environment variables below.
When trying to run the server, you might ask yourself, how do I get this hitster.sqlite file everyone is talking about? You might be seeing errors like these:
error: error returned from database: (code: 14) unable to open database fileAll you need to do to fix this is provide an empty file, the server will populate all the necessary database info it needs. To do this, just create an empty text file and call it hitster.sqlite, or if on a Unix-based command line, use:
touch hitster.sqliteChances are high you won't ever need an administrator account, as the game can be played without even registering a user. If you want to create your own packs or hits though, or fix already existing ones, you'll need to have at least one administrator account registered. You can easily do that with the help of the hitster cli tool.
When running Hitster locally, run the following command:
cargo run -p hitster-cli -- users create -a <username>Replace <username> with the username of choice. You'll be prompted to input a password and your new user will be created. You should be able to login via the web interface and use this account to make changes to the Hitster database.
When running Hitster in Docker, you can run the following command to create a new administrative user:
docker run -v hitster.sqlite:/hitster.sqlite --entrypoint /hitster/cli tonironaldbarth/hitster:latest users create -a <username>If running in Docker Compose, the command would look something like this:
docker compose run --entrypoint /hitster/cli hitster users create -a <username>Replace <username> with the username of choice. You'll be prompted to input a password and your new user will be created. You should be able to login via the web interface and use this account to make changes to the Hitster database.
By default, the Hitster server will try to download songs from YouTube with the help of a rust-native library called rusty_ytdl. This requires less dependencies to be running alongside the Hitster server and thus is preferred when setting up Hitster locally. It however is also less reliable as it runs into YouTube blocking mechanisms more frequently. If you therefore want to use yt-dlp instead, you'll need to build the Hitster server with the yt_dl feature enabled. Navigate into the server directory and run:
cargo run --features yt_dlThis will enable yt-dlp support as a fallback for the rust-native way of downloading songs from YouTube. If you want to skip the native way of downloading alltogether, you can disable default features and just enable the yt_dl feature alone, as follows:
cargo run --no-default-features --features yt_dlThis also is the default within the Docker container.
The project can be configured through environment variables. Environment variables can be populated in different ways, depending on how you are running it.
- (local only) by setting them via EXPORT on Linux or SET on Windows, e.g.:
export DATABASE_URL=~/sqlite://hitster.sqlite
- (local only) by specifying them inside a .env file, which will have to be placed inside the server directory of this repository. A file could look like this:
DATABASE_URL=sqlite://hitster.sqlite
- (Docker only) handing them to the docker run command via the -e switch, e.g.:
docker run -e DATABASE_URL=sqlite://hitster.sqlite -p 8000:8000 tonironaldbarth/hitster
The following environment variables are available. Required variables are set to default values when running via docker.
| variable | required | meaning |
|---|---|---|
| DATABASE_URL | yes | location of the database file, must be in the format of sqlite://path_to_file.sqlite, /hitster.sqlite in Docker containers by default |
| ALTCHA_KEY | no | a random secret key necessary to generate altcha challenges, it isn't required to run the server, but it'll be required if you're planning to allow user registration and other form submissions |
| CLIENT_DIRECTORY | no | specify the location of the compiled client files, usually not needed in Docker, ./client in local mode |
| DOWNLOAD_DIRECTORY | no | download location of the songs downloaded by the server, /hits in Docker containers by default, ./hits otherwise |
In addition to those custom environment variables, the server can be further tweaked by populating Rocket-specific environment variables. Some important variables would be ROCKET_ADDRESS to specify the address to bind to the server, as well as ROCKET_PORT to change the port the server is listening on. For a permanently deployed service, we recommend setting the ROCKET_SECRET_KEY environment variable to a randomly generated key, which will allow users to stay logged in even if the server restarts. Please see the list of rocket environment variables on the rocket website.
The server component of this game comes with a REST API that in turn is used by the client to control all aspects of the game and all that comes with it. We're trying our best to keep the REST API properly documented and strongly motivate you to develop alternative game frontends if you're unhappy with the one provided by us.
Every self-hosted instance launches its own Swagger API documentation under the /swagger-ui route, as well as a Rapidoc API documentation under /rapidoc. Here are the links to the API docs provided by our demo instances:
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the GNU General Public License, version 3. See LICENSE for more information.
Toni Barth - ToniBarth@troet.cafe - contact@toni-barth.online
Project Link: https://github.com/Timtam/hitster