Setting up Transmission (bittorrent) with Clutch WebUI

Introduction

This document will show you how you can setup Transmission BitTorrent client on Alpine Linux and control it with a nice HTTP web-interface. I assume that you know the basics about Alpine Linux (package management and internals) and you have enough storage available to store your downloaded media (ie USB hard-drive) and of course a working internet connection.

Setting up Lighttpd with PHP support

The first thing we need to setup is lighttpd. We need lighttpd because our web-interface (Clutch) depends on PHP and the default webserver in Alpine Linux (mini_httpd) does not support it. Lets install it:

apk_add lighttpd php

NOTE: When you install PHP you will see it has some dependencies. PHP isn't a light package so please consider this before you install it.

When the installation is finished we need to add PHP support to lighttpd. There are two ways of adding PHP support to lighttpd:

1. PHP in CGI mode
2. PHP in FastCGI mode

If you need a high performance HTTP server with PHP support, you should probably go for the second option but if you need PHP only for some administrative tasks like controlling Clutch, CGI mode should be enough. FastCGI keeps PHP running in the background waiting for lighttpd to talk to it This makes it fast and more responsive than normal CGI mode. I choose normal CGI because I have a small embedded system and I prefer to use my memory for other things. Lets add PHP CGI support by creating the following file:

vi /etc/lighttpd/mod_cgi_php.conf

And add the following to it and save it:

# see cgi.txt for more information on using mod_cgi
server.modules += ("mod_cgi")
cgi.assign = (".php"             =>      "/usr/bin/php-cgi")

Now we need to make sure lighttpd can find this configuration file by adding an include in our lighttpd.conf. You can add it inside the include section:

include "mod_cgi_php.conf"

Our Lighttpd with PHP support should be complete. Lets start lighttpd and see if it works (make sure no other service is running on port 80).

/etc/init.d/lighttpd start

Fire up your prefered browser and point it to:

http://ipaddress/

This should give a 404 document not found error. If not something went wrong... A good way of knowing if PHP is functioning properly is by creating a test page which includes the phpinfo() function. We do this like this:

echo "<? phpinfo(); ?>" > /var/www/localhost/htdocs/test.php

Now change the address in your browser to:

http://ipaddress/test.php

This should display a page which tells you everything regarding your PHP installation. If all is ok we can add lighttpd to the system start:

rc_add -k lighttpd

Setting up Transmission

As of Alpine 1.7.18 it includes Transmission BitTorrent client. Lets install it:

apk_add transmission

This should install Transmission 1.20 which is included in Alpine 1.7.18. After the installation is complete you should have default configuration file for init in:

/etc/conf.d/transmission-daemon

We need to make some changes to this file. Because transmission-daemon will be controlled via Clutch which is run by lighttpd we need to change the user/group transmission-daemon runs at. We also need to change the DATA directory because we do not want to loose transmissions runtime info after a reboot (if it does it will need to recheck the hash of each running torrent). Personally I have mounted my USB disk to /media/usb and created a subdirectory torrents. This will be the directory where my media will be saved to. Inside this directory I created a .config directory. This is my DATA dir where transmission holds its runtime data. Make sure the torrents directory and everything below it is owned by lighttpd:lighttpd or else transmission cannot save any media. The contents of my conf.d file is like this:

USER=lighttpd
GROUP=lighttpd
DATA_DIR=/media/usb/torrents/.config

If you need another DATA_DIR change it and save it. If you are sure that all permissions are setup correctly you can start transmission-daemon and see if all is working ok:

/etc/init.d/transmission-daemon start

If everything is OK you should see transmission-daemon running with the following command:

ps

Lets add it to our system start:

rc_add -k transmission-daemon

Setting up Clutch WebUI

The last step is to install our web-interface. We do this by running:

apk_add clutch

After the installation completes it should be located in:

/usr/share/webapps/clutch/0.4

To make it available for lighttpd we need to make a symlink in the docroot of lighttpd:

ln -s /usr/share/webapps/clutch/0.4/htdocs /var/www/localhost/htdocs/clutch

Because we are adding a file outside /etc we need to add it with lbu add:

lbu add /var/www/localhost/htdocs/clutch

Clutch uses an configuration file which we can manage from the interface. The configuration file is stored outside our /etc directory so we will have to add it also with lbu add and we need to setup the proper permissions to the directory where its stored so clutch is able to write to it:

chown lighttpd:lighttpd /usr/share/webapps/clutch/0.4/htdocs/remote/data

lbu add /usr/share/webapps/clutch/0.4/htdocs/remote/data

Now it time to see if our Clutch WebUI can find Transmission:

http://ipaddress/clutch

If everything is setup correctly it should return an error. This is because the default download directory is not setup correctly. In the left bottom corner of Clutch you will see a config button which will open the configuration window. Adjust your configuration and make sure you select a directory which is owned by the same user as transmission-daemon is running. After you save your settings you should have a working Clutch installation.

Saving your changes to disk

Now its a good time to write you changes to disk:

lbu_commit device