Improving documentation, not done but getting somewhere haugene#1558

README.md

@@ -4,64 +4,62 @@
 [![Docker Pulls](https://img.shields.io/docker/pulls/haugene/transmission-openvpn.svg)](https://hub.docker.com/r/haugene/transmission-openvpn/)
 [![Join the chat at https://gitter.im/docker-transmission-openvpn/Lobby](https://badges.gitter.im/docker-transmission-openvpn/Lobby.svg)](https://gitter.im/docker-transmission-openvpn/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-## Version 3.0 released - we have some breaking changes (but not much)
+This container contains OpenVPN and Transmission with a configuration
+where Transmission is running only when OpenVPN has an active tunnel.
+It has built in support for many popular VPN providers to make the setup easier.
 
-Those of you who are following this project knows that we have had some larger changes coming for a while.
-Hobby projects often get last in line for some love and care, and it took longer than I hoped but here we are.
+## Before you continue
 
-Some highlights on version 3.0:
-* We're dropping the ubuntu based image and making alpine the default (reduce double maintenance)
-* We're making Transmission settings persistent by default, removing the need for all the environment variables (but keeping support for it)
-* We're making it easier to provide your own OpenVPN (.ovpn) config file - adding scripts in the container to modify provider configs as needed to fit the container setup. (still in early stages at this point)
-* We're adding a standardized way to add scripts for doing necessary setup of a provider. This usually means to download a .ovpn config bundle, unpack it and modify it correctly to work in this container.
+The documentation for this image is here:
 
-Hopefully these changes will improve the usability of this container. As maintainers we also hope that it will free up time to keep the container up to date and stable instead of managing thousands of .ovpn files coming and going.
+https://haugene.github.io/docker-transmission-openvpn/
 
-I'll try to keep a list of breaking changes here, and add to it if we come across more:
-* The CREATE_TUN_DEVICE variable now defaults to true. Mounting /dev/net/tun will lead to an error message in the logs unless you explicitly set it to false.
-* The DOCKER_LOG variable is renamed to LOG_TO_STDOUT
-* If Transmission is running but you can't connect to torrents, try deleting (or rename to .backup) the settings.json file and restart.
+Start there if you're having issues or questions about your container.
+If you can't find your answer in the docs, please
+[search for similar issues](https://github.com/haugene/docker-transmission-openvpn/issues?q=is%3Aissue+your+issue)
+(open and closed) before opening a new one.
 
-PS: Now more than ever. We appreciate that you report bugs and issues when you find them. But as there might be more than ususal, please make sure you search and look for a similar one before possibly creating a duplicate.
-And you can always revert back to the latest tag on the 2.x versions which is 2.14. Instead of running with `haugene/transmission-openvpn` simply use `haugene/transmission-openvpn:2.14` instead. We hope that won't be necessary though :)
+Still can't figure it out? Open a new issue and share the details of your setup and some logs.
+Without that it's hard to help you. If you have a proposal for better documentation, come
+with it. PR's are always welcome! :)
 
 ## Quick Start
 
-This container contains OpenVPN and Transmission with a configuration
-where Transmission is running only when OpenVPN has an active tunnel.
-It bundles configuration files for many popular VPN providers to make the setup easier.
+These examples shows valid setups using PIA as provider for both
+docker run and docker-compose. Note that you should read some documentation
+at some point, but this is a good place to start.
+
+### Docker run
 
 ```
 $ docker run --cap-add=NET_ADMIN -d \
               -v /your/storage/path/:/data \
               -e OPENVPN_PROVIDER=PIA \
-              -e OPENVPN_CONFIG=France \
+              -e OPENVPN_CONFIG=france \
               -e OPENVPN_USERNAME=user \
               -e OPENVPN_PASSWORD=pass \
-              -e WEBPROXY_ENABLED=false \
               -e LOCAL_NETWORK=192.168.0.0/16 \
               --log-driver json-file \
               --log-opt max-size=10m \
               -p 9091:9091 \
               haugene/transmission-openvpn
 ```
 
-## Docker Compose
+### Docker Compose
 ```
 version: '3.3'
 services:
     transmission-openvpn:
+        cap_add:
+            - NET_ADMIN
         volumes:
             - '/your/storage/path/:/data'
         environment:
             - OPENVPN_PROVIDER=PIA
-            - OPENVPN_CONFIG=France
+            - OPENVPN_CONFIG=france
             - OPENVPN_USERNAME=user
             - OPENVPN_PASSWORD=pass
-            - WEBPROXY_ENABLED=false
             - LOCAL_NETWORK=192.168.0.0/16
-        cap_add:
-            - NET_ADMIN
         logging:
             driver: json-file
             options:

docs/building-blocks.md

@@ -0,0 +1,97 @@
+# The basic building blocks
+
+## The goal
+
+The core functionality of this image is to let the user run a
+VPN tunnel and Transmission as easy as possible. Transmission
+should only run while the VPN is active and any disconnect
+from VPN should cause Transmission to stop.
+
+The container should provide community best practices on how to configure the kill switch, firewall and tweaks on the
+OpenVPN configs to make it run as fast and secure as possible.
+
+## It goes like this
+
+To understand how it works, this is the most important events
+and who/what starts them.
+
+1. You start the container
+2. The container starts OpenVPN
+3. OpenVPN starts/stops Transmission
+
+When you start the container it is instructed to run a script
+to start OpenVPN. This is defined in [the Dockerfile](https://github.com/haugene/docker-transmission-openvpn/blob/master/Dockerfile).
+This script is responsible for doing initial setup and prepare what is needed for OpenVPN to run successfully.
+
+## Starting OpenVPN
+
+The main purpose of the startup script is to figure out which OpenVPN config to use.
+OpenVPN itself can be started with a single argument, and that is the config file.
+We also add a few more to tell it to start Transmission when the VPN tunnel is
+started and to stop Transmission when OpenVPN is stopped. That's it.
+
+Apart from that the script does some firewall config, vpn interface setup and possibly other
+things based on your settings. There are also some reserved script names that a user can mount/add to
+the container to include their own scripts as a part of the setup or teardown of the container.
+
+Anyways! You have probably seen the docker run and docker-compose configuration examples
+and you've put two and two together: This is where environment variables comes in.
+Setting environment variables is a common way to pass configuration options to containers
+and it is the way we have chosen to do it here.
+So far we've explained the need for `OPENVPN_PROVIDER` and `OPENVPN_CONFIG`. We use the
+combination of these two to find the right config. `OPENVPN_CONFIG` is not set as a mandatory
+option as each provider should have a default config that will be used if none is set.
+
+With the config file identified we're ready to start OpenVPN, the only thing missing are probably
+a username and password. There are some free providers out there, but they are the exceptions to the rule.
+We have to inject the username/password into the config somehow. Again there are exceptions but the majority
+of configs from regular providers contain a line with `auth-user-pass` which will make OpenVPN prompt for username
+and password when you start a connection. That will obviously not work for us so we need to modify that option.
+If it's followed by a path to a file, it will read the first line of that file as username and the second line as password.
+
+You provide your username and password as `OPENVPN_USERNAME` and `OPENVPN_PASSWORD`. These will be
+written into two lines in a file called `/config/openvpn-credentials.txt` on startup by the start script.
+Having written your username/password to a file, we can successfully start OpenVPN.
+
+## Starting Transmission
+
+We're using the `up` option from OpenVPN to start Transmission.
+> --up cmd<br>
+> &nbsp;&nbsp;&nbsp;&nbsp;Run command cmd after successful TUN/TAP device open
+
+This means that Transmission will be started when OpenVPN has connected successfully and opened the tunnel device.
+We are having OpenVPN call the [tunnelUp.sh](https://github.com/haugene/docker-transmission-openvpn/blob/master/openvpn/tunnelUp.sh)
+script which in turn will call the start scripts for
+[Transmission](https://github.com/haugene/docker-transmission-openvpn/blob/master/transmission/start.sh) and 
+[Tinyproxy](https://github.com/haugene/docker-transmission-openvpn/blob/master/tinyproxy/start.sh).
+
+The up script will be called with a number of parameters from OpenVPN, and among them is the IP of the tunnel interface.
+This IP is the one we've been assigned by DHCP from the OpenVPN server we're connecting to.
+We use this value to override Transmissions bind address, so we'll only listen for traffic from peers on the VPN interface.
+
+The startup script checks to see if one of the [alternative web ui's](config-options.md#alternative_web_uis) should be used for Transmission.
+It also sets up the user that Transmission should be run as, based on the PUID and PGID passed by the user
+along with selecting preferred logging output and a few other tweaks.
+
+Before starting Transmission we also need to see if there are any settings that should be overridden.
+One example of this is binding Transmission to the IP we've gotten from our VPN provider.
+Here we check if we find any environment variables that match a setting that we also see in settings.json.
+This is described in the [config section](config-options/#transmission_configuration_options).
+Setting a matching environment variable will then override the setting in Transmission.
+
+OpenVPN does not pass the environment variables it was started with to Transmission.
+To still be able to access them when starting Transmission, we're writing the ones we need to a file when starting OpenVPN.
+That way we can read them back and use them here. With the environment variables in place
+[this script](https://github.com/haugene/docker-transmission-openvpn/blob/master/transmission/updateSettings.py) then overwrites
+the selected properties in settings.json and we're ready to start Transmission itself.
+
+After starting Transmission there is an optional step that some providers have;
+to get an open port and set it in Transmission. **Opening a port in your local router does not work**.
+I made that bold because it's a recurring theme. It's not intuitive until it is I guess.
+Since all your traffic is going through the VPN, which is kind of the point, the port you have to open is not on your router.
+Your router's external IP address is the destination of those packets. It is on your VPN providers end that it has to be opened.
+Some providers support this, other don't. We try to write scripts for those that do and that script will be executed
+after starting Transmission if it exists for your provider.
+
+At this point Transmission is running and everything is great!
+But you might not be able to access it, and that's the topic of the [networking section](vpn-networking.md).

docs/arguments.md → docs/config-options.md

@@ -80,22 +80,6 @@ Transmission options changed in the WebUI or in settings.json will be overridden
 PS: `TRANSMISSION_BIND_ADDRESS_IPV4` will be overridden to the IP assigned to your OpenVPN tunnel interface.
 This is to prevent leaking the host IP.
 
-### Web proxy configuration options
-
-This container also contains a web-proxy server to allow you to tunnel your web-browser traffic through the same OpenVPN tunnel.
-This is useful if you are using a private tracker that needs to see you login from the same IP address you are torrenting from.
-The default listening port is 8888. Note that only ports above 1024 can be specified as all ports below 1024 are privileged
-and would otherwise require root permissions to run.
-Remember to add a port binding for your selected (or default) port when starting the container.
-If you set Username and Password it will enable BasicAuth for the proxy
-
-| Variable           | Function                | Example                 |
-| ------------------ | ----------------------- | ----------------------- |
-| `WEBPROXY_ENABLED` | Enables the web proxy   | `WEBPROXY_ENABLED=true` |
-| `WEBPROXY_PORT`    | Sets the listening port | `WEBPROXY_PORT=8888`    |
-| `WEBPROXY_USERNAME`| Sets the BasicAuth username | `WEBPROXY_USERNAME=test`    |
-| `WEBPROXY_PASSWORD`| Sets the BasicAuth password  | `WEBPROXY_PASSWORD=password`    |
-
 ### User configuration options
 
 By default everything will run as the root user. However, it is possible to change who runs the transmission process.
@@ -121,4 +105,22 @@ By default Transmission will log to a file in `TRANSMISSION_HOME/transmission.lo
 
 To log to stdout instead set the environment variable `LOG_TO_STDOUT` to `true`.
 
-*Note*: By default stdout is what container engines read logs from. Set this to true to have Tranmission logs in commands like `docker logs` and `kubectl logs`. OpenVPN currently only logs to stdout.
+*Note*: By default stdout is what container engines read logs from. Set this to true to have Tranmission logs in commands like `docker logs` and `kubectl logs`. OpenVPN currently only logs to stdout.
+
+### Custom scripts
+
+If you ever need to run custom code before or after transmission is executed or stopped, you can use the custom scripts feature.
+Custom scripts are located in the /scripts directory which is empty by default.
+To enable this feature, you'll need to mount the /scripts directory.
+
+Once /scripts is mounted you'll need to write your custom code in the following bash shell scripts:
+
+| Script                              | Function                                                     |
+| ----------------------------------- | ------------------------------------------------------------ |
+| /scripts/openvpn-pre-start.sh       | This shell script will be executed before openvpn start      |
+| /scripts/transmission-pre-start.sh  | This shell script will be executed before transmission start |
+| /scripts/transmission-post-start.sh | This shell script will be executed after transmission start  |
+| /scripts/transmission-pre-stop.sh   | This shell script will be executed before transmission stop  |
+| /scripts/transmission-post-stop.sh  | This shell script will be executed after transmission stop   |
+
+Don't forget to include the #!/bin/bash shebang and to make the scripts executable using chmod a+x