ts3web/README.md

README

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
• Sources are hosted on 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. 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 file which is also present in the default docker image.

It's recommended to use the network=HOST option for the docker setup, and it will be the only example in this README file.

Let's 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:

docker volume create ts3-vol
docker volume create ts3web-vol

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

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!

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

# inside the container, edit the env by copying the example to the docker volume mount path at /data/env
cp /var/www/html/application/config/env /data/env

# edit the env file to your liking
#
# the teamspeak_host should point to your public ip address and 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. See ensure that you're whitelisting the IP from which the webinterface will issue commands.

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 the web interface docker container

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 (see information above)
• 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
• Apply any whitelist.txt changes if you configured teamspeak_host differently than localhost

Upgrade

• Change directory to project home
• git pull
• composer update

Troubleshooting / F.A.Q

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! 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).

serverinstance_serverquery_flood_commands = 9999
serverinstance_serverquery_max_connections_per_ip = 999
serverinstance_serverquery_flood_time = 1

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 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.

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.

What's a whitelist.txt and why do I need it?

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 'host' mode.

127.0.0.1
::1
10.5.0.5
your-public-ip

Development

Contributions are welcome!

Release

• Set a date in the CHANGELOG.md file
• Remove SNAPSHOT from the version in Constants.php
• 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
  • 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. Merge this branch to patch or/and dev respectively
4. 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.