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
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
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).
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
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.
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
Deactivate i10n feature
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
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.
cd / /etc/init.d/piratebox restart
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.
In case of an upgrade of PirateBox
During a reboot the following happens to your customization
/opt/piratebox/share/contentstays completely untouched.
HEADER.txtis overwritten with a new version.
- Customization it
/opt/piratebox/confis overwritten and lost.