If you are planning on developing for the PirateBox, there are some tools that will help you.

There are multiple flavours piratebox comes in, you can install it on your PC, Raspberry Pi, Android or OpenWRT. This article is focused on the OpenWRT flavour.

The first thing you may want to do is get the build toolchain up and running. With this toolchain you can easily build your own OpenWRT images which allows for developing and quickly building images for testing on a real system.

PirateBox structure

PirateBox is based on OpenWRT and thus is able to use its build helpers. One very powerful feature of the OpenWRT build system are feeds. Feeds basically are collections of packages, they can be local or remote. This allows to easily add new package repositories to be included in the OpenWRT build.

PirateBox has its own feed, which means all you need is the OpenWRT build system and the PirateBox feed and you are good to go.

A detailed overview of the different github repositories can found on this page.


To give you a kickstart, there are some helper scripts that will set up the development environment for you, help building images and remastering them.

Those script can be found on github in the PirateBox dev environment repository. Once you have cloned the repository you may want to start building your toolchain and your first image for testing. Just run:

make auto_build_stable

This make target will fetch the toolchain, build it and then it will build the stable PirateBox release. Depending on your machine, this can take some time(hours). Make sure to check the README if you run into any problems. There is a detailed description on how to run the build manually and what each of the make targets does.

Local Feed

Once you have your toolchain up and running you may want to start on working on some of the packages. This is where the local feed comes in. A local fees is a directory with packages to be added to your image.

Prepare your local feed by running:

make apply_local_feed

This will pull in the repositories of all PirateBox packages into the local_feed folder. You can now switch branches, and start developing. When you are ready to build your images you simply run:

make auto_build_local

This will build your images using your local repositories for the PirateBox packages.


Once you have run the above steps you are ready to develop. Change to your local_feed folder. If the above steps worked as expected you will find the repositories for all packages that are needed to successfully build your PirateBox image. You can now checkout the branches you want your image to be built with, or add your own branches and start developing/improving PirateBox functionality or even swap one of the PirateBox package repositories with a fork of your own.

Core functionality

Web Interface

The following HowTo is based upong Archlinux and running lighttpd. It also applies only to the development branch (version >= 1.1). The development/lighttpd_extra.conf is prepared to setup a test environment in you homefolder's tmp directory. You can change it to something wich is more suitable. The configuration file development/lighttpd_inside.conf makes lighttpd run inside the the github repository. Each configuration has a disabled default redirect, because it won't help you much during development. The lighttpd runs with your userid and uses the highport 8001 and has no 404 redirect enabled per default.

The imageboard is currently not tested to run in this environment.

The WebUI should run in a configured apache2 environment. You need to setup cgi-bin to use .py files and react on python2 only. The file www/chat_content.html and www/cgi-bin/data.pso must be writeable for the apache user. Unfortunately the directory listing won't work.

Requirements are needed to get the UI working:

  • Python2
  • PHP including php-cgi (for lighttpd)

The following steps need to get the www folder working:

Get the latest development branch, if you want to contribute, please exchange the URL with the one of the forked repository.

# git clone
# cd PirateBoxScripts_Webserver 
# git checkout development

Create a dev. environment in an separate folder

This shows how to create a working web environment in ~/tmp

Create the web development environment for lighttpd in another directory:

# mkdir -p ~/tmp
# cp -rv piratebox/piratebox/www ~/tmp 
# cp -rv piratebox/piratebox/python_lib/*  ~/tmp/www/cgi-bin
# touch ~/tmp/www/chat_content.html
# mkdir -p  ~/tmp/www/Shared
# mkdir -p  ~/tmp/www/board 

Adjust the following line in the lighttpd configuration file in the PIrateBoxScripts_Webserver folder development/lighttpd_extra.conf. Be sure it is the full non relative path.

var.basedir=<change this to your desired folder>

Uploaded files will be placed in the Shared folder. Run lighttpd with the following command

# lighttpd -D -f development/lighttpd_extra.conf

Point your browser now to You will find error logs and logs from HTTP-Code 500 in /tmp/break.log & /tmp/error.log

Create run lighttpd inside github directory

You can run lighttpd inside the cloned repository. To do so, you should take care during the commits to not add unwanted files to the repository during working on it.

Create the web development environment for lighttpd:

# touch piratebox/piratebox/www/chat_content.html
# mkdir -p  piratebox/piratebox/www/Shared
# mkdir -p  piratebox/piratebox/www/board 

Usually during startup of the PirateBox, HEADER.txt and README.txt two files will be distributed across the directories. We are creating links to the original files, that you can adjust it transparently.

# ln piratebox/piratebox/src/HEADER.txt piratebox/piratebox/www/Shared/
# ln piratebox/piratebox/src/README.txt piratebox/piratebox/www/Shared/

Uploaded files will be placed in the Shared folder. Run lighttpd with the following command

 lighttpd -D -f development/lighttpd_inside.conf

Point your browser now to You will find error logs and logs from HTTP-Code 500 in /tmp/break.log & /tmp/error.log