This is an old revision of the document!


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.

Folders & Files

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

/opt/piratebox/www

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 .

/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.

/opt/piratebox/share/content

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.

/opt/piratebox/share/content/locales

In this folder the different language files are stored. 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 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).

/opt/piratebox/share/content/js

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

/opt/piratebox/share/content/img

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

/opt/piratebox/share/content/css

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

/opt/piratebox/share/Shared

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'

Permissions

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.

Customization hints

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

Language files

Deactivate i10n feature

FAQ

Redirect loops

In case of an upgrade of PirateBox