Cutting your PirateBox jib

This is a post that will be used as further reading/handout to a poster that will be presented at the 2014 TESOL France colloquium this November [update: you can find poster in this post]. It outlines some necessary steps to help customize the look of your PirateBox as well as some additional programs that will come in handy.


Before going to the chocolate factory (Google) store to download and install PirateBox for Android, you need to make sure your phone is rooted. Rooting a phone means that you are able to alter the permissions on the files of the phone. Usually you also have to unlock (the boot loader) of the phone before rooting though some phones come unlocked (note this is not the same as unlock to a particular telephone carrier). The following link is a good jump point to find information on rooting and unlocking your model of phone – How to Root Any Device.

Okay so you have unlocked and rooted your phone, and are now ready to download and install PirateBox for Android.

PirateBox settings

Once downloaded go into settings and untick Enable Updates and tick Content to SD. See the following screenshots:

enableupdates content2sd

Then start PirateBox once. Unticking Enable Updates option makes sure that any new version of PirateBox does not overwrite any changes you make in the configuration and HTML files. Updates will continue to update the core program only.

What the Content to SD option does is copy the configuration and HTML files you need to customize PirateBox to your phone’s sd card under a folder called piratebox/. There is also a separate directory pb-store/ where there is pb-store/uploads/ which keeps the files you want to serve, and pb_store/chat/ where chat logs are saved.

Aside – the simplest change you can do is use the SSID Name option to change the name of the wireless access point from “PirateBox – Share freely” to whatever you want, here is a screenshot of mine called un-originally enough “”:


Editing files

You can either edit the files on your phone or on your computer or both. I do the main edits on computer and any small edits on phone. Make sure you have copies on your computer in case you wipe your phone files somehow.

The files you need to customize are located in piratebox/html/ folder and piratebox/html/i18n/ called list.xhtml and respectively.

Most of your edits can be done in It is up to you how much customising you want to do. You will most definitely want to customize the welcome message. This is at the bottom of the file starting with


as you can see in the screenshot below, the one on the left is the original welcome message the one on the right my edited one:


If you know a little about image editing the header logo might be worth altering. The image files are located rightly enough in piratebox/html/images/. For example this is the logo I edited, note the English part  is like that to fit into existing dark header background:


I would also recommend commenting out the upload feature so as to preclude any potential issues with students trolling you with inappropriate images. You need to edit the index.xhtml file (located in piratebox/html/).

You comment out html code like this <!– code –> , that is open with left angle bracket, exclamation mark, dashed line, dashed line then your code and close with dashed line, dashed line, right angled bracket, as seen in the next screenshot below (the blue highlighted bit):


Also you can change the upload.title in file to something like:


Additional tools

Other tools that are useful is the camera on your phone, CamScanner app and FX File Explorer app (both free). CamScanner is a handy way of converting any pictures of text you take into pdf and FX file explorer is great for copying, pasting, editing files.

Imagine a scenario where you, at the last minute (perish the thought!), read a great lesson blog post with a text that you want to use but no time to make any photocopies and for some reason can’t download the text. So you take a picture of the text from the computer screen and save as pdf using CamScanner and then copy & paste to your pb-store/upload/ folder using FX File Explorer. Bingo you got your file that students can now access.

I am sure there are things I have not explained well and things I have left out, so do please let me know in the comments. You can always checkout the PirateBox forums as well, in particular the Piratebox for Android sub-forum.

I will put up the poster as an update once the conference is finished. And if you happen to be drifting by Paris for the conference do come say ahoy and witness more poor nautical puns at my poster session.

Thanks for reading shipmates, arrr!


5 thoughts on “Cutting your PirateBox jib

  1. Hi Mura,

    Great post – just been struggling with PirateBox for two days – it’s not easy but I finally got it up and running on my laptop.

    Two questions:

    i) Can I use PirateBox on my Android tablet? (Samsung notebook)

    ii) Are the files you need to adjust similar or the same on the desktop version. I mean, if I want to adjust the welcome screen on my PirateBox are the files similar and in the same place?



    1. hi Paul

      your tablet needs to be rooted
      no the files for piratebox for android is not same as the openwrt set-up.
      take the usb key and plug it into your computer and have a look at the /opt/piratebox folder to edit the html files there like index.html

      edit: forgot that /opt directory does not show up on normal file explorer, what you can do is connect via wifi to your piratebox from your desktop computer.

      than open a terminal and use the scp command to copy the www folder from /opt/piratebox/www to your desktop

      command will be:
      scp -r root@piratebox:/opt/piratebox/www ~/Desktop

      than after editing the index.html file you can copy back that file onto your piratebox using again scp command e.g.:
      scp ~/Desktop/www/index.html root@piratebox:/opt/piratebox/www/

      let me know if that makes sense!

      good luck!

Penny for your thoughts

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.