# JSIDPlay2 Server Setup and Maintenance

This guide explains how to set up and maintain the JSIDPlay2 server.

---

## Easy Setup using Caddy and Docker

The easiest way to set up the JSIDPlay2 server is by using Caddy and Docker. This method automates much of the
configuration, including HTTPS support and server requirements.

- **Caddy Configuration:** See [src/main/caddy](../src/main/caddy) for the web server setup and reverse proxy
  configuration.
- **Docker Configuration:** See [src/main/docker](../src/main/docker) for Dockerfiles and Docker Compose configurations
  to run the server and its dependencies (MySQL, NGINX) in containers.
- **Jenkins Configuration:** See [src/main/jenkins](../src/main/jenkins) for Jenkins job configurations used for
  continuous integration and deployment, including beta releases, server updates, and online content deployment.

### Component Details

#### Caddy

[Caddy](https://caddyserver.com/) acts as a modern, high-performance web server and reverse proxy. In this setup, it:

- Automatically manages SSL/TLS certificates via Let's Encrypt.
- Redirects insecure HTTP traffic to HTTPS.
- Serves as a reverse proxy for the JSIDPlay2 backend services.
- Serves static files for the web interface and music collections.
- Handles port 8443 for backward compatibility.

#### Docker Compose Modules

The [src/main/docker](../src/main/docker) directory contains several Docker Compose files, each serving a specific
purpose. You can use them in combination as needed:

- **`docker-compose.server.linux.yml`**: The server part.
    - **`jsidplay2-server`**: Runs the main RESTful API server.
    - **`mysql`**: Provides the database for WhatsSID audio recognition, AutoPlay sessions, and debug.
    - **`nginx`**: Configured with the RTMP module to support C64 video streaming using HLS.
- **`docker-compose.whatssid.linux.yml`**: A specialized configuration for maintenance.
    - Runs the `RecordingTool` to update the WhatsSID database if a new HVSC version gets
      released (Fills hvscXXX database).
- **`docker-compose.ui.linux.yml`**: Runs the JSIDPlay2 JavaFX desktop UI inside a container.
- **`docker-compose.netsiddev.linux.yml`**: Runs the NetSID device emulator GUI in a container.

#### Jenkins CI/CD Jobs

Jenkins automates the lifecycle of the project. The [src/main/jenkins](../src/main/jenkins) directory contains:

- **Beta Releases (`config-linux.xml`, `config-win.xml`, `config-mac.xml`, etc.)**:
    - Automatically build and package the latest code for all supported platforms.
    - Ensure that every commit to the repository results in a functional, ready-to-test beta version.
- **Server Updates (`config-server-linux.xml`)**:
    - Monitors the master branch and automatically redeploys the live JSIDPlay2 server when changes are detected.
    - Ensures the online service is always running the latest version.
- **Extra Online Content (`config-online-content.xml`)**:
    - Automates the deployment of large music collections (HVSC, CGSC) and other static resources, if the internet
      provides new versions.
    - Handles the complex task of synchronizing the server's local storage with the latest online content releases.

---

## Credentials

Basic authentication is used when calling the services of the RESTful API server with the following pre-configured
credentials:

* **Username:** `jsidplay2`
* **Password:** `jsidplay2!`

You can change the password or add an administrative user (e.g., to grant access to private music collections) via an
external configuration file named `tomcat-users.xml` located in your home directory.

**Example `tomcat-users.xml`:**

```xml

<tomcat-users>
    <role rolename="admin"/>
    <role rolename="user"/>

    <user name="jsidplay2" password="jsidplay2!" roles="user"/>
    <user name="admin" password="admin" roles="admin"/>
</tomcat-users>
```

## Maintenance and Updates

### HVSC Update (or CGSC, GameBase64, etc.)

When a new HVSC version is released:

1. Launch Jenkins Job: `config-online-content.xml`
2. Launch Jenkins Job: `config-server.xml`

### WhatsSID Update (Audio Fingerprinting)

To update the audio recognition database for a new HVSC version:

1. Update version references in `pom.xml`, `README.md`, and launch configurations.
2. Prepare directories contained in and change versions in compose.whatssid.linux.yml. The last HVSC recorded directory
   is always to be used as the previous directory for the next HVSC version (for the first recording, there is no
   previous directory).
3. Launch `docker-compose.whatssid.linux.yml`
4. Verify HVSC music counts with information of the HVSC website.
   ```sql
   SELECT count(DISTINCT InfoDir) FROM MusicInfo;
   ```