Internet-In-A-Box for JRS Iraq

information accessibility for rural project sites


(Note that a lot of this page is technically focused, but the introduction and overview video are generally accessible. Also there are pictures sprinkled throughout. Don’t be afraid; skimming is fun!)

Table of Contents

Introduction

During the portion of my Jesuit formation called “regency,” between my first studies and my theological preparation, I served as the Regional IT Officer for the Jesuit Refugee Service in the Middle East and North Africa. This job encompassed a wide variety of responsibilities ranging from helping develop and roll out a new data platform for the global organization to improving local networks at our project sites.

One of my favorite parts of the job, though, was traveling to our projects in Iraq and Kurdistan. It’s hard to fully explain, but if you’ve ever had the sensation of arriving in a place and just feeling like it’s where you are supposed to be at that moment… that was what I felt driving through the mountains of Kurdistan or across the plains of Nineveh.

A smiling man leaning on an ancient stone wall in front of a dry desert valley that opens onto a large plain stretching to the horizon

During one of those visits, Fr. Joseph Cassar, SJ, the country director for JRS in Iraq, asked me about solutions for the very fragile internet connections we often have in our schools and learning centers in the region. He had heard stories about the “Blue Box” made by Creighton University, and was hoping we could use them to improve the resources available in our classrooms for both children and adults. While the Blue Box program turned out to not be a fit for our particular situation, I was very grateful for the chance to explore the possibilities of providing “internet in a box,” using my technical background in service of people in dire need in this place I was quickly falling in love with.

I outline the concept and the overall process of building them (at least at a high level) in the video below. If you’re interested in more technical details, keep scrolling down! The full disk images used for deployment are also available for download at the bottom of the page.

Caveat

It’s important to emphasize that this is a very experimental pilot project. The content of the devices is a bit non-specific, and will have to be evolved over time. It’s not clear how well the hardware will hold up to the environmental challenges of heat and dust in the region. We expect there to be missed opportunities and failures as we learn how best to use this technology, but this page describes the efforts made in getting the initial version ready for deployment.

Overview Video

Technical Details

What follows here is a record of my thinking as to why I made certain choices, how the system is set up, etc. It’s partially a record for me, but also meant to be a guide for anyone else thinking of setting up a device like this. You may ultimately make different choices than I did, but maybe I can save you some time in discerning. So much as this is useful, use it.

Computer Hardware

Raspberry Pi 4 Model B w/2GB of RAM

Fundamentally, the Internet-in-a-Box is a server, like any other computer on a network. Since it is built on Linux, it could run on a broad variety of hardware, including old computers we already had lying around.

I ultimately went with Raspberry Pis for the same reasons lots of other people choose them for similar devices:

If, instead, we were using a more traditional computer, we would have to be prepared for a variety of failure modes, keep a list of compatible parts for replacement, provide more electrical power, etc. Raspberry Pis, while having a bit less CPU capacity than most other computers, are very capable for this niche.

The biggest challenge around using the Raspberry Pi was the fact that I was implementing this project in early 2022, when supply chain issues made the units difficult to find at any price, all over the world. With patience and the cooperation of my fellow Jesuits in other countries, I was able to get what I needed, but the procurement process for them was far more difficult than I anticipated when I first pitched the project.

The Raspberry Pi Model 4 is available in a few different RAM configurations. The larger 4 GB and 8 GB models were even more difficult to find (while also being more expensive), and from the research I had done, the 2 GB model would be sufficient for what we needed. If we end up expanding the capabilities of the devices in some of the ways we talk about for the future, we may ultimately want to upgrade to a model with more memory, but 2 GB gives a lot of room to play initially.

Computer Cases

JUN-ELECTRON Aluminum Alloy Case with Cooling Fans

Having chosen the Raspberry Pi, I then turned to the question of how best to protect it, given that temperatures in Qaraqosh can rise to 50°C (122°F) and dust is an ever-present concern.

There’s a large variety of cases available for Raspberry Pis. Many are purely aesthetic; some provide additional features like power management or storage; others are focused on cooling for people who want to overclock their units. There was very little publicly written about how to keep the devices operating under conditions I anticipated in Iraq.

I did spend some time surveying people who used Raspberry Pis to drive art projects at Burning Man, which has conditions nearly as extreme as those in the region we serve. Usually, though, since Burning Man only lasts for a brief time, they don’t need to keep the devices running long-term. They did provide a few useful pointers, though, and experiences with how hard you could push a Raspberry Pi before it would shut down from overheating.

We had a few points in our favor here:

Ultimately, the JUN-ELECTRON case linked at the top of this section was mentioned a few times as a good option, since it combines a large solid heatsink for passive cooling with a pair of fans for active cooling. The fans are the only moving part in the system at present, and probably represent the biggest liability for breakdown. The ones that ship with the case are not especially hardy, so we’ll have to see if they remain functional in the face of the Iraqi dust. However, if the fans break down, it’s not catastrophic since the heatsink’s passive cooling will remain in effect.

The heat and dust problem is one that I am most concerned about with ongoing operations, but there’s no way to really know without running them in the field, so as of this writing, I’m simply awaiting reports. 🙏🏻🤞🏻

The computer described above in the case described above

Storage

480 GB SanDisk portable SSD (SDSSDE30-480G-G25)

Raspberry Pis typically boot from a microSD card. These have a lot of advantages — they are readily available all over the world since they are widely used in digital cameras; they are very small and let the entire unit be self-contained; they are solid-state with no moving parts to break; they provide sufficient read/write performance for nearly any application.

There are, however, some fairly significant downsides for our use case, though.

The last two points are also true for USB solid state drives, but the frauds and failures are much less frequent there. (Before I had settled on using USB drives for deployment, I actually got burned with some fraudulent microSD cards from local retailers. Caveat emptor.)

In the past, it was common for many Raspberry Pis to be used with the operating system booting from a small SD card and then using a USB drive for user data which could then be easily retained across operating system upgrades. We could have taken an approach like this, but ever since the fourth generation for Raspberry Pi devices, they’ve been capable of booting directly from a USB drive, so we could simplify things greatly by having just one storage device.

I never considered using a spinning-disk hard drive, even though it would have saved some money. The cost/reliability/speed profiles on solid state drives have just gotten so good that there was no reason to think about introducing another physically moving part to the system. SSDs also draw considerably less power, so we could continue running the system from the same power supply.

As for the particular model and brand of SSD, I had fewer opinions (but also fewer options). I wanted a reliable known manufacturer, but even most of the “rugged” branded drives were not made to deal with our levels of heat. When I did find a drive that I thought would work, it was not available for purchase in Lebanon (where I was doing the assembly), and I did not have time for international procurement at that stage.

The storage unit hardware is another area that I worry a bit about long term reliability, but we will have to see how they actually work in the field. The good news there is that reliable SSD drives are available and reasonably priced in the tech markets of Iraq, so replacements will not be hard to come by.

An assembled IIAB unit being held in front of a sign for the JRS Duhok office; the sign explains the mission and funding of the project there

IIAB Software Configuration

I experimented with many different ways of getting the devices up and running with the IIAB software. Using the one-line installer invocation from the IIAB Downloads Page, it’s fairly easy to put the software on a Raspberry Pi system that’s already up and running with Raspbian, Ubuntu, etc. I did this several times as I would often misconfigure something into a state of unusability and then need to wipe the device and start over.

Ultimately I found it was simpler to directly install one of the IIAB pre-built images that already included their software on top of Raspbian. Part of the challenge was that I was doing this setup in Beirut, where even at my office the internet is not very good, and the IIAB installation script downloads a lot of packages and content as it sets itself up. The pre-baked images, in contrast, can just be downloaded once and be used multiple times without the internet.

So I built our devices on the latest pre-built IIAB image at the time, which was the SMALL variant of 8.0beta1. That was enough to get the device up, broadcasting itself as a WiFi access point called “Internet in a Box” and serving up… nothing. The images do not include content, because it’s up to me to configure!

Here’s where I faced some difficulties, because the easiest way to add content to an IIAB system is to download it directly to the system itself using their web administration interface. My Lebanese environment again proved to be an obstacle here, though — if the internet cut out, there didn’t seem to be any way to resume a download, so if, say, I was 90% of the way through fetching the 87 GB archive of the English Wikipedia when the internet dropped, all the time and bandwidth was useless.

(If any IIAB project folks are reading, I would love to be wrong about this! If I’m mistaken, please correct me, but I could not get interrupted downloads to resume despite a few efforts.)

With things like Wikipedia archives, that are available as ZIM files, this isn’t too bad, as I was able to download them on my laptop (where resuming interrupted transfers is simple) and then move them over to the IIAB afterwards. Downloading map tiles was more difficult, as there is no obvious mechanism for importing them. Thankfully the system which handles the map tiles seems more amenable to working partially, so I spent a week running the process and periodically restarting it if it had gotten stuck because of a dropped connection.

Other than the content set, there was very little additional configuration done on the devices. They’re mostly running out-of-the-box standard IIAB for this pilot deployment. Future versions may be more customized, but it will be far easier to do so in a more stable development environment.

Prepping Disk Images

Because of my own difficulties in setting up these devices in the substandard electrical grid and internet capacity of Lebanon, I wanted to create something more turnkey for local IT staffers who would be tasked with day-to-day maintenance of the devices. Rather than teach them the intricacies of Linux installations and the variety of download techniques I developed for ingesting the content, I decided the simplest thing to do would be to make a disk image from the deployed device with all its content.

“Shane, wouldn’t that be a very large file?”

Yes it would, and yes, it is: about 237 GB compressed. While that is big, it’s not unfathomably big, so it’s something that can be stored on a backup drive at the country office or hosted on a web site (like this one!) for re-downloading as necessary. My hope for the future is that I can create a new image (with entirely new sets of content, new capabilities, software upgrades, etc.) from the more posh computing environment I’ll have after moving back to the US and then make it available on this web page. Then the country IT officer can download it at the country office in Erbil (where the internet is very reliable), and take out a freshly imaged drive on the next trip to the project sites where the devices are deployed.

Is this a realistic plan or a naïve fantasy? As with the hardware reliability mentioned before, we’re just going to have to see.

In any event, I want to record the procedure I use for making the images, as much for my own reference as anyone else who stumbles across this. Note that these steps have to be performed on a Linux machine, since they required GNU Parted, which doesn’t run on Macs.

  1. Once you have the IIAB set up the way you like, shut it down and detach its drive.
  2. Plug that drive into another Linux machine.
  3. Create an image from an attached drive:
  4. Download my fork of PiShrink:
  5. Use it to zip up and reduce an image:
  6. To generate the MD5 signature for the file:

Deployment Trip

In June of 2022 I traveled to Qaraqosh and Duhok to do the initial deployments and training sessions for the pilot version of the JRS IIAB devices.

A man wearing a medical face mask standing in front of an open network cabinet holding cables and a small computer
A man wearing a medical face mask and a clerical collar giving a thumbs-up in front of a computer screen open to the Internet-in-a-Box main menu
A group of people listening to a man in clerical attire lecture in front of a projector
Two staffers walking around behind people working in a computer lab answering their technical questions
A group of people listening to a man in a grey shirt lecture in front a projector

The training sessions were very gratifying in that all the educators we were working with quickly got it, and understood the potential of these devices to enhance their teaching. Like any educational resource, it will need decent lesson plans and engagement from the students, but there were a lot of sparks of ideas and really good questions coming from the crowd.

Future Directions

Along with those great questions, there were some folks who had immediate ideas for what else they wanted to do with the devices.

Software/Content

One of the teachers who does programming classes for adults asked about getting StackOverflow content, which is easy! Another who teaches kids asked about Scratch which is a little trickier, but should still be doable.

I mentioned, as an offhand joke, that I could put Minecraft on the devices (it would actually be Minetest, an open source game that is very similar), thinking it wasn’t something they would want, but the country director actually reacted positively. “As long as that’s not all they’re doing, it could be a good way to get them using it.” So we’ll see! I’m looking into what other kinds of entertainment stuff could make sense to go on there, too…

From the software side, it’s mostly going to be just more and updated iterations of content. I’d also like to tweak the IIAB menu page to have some JRS branding; I’d meant to do that before this initial deployment but time got away from me.

Hardware

If we are able to do another hardware deployment, there are a few things I definitely want to have.

One of the teachers asked about putting a bunch of the devices around the town, which is also an exciting prospect. With a solar panel and a decent WiFi access point, they can provide content and services to a much larger population. This would also require some good engineering analysis, but it’s in the realm of possibility.

If that’s the case and we can make these kind of “civic access points,” I wonder about including things like wikis and forum software for better communication… though I would really not want to deal with the moderation headaches that might come with it.

A lot of cool possibilities here, is my point.

Deployment Disk Images

These are compressed versions of the full deployment images including content and configuration. They are meant to mitigate the burden of local IT personnel by providing something that is easily imaged to a USB drive without much need for knowledge about how it works.

I recommend using the Raspberry Pi Imager program to write these images to a drive. It automatically handles setting up appropriate partitions, formatting, making sure it’s bootable by the Raspberry Pi, etc. There are other programs that provide similar functionality, but I personally find the RPi Imager to be the most straightforward. It runs on many operating systems and while the pictures below are from a Mac, the application interface is identical on Windows.

  1. Before starting the program, plug in the drive you wish to image or re-image. NOTE: this process will erase everything on the drive and it cannot be used for other purposes while it is acting as a storage unit.
  2. Run the Raspberry Pi Imager program and select “Choose OS” The Raspberry Pi Imager interface with the ‘Choose OS’ button circled
  3. Scroll down to select “Use custom” The Raspberry Pi Imager interface selecting a custom operating system
  4. Navigate to your downloaded image file that ends in .img.gz and choose it.
  5. Press the “Choose Storage” button. The Raspberry Pi Imager interface with the ‘Choose Storage’ button circled
  6. Choose the drive you want to image from the list. Remember this will completely and thoroughly erase the drive, so make sure to choose carefully.
  7. Once all that has been set up, you can now click the “Write” button. You will be asked to confirm that you are ready to erase everything currently on the drive. The Raspberry Pi Imager interface with the ‘Write’ button circled
  8. Wait patiently while the drive is imaged; it may take around a half-hour or so depending on the speed of the drive, your computer, etc.

The first time one of the images is booted, it will resize its data partition to use all available space on the drive; this gives flexibility to add more content if needed, and also to easily upgrade to larger drives as we expand.

At the moment, there’s just the one image for download, but if/when I generate more, they will go here.

Image Downloads

Please note these disk image files are very large, so make sure you are downloading them to a location that can handle a huge file. To verify that they downloaded correctly, on Windows you can run Get-FileHash {PATH_TO_IMAGE} -Algorithm MD5 in PowerShell, or on Mac/Linux md5 {PATH_TO_IMAGE} from a terminal. Either of these commands will print a checksum that should match the MD5 value given below. (Note that since these files are enormous, it may take a few hours to generate the checksum.)