Improve README and make pipeline run with building testing docker image on every branch

Co-authored-by: Varakh <varakh@varakh.de>
Reviewed-on: #2

.drone.yml

@@ -1,28 +1,49 @@
 ---
 kind: pipeline
 type: docker
-name: default
+name: build and test
 
 trigger:
     event:
         include:
             - push
+steps:
+    -   name: test build docker image
+        image: plugins/docker
+        environment:
+            REVISION: ${DRONE_COMMIT_SHA}
+            CREATED: ${DRONE_BUILD_CREATED}
+            SOURCE_URL: ${DRONE_GIT_HTTP_URL}
+        settings:
+            purge: true
+            dry_run: true
+            repo: varakh/ts3web
+            username:
+                from_secret: dockerhub_user
+            password:
+                from_secret: dockerhub_key
+            tags:
+                - ${DRONE_COMMIT_SHA}
+
+---
+kind: pipeline
+type: docker
+name: publish
+
+trigger:
+    event:
+        include:
             - cron
     branch:
         - master
 
-environment: &default_environment
-    REVISION: ${DRONE_COMMIT_SHA}
-    CREATED: ${DRONE_BUILD_CREATED}
-    SOURCE_URL: ${DRONE_GIT_HTTP_URL}
-    # also change in 'tags' of build docker
-    TS3WEB_VERSION: 2.2.5
-
 steps:
-    -   name: build docker image
+    -   name: publish docker image
         image: plugins/docker
         environment:
-            <<: *default_environment
+            REVISION: ${DRONE_COMMIT_SHA}
+            CREATED: ${DRONE_BUILD_CREATED}
+            SOURCE_URL: ${DRONE_GIT_HTTP_URL}
         settings:
             purge: true
             repo: varakh/ts3web
@@ -32,9 +53,10 @@ steps:
                 from_secret: dockerhub_key
             tags:
                 - latest
-                - 2.2.5
+                # adapt for new releases
+                - 2.2.7-SNAPSHOT
 
-    -   name: notify
+    -   name: notify about publish
         image: drillster/drone-email
         settings:
             subject: "Build failed"
@@ -50,8 +72,4 @@ steps:
         when:
             status:
                 - failure
----
-kind: signature
-hmac: f575a63bd85c4a95593be5e077373216fbd50ad57e6b3d1db56f950e881ed2a5
 
-...

README.md

@@ -2,14 +2,14 @@
 
 [![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.
+_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,
+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
@@ -45,12 +45,14 @@ 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.
+* 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, and it will be the only example in this `README` file.
+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 create the docker volumes first. You could also use automatically generated ones by the `docker-compose` file, you
+Let's start with the `network=HOST` example. Create the docker volumes first. You could also use automatically generated 
-would need to remove the `external: true` in the `volumes` section of the `docker-compose.yml` then.
+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:
 
@@ -107,12 +109,11 @@ 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
+# edit the env file to your liking, you can start by copying the env.example of this git repository 
-cp /var/www/html/application/config/env /data/env
+# in config/ and edit to your liking
-
-# 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
+# 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
@@ -128,7 +129,8 @@ exit
 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](#whitelisttextfile).
+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
@@ -156,7 +158,7 @@ _Finally_, start the stack with `docker-compose up -d`. Please see the **Reverse
 
 ### Reverse proxy
 
-Here's an example on how to configure a reverse proxy for the web interface docker container
+Here's an example on how to configure a reverse proxy for _ts3web_ docker container
 
 ```shell
 root   .../public;
@@ -195,16 +197,15 @@ include        fastcgi_params;
 * Change directory to project home
 * Execute `composer install`
 * `composer install`
-* Do the configuration by coping the `env.example` file (see information above)
+* 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
+* Apply any [whitelist.txt](#whitelist-text-file) changes if you configured `teamspeak_host` differently than `localhost`
-  than `localhost`
 
 ### Upgrade
 
 * Change directory to project home
-* `git pull`
+* `git pull` (be sure to be on `master` branch!)
 * `composer update`
 
 ## Troubleshooting / F.A.Q
@@ -216,8 +217,8 @@ 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
+The web UI uses query commands _a lot_ to the TeamSpeak server! When your instance is up and running, you should be 
-setting, e.g. directly in your database (MySQL or sqlite).
+able to change the following setting, e.g. directly in your database (MySQL or sqlite).
 
 ```ini
 serverinstance_serverquery_flood_commands = 9999
@@ -232,12 +233,26 @@ You're probably on a docker environment and the TeamSpeak server is queried thro
 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`](#whitelisttextfile) file and include it in
+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.
 
@@ -246,20 +261,6 @@ docker volume has the correct permissions. The user which is used in the docker
 
 Change owner permissions recursively with `chown -R 65534:65534 /path/to/dir`.
 
-<a name="whitelisttextfile"></a>
-### 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!
@@ -268,6 +269,7 @@ Contributions are welcome!
 
 * 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,
@@ -280,8 +282,9 @@ Contributions are welcome!
 
 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
+3. Adapt the occurrences inside the `.drone.yml` with the new version
-4. Don't forget to clean up all created branches
+4. Merge this branch to `patch` or/and `dev` respectively
+5. Don't forget to clean up all created branches
 
 ### Helpers