JTS3ServerMod-dockerized/README.md

<h1 align="center">JTS3ServerMod-dockerized</h1>

<p align="center">
  <a href="https://drone.nick-slowinski.de/NickSlowinski/JTS3ServerMod-dockerized" title="Build Status">
    <img alt="Status of the published version" src="https://img.shields.io/drone/build/NickSlowinski/JTS3ServerMod-dockerized?label=build%20%28released%29&logo=build%20%28released%29&server=https%3A%2F%2Fdrone.nick-slowinski.de">
    <img alt="Status of the developer version" src="https://img.shields.io/drone/build/NickSlowinski/JTS3ServerMod-dockerized/dev?label=build%20%28dev%29&logo=build%20%28released%29&server=https%3A%2F%2Fdrone.nick-slowinski.de">
  </a>
  <a href="https://hub.docker.com/r/nickslowinski/jts3servermod-dockerized" title="Docker Hub">
    <img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/nickslowinski/jts3servermod-dockerized">
    <img alt="Docker Image Size" src="https://img.shields.io/docker/image-size/nickslowinski/jts3servermod-dockerized/dev">
  </a>
</p>

## What is it? And can I eat it?

First: No, you can't eat it. But you can use it as a dockerized variant of the [JTS3ServerMod](https://www.stefan1200.de/forum/index.php?topic=2.0).  
JTS3ServerMod is a fairly perfect bot for your TeamSpeak server – written in Java. Because some people need/want a Docker image and the original author Stefan1200 does not provide one, I am here to help you.

## Supported architectures

- linux/amd64
- linux/arm/v7
- linux/arm/v6
- linux/arm64/v8

## Running the image

You can run the image as any other image, it automatically exposes the required minimum volume with the config files. For more details how to configure the JTS3ServerMod, please see its official docs, either by mapping the _documents_ volume or by visiting [its online documentation](https://www.stefan1200.de/documentation/jts3servermod/readme.html).

### Possible volume mapping

| Volume    | Path in the container      | Description                                                                                                 |
| --------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| config    | `/JTS3ServerMod/config`    | Config files                                                                                                |
| documents | `/JTS3ServerMod/documents` | Documentation files of the bot + original _changelog.txt_ and _readme.txt_ (+german variant)                |
| plugins   | `/JTS3ServerMod/plugins`   | Additional plugins can be uploaded in this directory - please follow the original docs of the JTS3ServerMod |

### Examples

#### A container with named volumes and a given name

```
docker run --name jts3servermod-dockerized -v jts3_config:/JTS3ServerMod/config -v jts3_documents:/JTS3ServerMod/documents -v jts3_plugins:/JTS3ServerMod/plugins nickslowinski/jts3servermod-dockerized:dev
```

#### A container with mounted volumes and a given name

```
docker run --name jts3servermod-dockerized -v /some/path/on/host/jts3_config:/JTS3ServerMod/config -v /some/path/on/host/jts3_documents:/JTS3ServerMod/documents -v /some/path/on/host/jts3_plugins:/JTS3ServerMod/plugins nickslowinski/jts3servermod-dockerized:dev
```

## Common issues

### The container stops immediately after starting

If the log looks something like the following, **then this does not mean that the image is defective!** You have to configure the bot and restart it, as long as you have not made any errors in the configuration, the bot will start successfully.

```
JTS3ServerMod 6.5.7 (31.01.2020) Instance Manager started...
Operating System : Linux (version: 5.14.10-200.fc34.x86_64 / arch: amd64)
Used Java Version: 1.8.0_282 (path: /usr/lib/jvm/java-1.8-openjdk/jre)
Current directory: /JTS3ServerMod
Writing InstanceManager log file to: /JTS3ServerMod/JTS3ServerMod_InstanceManager.log
Loading InstanceManager config file from: /JTS3ServerMod/config/JTS3ServerMod_InstanceManager.cfg
bot1: Writing bot log file to: /JTS3ServerMod/JTS3ServerMod_server1.log
bot1: Virtual bot instance "bot1" starts now (build 6508)
bot1:
bot1: **********************************************************************************
bot1: It seems you never touched the config, check file config/server1/JTS3ServerMod_server.cfg
bot1: **********************************************************************************
bot1:
bot1: Unable to connect to Teamspeak 3 server at ts3.server.net!
bot1: java.net.UnknownHostException: ts3.server.net
bot1: Virtual bot instance "bot1" stopped
Stopping all bots, please wait...
```

### Error loading JTS3ServerMod InstanceManager configuration file

Example log:

```
JTS3ServerMod 6.5.7 (31.01.2020) Instance Manager started...
Operating System : Linux (version: 5.10.17-v8+ / arch: aarch64)
Used Java Version: 1.8.0_282 (path: /usr/lib/jvm/java-1.8-openjdk/jre)
Current directory: /JTS3ServerMod
Writing InstanceManager log file to: /JTS3ServerMod/JTS3ServerMod_InstanceManager.log
JTS3ServerMod InstanceManager configuration file does not exists, check file path:
/JTS3ServerMod/config/JTS3ServerMod_InstanceManager.cfg
Error while loading the JTS3ServerMod InstanceManager config file, read error messages above to know more. Quitting now...
```

So far, this error could always be traced back to outdated software versions. To fix this error, you only need to update the system, including Docker and its dependencies. If the error still occurs after a successful update and a subsequent system restart, please [create a ticket](https://git.nick-slowinski.de/NickSlowinski/JTS3ServerMod-dockerized/issues/new).

## Getting Help

Please use the [issue tracker](https://git.nick-slowinski.de/NickSlowinski/JTS3ServerMod-dockerized/issues) to search for your problem (and use different phrases). If you ensure your problem is unique, [create a ticket](https://git.nick-slowinski.de/NickSlowinski/JTS3ServerMod-dockerized/issues/new) and provide helpful information like logs, what you have done, useful parts of your config, etc.  
If you found a security vulnerability, please contact me privately via e-mail at nick@nick-slowinski.de (and encrypt the message with [my PGP key](https://keys.openpgp.org/search?q=nick%40nick-slowinski.de) if possible). Security vulnerabilities are prioritized, and a public announcement is made after a fix is released.

## Contributing

Contributions to this project are welcome. If you found a way to improve this project, feel free to open a [ticket](https://git.nick-slowinski.de/NickSlowinski/JTS3ServerMod-dockerized/issues/new) and discuss what you want to achieve (so you do not waste your time, if it is out of the scope).  
A full contributors guide will be published at a later time.

## Authors

- [Maintainers](MAINTAINERS)
- [Contributors](CONTRIBUTORS)

## License

This project is licensed under the _GNU General Public License_. See [LICENSE](LICENSE) for the complete license text.

## Frequently Asked Questions

### Are you planning to release images for other architectures?

Not for now, but if somebody requests another architecture (via the issue tracker), I will look into it, what I can do.

### Why do you use openjdk8 and not 11?

I want to keep the image as small as possible, therefor OpenJDK 8 was chosen over 11. As long as OpenJDK 8 is supported and is sufficient for this project, it will be used.

### Is the JTS3ServerMod Hosting Edition supported?

Not at the moment. I can build an image for it (Stefan1200 exposes the downloads for it), but there is no way I could test it because I do not have a license key for it.

### What changes have been made to the original code?

1. The following files have been moved to the _documents_ subfolder: `changelog.txt`, `readme.txt`, `readme_deutsch.txt`
2. The standard log paths in the `JTS3ServerMod_InstanceManager.cfg` have been adapted so that the logs are accessible via a volume.

The adjustments were necessary so that the corresponding files could be made accessible via volumes without having to "publish" the `.jar` file or other critical files.