Theme - Guide

Among on the forums are several confusions about customizing PirateBox. Let's sum up the possibilities and make clear howto get to you custom Theme. Please provide feedback or help with unclear points in the Piratebox forum.

On the webpage, all URLs and links (JS & CSS) are absolute URLs agains /content/...

This is the original webroot folder. You land on this folder when you enter http://piratebox.lan or any url without a path suffix. index.html is containing the absolute URL to the box' name and is changed with the /opt/piratebox/bin/install_piratebox.sh script. It 'always' refers to http://piratebox.lan/content. This also used to forward in case of an unknown (404). PirateBox 1.1.3 still contains redirect.html which will be removed in the future. Usually you do not have do modify the content here. In the folder the generated HTML pages for the Shoutbox and the disk usage bar is stored. All CSS & JS is in /opt/piratebox/www/content .

Note: It is not necessarily needed to modify this folder.

This folder contains the original unmodified version of the landing page. It is a backup of the default theme and is copied to /opt/piratebox/share/content during first initialization. PirateBox keeps a copy of the folder in case of (accidentally) removing the content folder on the USB stick- this folder will be placed again to /opt/piratebox/share/content if content is missing during startup.

This is the folder which you should focus on adding on your modifications. /opt/piratebox/www/content is a symlink to /opt/piratebox/share/content , which means, that those are kind of identical. As the share folder is typically on the USB stick or the expanded storage medium, you can backup, edit and exchange this folder on your computer (in case of USB stick). favicon.ico is stored here.

In this folder the different language files are stored. If you want a multi-language box, you may want to adjust these text files. If you only want to have your modification only, it is better to disable the language feature (see below).

Contains custom Javascript code including jQuery and the l10n script. jQuery might be referred by the directory listing in http://piratebox.lan/Shared.

The PirateBox logo files are located here. You may just replace the file itself (with the same name) or add other files.

Here is the CSS file page_style.css for the landing page and the directory listing.

Due to legacy reasons, this is the most difficult part for customizations. PirateBox uses the most ressource-free method to create the directory listing, which is the lighttpd built in listing. The initial configuration is in /opt/piratebox/conf/lighttpd/ligghtpd.conf at this point a reference to /content/css/page_style.css is included and to add HEADER.txt (head) and README.txt (bottom) of each page. In summary, this creates the PirateBox theme look & feel of the directory listing.

You have to make sure, that page_style.css is available or the directory listing redirect to the landing page. You can directly edit HEADER.txt and README.txt in the /opt/piratebox/share/Shared folder. After you finished editing these files, copy your modified version over to /opt/piratebox/src. Create a backup of these files, instead of the /content folder, these files are overwritten during an upgrade.

If you already have a larger folder structure, you can you PirateboxScripts to distribute your version of HEADER.txt and README.txt over to these folders. Run:

sudo /opt/piratebox/bin/distribute_files.sh /opt/piratebox/share/Shared 'true'

Note: i10n Feature is not enabled for directory listing.

On OpenWrt based PirateBox your are typically working as root and the USB Stick does not reflect a the Linux file permissions, you do not have to deal with it here. On RPi based or normal Linux based PirateBox it is a bit more difficult. The normal installation changes the permissions of the www folders (see above) to the owner/group nobody/nogroup and the files are read-writable for user&group only, while the user login is alarm. For a normal webserver setup, this is sufficient- but for customization it is difficult. If you decided to use the USB stick as a storage option on RPi, you can easily edit the files on the USB stick.

The easiest way to make the needed folders writable for you is:

sudo chmod a+w <folder>

for example for the content folder:

sudo chmod a+w /opt/piratebox/share/content

After you are done with the customization, the recommendation is to perform the following commands:

sudo chmod a-w <folder>
sudo chown nobody:nogroup -R <folder>

Note: nobody:nogroup may be different on custom installations.

Beside of HEADER.txt and README.txt you can easily exchange the /opt/piratebox/share/content folder with your own.

The data-<lang>.properties are containing the text which is inserted during pageload. The text you can see in the files located in /opt/piratebox/share/content is a space holder, which is used if no corresponding data-<lang>.properties file is found. (Language files needs to be referred in locales.ini).

If you want to edit directly the text in the HTML file, you might want to disable i10n.

To disable that feature, find & remove the following line in /opt/piratebox/share/content/index.html:

   <script type="text/javascript" src="/content/js/l10n.js"></script>

Redirect loops usually happen, if you refer to a not existing file, which creates a HTTP 404 - which results in a redirect to the landing page… which is referring to a not existing file … which creates HTTP 404 - you can imagine. To debug this issue, you might want to use the features of your browser to identify the 404. If you can not find it like this, you might want to disable the automatic redirect in lighttpd configuration (OpenWrt - omit sudo)

sudo sed -i -e "s/^server.error-handler-404/#server.error-handler-404/" \
    /opt/piratebox/conf/lighttpd/lighttpd.conf

You might want to restart the piratebox or just the service.

OpenWrt:

 cd /
 /etc/init.d/piratebox restart

RPi:

 sudo systemctl restart piratebox

To re-enable it, just run the following command:

sudo sed -i -e "s/^#server.error-handler-404/server.error-handler-404/" \
    /opt/piratebox/conf/lighttpd/lighttpd.conf

Restart Piratebox again.

During a reboot the following happens to your customization

1. /opt/piratebox/share/content stays completely untouched.
2. README.txt and HEADER.txt is overwritten with a new version.
3. Customization it /opt/piratebox/conf is overwritten and lost.