maxkoryukov/HeadphonesDev.md

## HeadphonesDev.md

      
    Raw
  

              HeadphonesDev.md
            
          
    Deployment

Download sources (currently master is the latest actual version):
git clone https://github.com/maxkoryukov/headphones.git .

Second step: run the app
python Headphones.py

By default Headphones should open your default browser. If not - headphones works on the address (default settings): http://localhost:8181
Lighttpd

Here is sample config for Lighttpd, which:

Redirects all HTTP queries to HTTPS
Redirect all queries from https://YOURSERVER.XXX/headphones/ANYURL to Headphones
Pay attention to correct HTTPS -> HTTP redirecting (by adding appropriate headers)

Here is a config, in next sections - detailed description for every config option
# /usr/share/doc/lighttpd/proxy.txt

server.modules   += ( "mod_setenv" )     # enable setenv module, required
	                                     # for HTTP->HTTPS redirection
server.modules   += ( "mod_proxy" )      # enable proxy module for lighttpd


$HTTP["url"] =~ "^/headphones($|/)" {         # All rules - just for /headphones subpath

	                                     # BLOCK 1 : HTTPS redirect
	$HTTP["scheme"] == "http" {		     # this rule only for HTTP-queries
		$HTTP["host"] =~ ".*" {		     # .. for ANY host/address
			url.redirect = ( ".*" => "https://%0$0")		# REDIRECTION!

		}
	}

	                                     # BLOCK 2 : HTTPS proxy
	setenv.add-request-header = (        # next step - proxyfying request
		"X-Forwarded-Ssl" => "on"        # need to append HTTP-HEADERS
		                                 # for HP hidden behind https proxy

		##"X-Forwarded-Proto" => "https" # DO NOT USE THIS HEADER!!!!
	)

	                                     # BLOCK 3 : Reverse proxy
	proxy.server = (                     # enable proxy for path
		"" => ((
				"host" => "127.0.0.1",   # proxy settings, host and ...
				"port" => 8181           # ... path
		))
	)
}


DO NOT FORGET to set appropriate options for Headphones
HTTPS redirect

Probably, you would like to redirect all HTTP requests to HTTPS. Here is small tooltip for Lighttpd
# setting up the proxy for required path:
$HTTP["url"] =~ "^/headphones($|/)" {

	$HTTP["scheme"] == "http" {		# select HTTP-queries
		$HTTP["host"] =~ ".*" {		# query for any host/address
			url.redirect = ( ".*" => "https://%0$0")		# REDIRECTION!

		}
	}
}

HTTPS proxy

Good reverse proxy, which handles HTTPS TO HTTP, should care about back HTTP-headers, because back-end application (in our case - Headphones) doesn't know about HTTPS without hints. Lets edit the configuration of Lighttpd and add two required things:
# enable setenv module
server.modules += ( "mod_setenv" )

and the second part:
$HTTP["url"] =~ "^/headphones($|/)" {
	setenv.add-request-header = (
		"X-Forwarded-Ssl" => "on"
	)
}

This part will append special header to all redirected requests, so the HP will know, that it is behind HTTPS proxy.
FYI: HTTP-header X-Forwarded-Proto could cause strange thins, like this: rembo10/headphones#2616
Reverse proxy

Assume, that your Headphones-instance should be handle path http://example.com/**headphones/**. First, you need to set up reverse proxy on Lighttpd. Lets loot at this lighttpd configuration.
# /usr/share/doc/lighttpd/proxy.txt

server.modules   += ( "mod_proxy" )      # enable proxy module for lighttpd

$HTTP["url"] =~ "^/headphones($|/)" {        # Rule for /headphones subpath
	proxy.server = (                     # enable proxy for path
		"" => ((
				"host" => "127.0.0.1",   # proxy settings, host and ...
				"port" => 8181           # ... path
		))
	)
}


Headphones

Work behind proxy

Headphones could work behind proxy, but it is required to edit configuration file. You could find config file - config.ini - in the root of Headphones installation.
To work behind reverse proxy set two options in General section:
[General]
http_root = /headphones/
http_proxy = True
Both options are available in the WebUI of HP: Settings > Advanced > Advanced HTTP
Soft Chroot

SoftChroot - is an ability to use real paths on backend and chrooted paths on frontend.
For example, lets assume following config:
[General]
soft_chroot = /tmp/heaphones/
log_dir = /tmp/heaphones/some_dir/a/hello/logs
...
The app will write logs to the /tmp/heaphones/some_dir/a/hello/logs , but through UI user could see, that log dir is /some_dir/a/hello/logs . So, the user is soft-chrooted to the /tmp/headphones/
Hidden and Readonly options

If you want to configure meta-info for options, do the following:

Navigate to the root of HP installation (there should exists file config.ini)
Create file config.meta.ini. Remember: the name is very important
Edit config.meta.ini, according to the format (described further)

Format of meta

config.meta.ini is a common INI file, and its content is very similar to the config.ini
Here is the example:
[General]
soft_chroot = ro,hide
http_host = rw
http_username = ro
nzb_downloader = rw
torrent_downloader = items-allow(1;2), rw
The names of sections and options are the same, as in the config.ini. The value of option is composite, here is a list of possible parts (with description):

hide - make option hidden
show - make option visible (default)
ro - option is readonly
rw - you could read and write the value (default)
items-allow(n1; n2) - allowed items for dropdown lists

You could combine this parts together, separating them by comma ,
All changes will take effect after restarting of the Headphones