2019-01-18 16:49:49 +00:00
# README
2021-05-20 23:05:38 +00:00
2023-03-25 08:28:18 +00:00
[![Build Status ](https://drone.myservermanager.com/api/badges/varakh/ts3web/status.svg )](https://drone.myservermanager.com/varakh/ts3web)
2019-08-07 15:56:21 +00:00
ts3web is a free and open-source web interface for TeamSpeak 3 instances.
2021-05-20 23:05:38 +00:00
2019-08-07 15:56:21 +00:00
The minimalistic approach of this application is intentional.
2018-04-03 11:56:20 +00:00
2019-11-08 20:39:43 +00:00
* Docker images available on [https://hub.docker.com/r/varakh/ts3web ](https://hub.docker.com/r/varakh/ts3web )
2022-07-05 15:46:47 +00:00
* Sources are hosted on [https://git.myservermanager.com/varakh/ts3web ](https://git.myservermanager.com/varakh/ts3web )
2018-04-03 11:56:20 +00:00
2021-05-20 23:05:38 +00:00
There are many TeamSpeak 3 web interfaces out. Why should I pick ts3web? Free, simple, stateless, easy to extend,
standard bootstrap theme.
2019-01-18 23:59:24 +00:00
2022-07-05 20:09:17 +00:00
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!
2021-05-24 13:40:31 +00:00
## 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).
2019-01-18 16:49:49 +00:00
2021-05-24 13:40:31 +00:00
Please read the next FAQ section carefully!
## F.A.Q
2021-02-07 13:46:40 +00:00
< a name = "flood" > < / a >
2021-05-20 23:05:38 +00:00
2021-05-24 13:40:31 +00:00
### How to overcome server query limit?
2021-05-20 23:05:38 +00:00
2021-05-24 13:40:31 +00:00
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).
```ini
serverinstance_serverquery_flood_commands = 9999
serverinstance_serverquery_max_connections_per_ip = 999
serverinstance_serverquery_flood_time = 1
```
2019-01-18 23:59:24 +00:00
2021-02-07 13:46:40 +00:00
< a name = "whitelist" > < / a >
2021-05-20 23:05:38 +00:00
2021-05-24 13:40:31 +00:00
> I always get `TSException: Error: host isn't a ts3 instance!` when selecting a server.
2021-05-20 23:05:38 +00:00
2021-05-24 13:40:31 +00:00
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 ](#whitelist-text-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 (in example it's `./ts3server` where your `docker-compose.yml` resides).
2021-02-07 13:46:40 +00:00
< a name = "dockerperms" > < / a >
2021-05-20 23:05:38 +00:00
2021-05-24 13:40:31 +00:00
### I always get `no write permissions` or something similar when trying to save snapshots or when a log entry is created.
2021-05-20 23:05:38 +00:00
This probably happens when you're in the docker setup. Ensure that host binds have permissions set up properly. The user
which is used in the docker container is `nobody` with id `65534` . If, e.g. logs are host bound, then execute
2021-02-08 08:55:35 +00:00
`chown -R 65534:65534 host/path/to/log` . The same holds true for snapshots.
2019-08-07 15:56:21 +00:00
2022-01-23 10:20:18 +00:00
In the below `docker-compose.yml` file it's advised to execute the following command when you're in the _same_ directory
as the `docker-compose.yml` file resides in: `chown -R 65534:65534 env snapshots log` .
2019-08-07 15:56:21 +00:00
## Configuration
2021-02-07 13:46:40 +00:00
2021-05-20 23:05:38 +00:00
The main configuration file for the *web interface* is the `env` file located in `config/` . There's an example file
called `env.example` which you **need** to copy to `config/env` . Defaults will assume you're running your TeamSpeak
2021-02-07 13:46:40 +00:00
server on `localhost` with default port. Docker deployments can and *should* host bind this file into the container
directly and just maintain the `env` file.
2018-04-03 11:56:20 +00:00
2019-08-07 15:56:21 +00:00
## Deployment
2021-05-20 23:05:38 +00:00
The application can be deployed two different ways. See below for more information. For each deployment type a running
TeamSpeak 3 instance is a prerequisite.
2021-02-07 13:46:40 +00:00
2021-05-24 13:40:31 +00:00
In the `docker-compose.yml` [example ](#docker-compose ), a setup together with a teamspeak server instance is shown.
2021-02-07 13:46:40 +00:00
### Docker
2021-05-24 13:40:31 +00:00
**Important. Read before setup!**
2021-02-07 13:46:40 +00:00
2022-07-05 15:46:47 +00:00
- [README ](#readme )
- [READ BEFORE USING ](#read-before-using )
- [F.A.Q ](#faq )
- [How to overcome server query limit? ](#how-to-overcome-server-query-limit )
- [I always get `no write permissions` or something similar when trying to save snapshots or when a log entry is created. ](#i-always-get-no-write-permissions-or-something-similar-when-trying-to-save-snapshots-or-when-a-log-entry-is-created )
- [Configuration ](#configuration )
- [Deployment ](#deployment )
- [Docker ](#docker )
- [docker standalone ](#docker-standalone )
- [docker-compose ](#docker-compose )
- [whitelist text file ](#whitelist-text-file )
- [As native PHP application ](#as-native-php-application )
- [Install: ](#install )
- [Upgrade: ](#upgrade )
- [Reverse proxy ](#reverse-proxy )
- [Limitations ](#limitations )
- [Development ](#development )
- [Release ](#release )
- [Prepare next development cycle ](#prepare-next-development-cycle )
- [Helpers ](#helpers )
- [Translations ](#translations )
- [Theme ](#theme )
2021-02-07 13:46:40 +00:00
2021-05-24 13:40:31 +00:00
#### docker standalone
2021-05-20 23:05:38 +00:00
2021-02-07 13:46:40 +00:00
The following section outlines a manual setup. Feel free to use the provided `docker-compose.yml` as quick setup.
1. Create docker volumes for `snapshots` , `log` and `env` . Alternative is to host bind them into your containers.
2. Create a docker network with a fixed IP range or later use host network.
2021-05-20 23:05:38 +00:00
3. Depending on your setup, you need to change `teamspeak_host` of your `env` file to point either to `your IP` or to a
2021-02-07 13:46:40 +00:00
`fixed docker IP` which your teamspeak uses. `localhost` is not valid if you're using it in docker. If you're unsure,
please take a look at the example `docker-compose.yml` files.
4. Start a container using the docker image `varakh/ts3web` and provide the following bindings for volumes:
2021-02-08 16:19:59 +00:00
* `{env_file_volume|host_file}:/var/www/html/applicationconfig/env`
* `{snapshot_volume|host_folder}:/var/www/html/application/data/snapshots`
* `{log_volume|host_folder}:/var/www/html/application/log`
2021-05-24 13:40:31 +00:00
5. [Ensure that you're whitelisting the IP from which the webinterface will issue commands. ](#whitelist-text-file )
2021-05-20 23:05:38 +00:00
6. Run the `docker run` command including your settings, volumes and networks (if
any): `docker run --name teamspeak_web -v ./env:/var/www/html/application/config/env -p 8181:80 varakh/ts3web:latest`
.
2021-02-07 13:46:40 +00:00
#### docker-compose
2021-05-20 23:05:38 +00:00
In order for TeamSpeak to show correct IP and country flags, the `network_mode = "host"` is advised. It's also possible
2021-05-24 13:40:31 +00:00
to set everything up without using the host network mode and use fixed IPs.
2021-05-20 23:05:38 +00:00
The examples will use host binds for volumes. Feel free to adapt the `docker-compose.yml` template and use docker
volumes instead if you like.
2021-02-07 13:46:40 +00:00
2021-05-24 13:40:31 +00:00
Ensure to [apply permissions ](#i-always-get-no-write-permissions-or-something-similar-when-trying-to-save-snapshots-or-when-a-log-entry-is-created ) for volumes though.
2021-02-07 13:46:40 +00:00
2021-05-24 13:40:31 +00:00
< details >
< summary > docker host mode example< / summary >
2019-01-18 23:59:24 +00:00
2019-08-06 18:25:50 +00:00
```
2019-11-08 20:39:43 +00:00
version: '2.1'
2019-08-06 18:25:50 +00:00
networks:
teamspeak:
external: false
services:
app:
container_name: teamspeak_app
image: teamspeak:latest
volumes:
2021-02-07 13:46:40 +00:00
- ./ts3server:/var/ts3server
2019-08-06 18:25:50 +00:00
- ./whitelist.txt:/whitelist.txt
ports:
- 10011:10011
- 30033:30033
- 9987:9987/udp
environment:
- TS3SERVER_LICENSE=accept
- TS3SERVER_IP_WHITELIST=/whitelist.txt
restart: always
network_mode: "host"
web:
container_name: teamspeak_web
2021-02-08 08:55:35 +00:00
image: varakh/ts3web:latest
2019-08-06 18:25:50 +00:00
volumes:
2021-02-08 16:19:59 +00:00
- ./env:/var/www/html/application/config/env
- ./snapshots:/var/www/html/application/data/snapshots
- ./log:/var/www/html/application/log
2019-08-06 18:25:50 +00:00
ports:
- 127.0.0.1:8181:80
depends_on:
- app
restart: always
networks:
- teamspeak
```
2021-05-24 13:40:31 +00:00
< / details >
2018-04-03 11:56:20 +00:00
2021-05-20 23:05:38 +00:00
2021-05-24 13:40:31 +00:00
< details >
< summary > docker without host mode example< / summary >
2021-02-07 13:46:40 +00:00
```
version: '2.1'
networks:
teamspeak:
driver: bridge
ipam:
config:
- subnet: 10.5.0.0/16
gateway: 10.5.0.1
services:
app:
container_name: teamspeak_app
image: teamspeak:latest
volumes:
- ./ts3server:/var/ts3server
- ./whitelist.txt:/whitelist.txt
environment:
- TS3SERVER_LICENSE=accept
- TS3SERVER_IP_WHITELIST=/whitelist.txt
restart: always
ports:
- 10011:10011
- 30033:30033
- 9987:9987/udp
networks:
teamspeak:
ipv4_address: 10.5.0.5
web:
container_name: teamspeak_web
image: varakh/ts3web:latest
volumes:
2021-02-08 16:19:59 +00:00
- ./env:/var/www/html/application/config/env
- ./snapshots:/var/www/html/application/data/snapshots
- ./log:/var/www/html/application/log
2021-02-07 13:46:40 +00:00
ports:
- 127.0.0.1:8181:80
depends_on:
- app
restart: always
networks:
teamspeak:
ipv4_address: 10.5.0.6
```
2021-05-24 13:40:31 +00:00
< / details >
2021-02-07 13:46:40 +00:00
2021-05-24 13:40:31 +00:00
#### whitelist text file
2021-02-07 13:46:40 +00:00
2021-05-20 23:05:38 +00:00
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.
2021-02-07 13:46:40 +00:00
```
127.0.0.1
::1
10.5.0.5
your-public-ip
```
2021-05-20 23:05:38 +00:00
Now execute `docker-compose up -d` to start those containers. If you like to update, do `docker-compose down` ,
2019-08-06 18:25:50 +00:00
`docker-compose pull` and then `docker-compose up -d` again.
2019-01-18 23:59:24 +00:00
2019-08-06 18:25:50 +00:00
Your TeamSpeak 3 Server will be available under `public-server-ip:9987` . The web interface will be available on
2021-05-20 23:05:38 +00:00
`127.0.0.1:8181` . You need to add a [reverse proxy ](#reverseproxy ) and probably you also want SSL configured if you
expose it via domain. For testing purposes, change `- 127.0.0.1:8181:80` to `- 8181:80` . The web interface will then be
available under
2021-02-07 13:46:40 +00:00
`public-server-ip:8181` .
2019-01-18 23:59:24 +00:00
2021-05-24 13:40:31 +00:00
This is **not recommended** ! Secure your setup properly via [reverse proxy and SSL ](#reverse-proxy ).
2018-04-03 11:56:20 +00:00
2021-02-07 13:46:40 +00:00
### As native PHP application
2021-05-20 23:05:38 +00:00
2019-08-06 18:25:50 +00:00
**Prerequisite**: `php` , `composer` and probably `php-fpm` installed on the server.
2019-01-18 16:49:49 +00:00
2021-02-07 13:46:40 +00:00
#### Install:
2021-05-20 23:05:38 +00:00
2019-01-18 16:49:49 +00:00
* Clone repository
* Change directory to project home
2019-01-18 23:59:24 +00:00
* Execute `composer install`
2019-01-18 16:49:49 +00:00
* `composer install`
2019-11-08 21:46:24 +00:00
* Do the configuration by coping the `env.example` file (see information above)
2021-02-07 13:46:40 +00:00
* 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 )
2021-05-24 13:40:31 +00:00
* Apply any [whitelist.txt ](#whitelist-text-file ) changes if you configured `teamspeak_host` differently
2021-05-20 23:05:38 +00:00
than `localhost`
2019-01-18 16:49:49 +00:00
2021-02-07 13:46:40 +00:00
#### Upgrade:
2021-05-20 23:05:38 +00:00
2018-04-03 11:56:20 +00:00
* Change directory to project home
* `git pull`
* `composer update`
2021-02-07 13:46:40 +00:00
### Reverse proxy
2021-05-20 23:05:38 +00:00
2021-02-07 13:46:40 +00:00
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;
}
```
## 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)
2019-08-06 18:25:50 +00:00
## Development
2021-02-07 13:46:40 +00:00
If you're willing to contribute, here's some information.
2019-08-06 18:25:50 +00:00
### Release
2021-05-20 23:05:38 +00:00
2019-08-06 18:25:50 +00:00
* Set a date in the `CHANGELOG.md` file
2019-11-10 14:37:04 +00:00
* Remove `SNAPSHOT` from the version in `Constants.php`
2020-03-22 12:41:45 +00:00
* Build the docker image from the project
2021-05-20 23:05:38 +00:00
* 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 )
2021-02-08 08:55:35 +00:00
* execute `sudo docker build --no-cache -t varakh/ts3web:latest .` to build
2020-03-22 12:41:45 +00:00
* publish it
2019-11-10 14:34:32 +00:00
* 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`
2019-11-10 14:37:04 +00:00
2. Add `-SNAPSHOT` to the version in `Constants.php` and increase it
2019-11-10 14:34:32 +00:00
3. Merge this branch to `patch` or/and `dev` respectively
4. Don't forget to clean up all created branches
2018-04-03 11:56:20 +00:00
2019-08-06 18:25:50 +00:00
### Helpers
2021-05-20 23:05:38 +00:00
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.
2018-04-05 19:20:29 +00:00
```
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
```
2019-08-06 18:25:50 +00:00
See example usage in the folder `View/bootstrap4` .
2018-04-05 19:20:29 +00:00
2019-08-06 18:25:50 +00:00
### Translations
2021-05-20 23:05:38 +00:00
- 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` .
2018-04-03 11:56:20 +00:00
2019-08-06 18:25:50 +00:00
### Theme
2021-05-20 23:05:38 +00:00
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
2019-11-16 11:21:43 +00:00
in `public/theme/<themeName>` and accessed accordingly. See an example in `src/View/boostrap4/layout.twig` .