ts3web/README.md

# README

[![Build Status](https://drone.myservermanager.com/api/badges/varakh/ts3web/status.svg)](https://drone.myservermanager.com/varakh/ts3web)

_ts3web_ is a free and open-source web interface for TeamSpeak 3 instances.

The minimalistic approach of this application is intentional.

* Docker images available on [https://hub.docker.com/r/varakh/ts3web](https://hub.docker.com/r/varakh/ts3web)
* Sources are hosted on [https://git.myservermanager.com/varakh/ts3web](https://git.myservermanager.com/varakh/ts3web)

There are many TeamSpeak 3 web interfaces out. Why should I pick _ts3web_? Free, simple, stateless, easy to extend,
standard bootstrap theme.

The main git repository is hosted at
_[https://git.myservermanager.com/varakh/ts3web](https://git.myservermanager.com/varakh/ts3web)_.
Other repositories are mirrors and pull requests, issues, and planning are managed there.

Contributions are very welcome!

## Limitations

TeamSpeak has a detailed interface for permissions and uploading files, therefore the following features are not
supported:

* uploading files (only viewing and deleting, use the official client for uploading)
* editing permissions (only viewing, use the client for editing)

## READ BEFORE USING

This web interface makes **heavy use of TeamSpeak 3 server query commands**. Please ensure that you _increase query
limits_ and whitelist the requesting IP address to a `whitelist.txt` when in a docker environment (see below).

Please read the next sections carefully.

## Setup

_ts3web_ can be deployed natively or via docker. It's recommended to use docker with docker-compose. Those steps are
outlined below.

### docker-compose

General remarks:

* By default, `/var/www/html/application/config/env` is used for bootstrapping necessary configuration, can be set to another parent directory with `ENV_DIR` in docker environment variable, e.g., `ENV_DIR=/data`
* By default, `/var/www/html/application/data/snapshots` is used for storing snapshots, path can be changed in the `env` file with `snapshot_dir`
* By default, `/var/www/html/application/log` is used for storing and reading logs, path can be changed in the `env` file with `log_dir`
* Other `env` configuration values are outlined in the [env example](./config/env.example) file which is also present in the default docker image.

It's recommended to use the `network=HOST` option for the docker setup. You can also work with other network modes. 
In that case you'll need to assign static networks though for the web interface to work.

Let's start with the `network=HOST` example. Create the docker volumes first. You could also use automatically generated 
ones by the `docker-compose` file, you would need to remove the `external: true` in the `volumes` section of the 
`docker-compose.yml` then.

Create the external volumes:

```shell
docker volume create ts3-vol
docker volume create ts3web-vol
```

Paste the example `docker-compose.yml` into a file on your machine:

```yaml
version: '2.1'
networks:
  teamspeak:
    external: false

services:
  app:
    container_name: teamspeak_app
    image: teamspeak:latest
    volumes:
      - ts3-vol:/var/ts3server
    # ports are all public here in the HOST mode example
    environment:
      - TS3SERVER_LICENSE=accept
      - TS3SERVER_IP_WHITELIST=/var/ts3server/whitelist.txt
    restart: unless-stopped
    network_mode: "host"

  web:
    container_name: teamspeak_web
    image: varakh/ts3web:latest
    volumes:
      - ts3web-vol:/data
    environment:
      # volume needs to contain the env file!
      - ENV_DIR=/data
    ports:
      - 127.0.0.1:8181:80
    depends_on:
      - app
    restart: unless-stopped
    networks:
      - teamspeak

volumes:
  ts3-vol:
  ts3web-vol:
```

Let's populate our docker volumes **before** we start!

```shell
docker run -d --rm --name ts3web_creator -v ts3web-vol:/mnt alpine tail -f /dev/null
docker exec -it ts3web_creator sh

# edit the env file to your liking, you can start by copying the env.example of this git repository 
# in config/ and edit to your liking
#
# IMPORTANT: the teamspeak_host should point to your public ip address and
# it must be whitelisted inside the teamspeak server itself
vi env

# create necessary directories and set permissions
mkdir -p /data/log
touch /data/log/application.log
mkdir -p /data/snapshots
chown -R 65534:65534 /data

# exit the container
exit

# on the host system, stop the creator container
docker stop ts3web_creator
```

Let's populate the teamspeak container with a proper `whitelist.txt` file. **Ensure that you're 
[whitelisting](#whitelist.txt) the IP from which the webinterface will issue commands inside the teamspeak server.

```shell
docker run -d --rm --name ts3_creator -v ts3-vol:/mnt alpine tail -f /dev/null
docker exec -it ts3_creator sh

# edit the whitelist.txt file at /var/ts3server/whitelist.txt
# it should contain the following entries
#
# 127.0.0.1
# ::1
# your-public-ip
#
vi /var/ts3server/whitelist.txt

# exit the container
exit

# on the host system, stop the creator container
docker stop ts3_creator
```

Maybe you like to copy valid license files into the `ts3-vol` docker volume before stopping.

_Finally_, start the stack with `docker-compose up -d`. Please see the **Reverse proxy** section for a nginx example.

### Reverse proxy

Here's an example on how to configure a reverse proxy for _ts3web_ docker container

```shell
root   .../public;
index index.php;   

# enable and setup if you have a certificate (highly recommended)
#ssl on;
#ssl_certificate fullchain.pem;
#ssl_certificate_key privkey.pem; 

rewrite_log on;

location / {
try_files $uri $uri/ @ee;
}

location @ee {
rewrite ^(.*) /index.php?$1 last;
}

# php fpm
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
include        fastcgi_params;
}
```

## Native application

**Prerequisite**: `php`, `composer` and probably `php-fpm` installed on the server.

### Install

* Clone repository
* Change directory to project home
* Execute `composer install`
* `composer install`
* Do the configuration by coping the `env.example` file to `env` inside the `config/` directory
* Use a web server _or_ run directly via the embedded PHP server: `php -S localhost:8080 -t public public/index.php`.
* Point your browser to [localhost:8080](http://localhost:8080)
* Apply any [whitelist.txt](#whitelist-text-file) changes if you configured `teamspeak_host` differently than `localhost`

### Upgrade

* Change directory to project home
* `git pull` (be sure to be on `master` branch!)
* `composer update`

## Troubleshooting / F.A.Q

<a name="flood"></a>
### How to overcome server query limit?

You might get one of these messages:

> I always get `flood client` message when clicking anywhere in the web interface.

The web UI uses query commands _a lot_ to the TeamSpeak server! When your instance is up and running, you should be 
able to change the following setting, e.g. directly in your database (MySQL or sqlite).

```ini
serverinstance_serverquery_flood_commands = 9999
serverinstance_serverquery_max_connections_per_ip = 999
serverinstance_serverquery_flood_time = 1
```

<a name="whitelist"></a>
> I always get `TSException: Error: host isn't a ts3 instance!` when selecting a server.

You're probably on a docker environment and the TeamSpeak server is queried through the web UI which
resides behind a web server, so the TeamSpeak server thinks that the _remote web server IP address_ invokes the query
commands and thus blacklists it.

You need define an exception for you server's IP in a [`whitelist.txt`](#whitelist.txt) file and include it in
your TeamSpeak application.

You can also add the desired IP to `query_ip_allowlist.txt` and `query_ip_whitelist.txt` within the TeamSpeak 3 Server
data directory.

<a name="whitelist.txt"></a>
### What do I need to type into the `whitelist.txt`?

The following illustrates a valid `whitelist.txt` file which can be used for the above `docker-compose` setups. You need
to replace `your-public-ip` with the TeamSpeak's public IP address if required or remove the fixed internal docker IP if
you're on `network=HOST` mode.

```
127.0.0.1
::1
10.5.0.5
your-public-ip
```

<a name="dockerperms"></a>
### I always get `no write permissions` or something similar when trying to save snapshots or when a log entry is created.

This probably happens when you're in the docker setup. Ensure that host binds have permissions set up properly and also files inside any
docker volume has the correct permissions. The user which is used in the docker container is `nobody` with id `65534`.

Change owner permissions recursively with `chown -R 65534:65534 /path/to/dir`.

## Development

Contributions are welcome!

### Release

* Set a date in the `CHANGELOG.md` file
* Remove `SNAPSHOT` from the version in `Constants.php`
* Adapt the occurrences inside the `.drone.yml` with the new version
* Build the docker image from the project
    * if necessary, add GitHub access token to let composer pull dependencies within the image correctly:
      add `&& composer config --global --auth github-oauth.github.com <token> \` before the `composer install` command,
      where `<token>` can be retrieved from [GitHub settings](https://github.com/settings/tokens)
    * execute `sudo docker build --no-cache -t varakh/ts3web:latest .` to build
    * publish it
* Tag the release git commit and create a new release in the VCS web interface

### Prepare next development cycle

1. Branch from `master` to `release/prepare-newVersionNumber`
2. Add `-SNAPSHOT` to the version in `Constants.php` and increase it
3. Adapt the occurrences inside the `.drone.yml` with the new version
4. Merge this branch to `patch` or/and `dev` respectively
5. Don't forget to clean up all created branches

### Helpers

Attributes can be defined when including `table`, `keyvalues` and `form` templates of twig. This helps to generate
tables and forms without the need to specify all attributes.

```
hiddenDependingOnAttribute // hides a row depending on a value in a table
hiddenColumns // hides an entire column depending on a key in a table
links // generates a link for a specific cell in a table or keyvalue
additional_links // generates extra columns in a table
filters // applies filters depending on a key in a table or key value view
attributesEditable // define editable attributes in the key value view
fields // define fields for a form
```

See example usage in the folder `View/bootstrap4`.

### Translations

- This app uses Symfony Translator. It's bootstrapped in `Util\BootstrapHelper` and locales are placed
  under `data/locale/` and the data table `.json` file, e.g. `en_dataTable.json`. Adjust to your needs or help
  translating.
- Form fields (name/id should be the same) are also translated. For a field named `content` or `ConT enT`
  translate `form_field_content`.

### Theme

Themes can be chosen in the `env` file by editing the `theme` variable. Templates are mapped to the corresponding view
folder in `src/View/<themeName>`. `.css`, `.js` and other style files like `.ttf` or `.woff2` for fonts should be placed
in `public/theme/<themeName>` and accessed accordingly. See an example in `src/View/boostrap4/layout.twig`.