Installation using docker

Customizing the application

On the file docker/.env you can customize easily some properties described on the configuration. Please take a look at the next sections to understand what can/must be changed:

Using a custom domain

By default, I am assuming that you are deploying this application as a docker container on a server in the cloud. That means that probably you already have a domain that you must set on the application. Please, update machine_domain variable on docker/.env to match your existing domain.

machine_domain=<your-domain>
[...]
#Frontend
protocol=https
websocket_protocol=https

Use a https protocol as the system will automatically generate a certificate for you. For additional details, please visit Let's Encrypt and section Using REVERSE PROXY and Generating SSL.

The reverse proxy uses the SSL port, which is the default port for the HTTPS protocol. Therefore, you can access the tool through your domain using https://<your-domain>/

Using localhost

You can deploy the application in your desktop computer for testing it also with docker. It is not recommended for a real environment but is an easy way to check the state of the art on this application and if it fits to your needs or not.

Note: When accessing the tool via the localhost configuration without a domain, your computer will be isolated, and certain features will be unavailable. Actions such as using QR codes to connect to scoreboards or operating multiple devices for each shiaijo will not work because they are unable to communicate with your server.

On docker/.env set:

machine_domain=localhost
[...]
#Frontend
protocol=http
websocket_protocol=http

Since the system will be installed on localhost, SSL certificates are not required.

In the docker/docker-compose.yml file, comment out the following lines by adding a # at the beginning:

kendo-tournament-rproxy:
# - "traefik.http.routers.dashboard.tls.certresolver=https"

kendo-tournament-frontend:
# - "traefik.http.routers.kendo-tournament-frontend.tls.certresolver=https"

kendo-tournament-backend:
# - "traefik.http.routers.kendo-tournament-backend.tls.certresolver=https"
# - "traefik.http.routers.kendo-tournament-backend-api.tls.certresolver=https"

Additionally, change https to http in these lines:

kendo-tournament-rproxy:
- "traefik.http.routers.dashboard.entrypoints=http"

kendo-tournament-frontend:
- "traefik.http.routers.kendo-tournament-frontend.entrypoints=http"

kendo-tournament-backend:
- "traefik.http.routers.kendo-tournament-backend.entrypoints=http"
- "traefik.http.routers.kendo-tournament-backend-api.entrypoints=http"

For the subsequent steps, you may opt to either utilize the reverse proxy or remove it in order to execute the tool on localhost.

Utilizing localhost with a reverse proxy

Should you wish to maintain the reverse proxy operational, it is necessary to configure it to avoid using certificates and HTTPS connections. Remove all SSL configurations from the reverse proxy by commenting out the relevant line in /docker/traefik/Dockerfile.

#ADD config/* /config/

This prevents copying SSL configurations to the server. Then, disable all HTTP to HTTPS redirections in /docker/traefik/traefik.yml by commenting out the following lines:

entryPoints:
  http:
    address: ":80"
#    http:
#      redirections:
#        entryPoint:
#          to: https
#          scheme: https
#          permanent: true
#  https:
#    address: ":443"

This adjustment will ensure that Traefik disregards any SSL connections.

An example of the final result can be found here.

Utilizing localhost without a reverse proxy

Alternatively, you may choose to bypass the reverse proxy configuration entirely and access the containers directly. To do so, expose port 8080 and add the container to the external network.

  kendo-tournament-rproxy:
      [...]
      networks:
      - containers
      - external
      ports:
      - "8080:8080"
      [...]

We would like to express our gratitude to user dim-geo for providing this straightforward approach.

An example of this configuration can be found here.

Final steps with or without a reverse proxy

Optionally, to prevent the tool from running continuously on your computer when not desired, modify the docker/docker-compose.yml file as follows:

kendo-tournament-rproxy:
  # restart: always
  restart: unless-stopped

kendo-tournament-frontend:
  # restart: always
  restart: unless-stopped

kendo-tournament-backend:
  # restart: always
  restart: unless-stopped

This configuration allows you to stop the tool at any time by executing docker-compose stop within its docker directory.

Finally, deploy the application using the usual docker-compose command:

docker-compose build && docker-compose up -d

Tip: If you have attempted to access localhost with HTTPS enabled, it is possible that the redirect from HTTPS to HTTP has been cached in your browser. Ensure that the final URL in your browser is http://localhost and that it does not change to https://localhost automatically. If this is the case, temporarily disable your browser cache or clear it completely. You can also try using a different browser or switch to incognito mode.

Finally, verify that all services are running properly by executing the command:

docker ps

Alternatively, wait for at least 30 seconds to confirm that all services have started.

When accessing the tool via localhost without SSL and using the HTTP protocol, use the URL http://localhost/.

Utilizing Localhost with the Latest Code

You may compile the most recent version of the tool if you prefer not to wait for the next official release. Should you wish to operate it within a Docker container, you must directly include the compiled code and integrate it into the container. An example is available at the following link: here.

Troubleshooting

If you continue to experience issues when accessing localhost, please follow these steps:

1. Verify that you have completed all the instructions outlined above. Consider downloading a fresh copy of the tool to ensure all configuration files are correct.

2. Confirm that the backend is operational by checking the logs using the command docker logs kendo-tournament-backend. Look for a ### Server started ### message within the log, typically appearing shortly after the tool’s title.

3. Try accessing the backend directly at http://localhost/kendo-tournament-backend to confirm if the API is reachable.

4. Make sure that any third-party software, such as antivirus programs or firewalls, is not interfering with the application. Adjust their settings accordingly if necessary.

Using a different database engine.

If you want to use a different database engine, add the correct jar dependency with the jdbc connector in backend/libraries. Configure these specific variables in the .env file:

database_type=postgresql  (hsqldb, h2, oracle, mysql, postgresql, ...)
database_name=database
database_password=mypass
database_user=myuser
database_port=5432

Security passwords

Variable jwt_secret is used for encrypting JWT token related to the REST API authorization. Please change it and avoid using the default one. If jwt_secret is left empty, the system will generate a random one on start. Random is more secure, but any user will be forced to log in into the system again if the server is restarted.

Variable database_encryption_key will encrypt some personal data information stored on a database, to ensure a higher level of privacy. If you want to check the content of your database using any other external software, please leave this variable with a blank value. Otherwise, change the default value to any other that only you know. Remember that if you set your database to be encrypted, the property database_populate_default_data must be set to never, as the pre-made script has data that is not encrypted and therefore incompatible with your encryption.

Using REVERSE PROXY and SSL certificates

Currently, we are using Traefik that handles the SSL certificate generation. No extra action is needed if you have your own domain. Wait for a few minutes and ensure that your domain is redirected to this application and Traefik will handle it.

Changing Traefik dashboard password

Remember that you can check the Traefik status accessing to its dashboard. By default, is protected by user admin and password 0b186336d5. I recommend changing it as soon as possible. For this purpose, you can use htpasswd tool on a Unix system:

echo $(htpasswd -nB user) | sed -e s/\\$/\\$\\$/g

The sed command is due to the docker-compose needs to scape any $ character to $$. Ensure that is the case in your output.

Finally, update the docker-compose.yml file with the obtained password, replacing the next line with the content obtained from the value obtained on the previous step:

  - "traefik.http.middlewares.auth.basicauth.users=admin:<<put here your new hashed password>>"

Regenerate the docker container with a docker-compose build --no-cache kendo-tournament-rproxy && docker-compose up -d kendo-tournament-rproxy and the new password will be used.