Instructions

The following are a series of instructions to set up your own BlueBox:

Step 1: Acquiring the Hardware
    1. Buy a Raspberry Pi
    1. Go to https://www.raspberrypi.com/products/raspberry-pi-4-model-b/.
    2. Click Buy Now.
    3. Pick a model under Select a model. Note: 2GB is sufficient but 4GB or higher is recommended.
    4. Pick a country under Country.
    5. Click one of the approved retailers and purchase the Raspberry Pi.
    2. Acquire Supporting Hardware
    1. Depending on the retailer, search for related products to find available power supplies for the Raspberry Pi. More specifically, the Raspberry Pi4 Official USB-C 15.3W Black 5.1V 3A power supply should work.
    2. Browse the Internet for a Raspberry Pi 4 case that you would like to use.
    3. Browse the Internet for a micro SD card you would like to use. A minimum of 64 GB is recommended; however, depending on how many modules you would like to install, you likely need to increase this amount. We recommend an endurance card when possible (e.g., SanDisk High Endurance or Samsung Pro Endurance).
Step 2: Setting Up the BlueBox
    Option 1: Installing from Image 1. Download Etcher and the BlueBox Image
    1. Download Etcher from https://www.balena.io/etcher/ and install it.
    2. Download this image (2.85 GB).
    2. Install the Image
    1. Insert a micro SD card into your computer.
    2. Open Etcher.
    3. Click Flash from file and select the image you downloaded in step 1.
    4. Click Select target and select the drive of the SD card.
    5. Click Flash!
    6. When the flash has finished, remove the micro SD card and insert it into your Raspbery Pi.
    7. Plug in your Raspberry Pi and wait a few minutes.
    8. Search for the BlueBox Wi-Fi connection and select it.
    9. Enter bluebox/ or 10.10.10.10 in your browser URL.
    Option 2: Installing from Scratch 1. Install the Raspberry Pi OS
    1. Download and install the Raspberry Pi Imager: https://www.raspberrypi.org/software/.
    2. Insert a micro SD card into your machine.
    3. Open the Raspberry Pi Imager application.
    4. Click on CHOOSE OS under Operating System and select Raspberry Pi OS (other). It should be the second option.
    5. Select Raspberry Pi OS Lite (32-bit). Note: you could install the Desktop environment instead of the Lite environment, but it will take up more space on the Raspberry Pi.
    6. Click on CHOOSE STORAGE under Storage and select the micro SD card you inserted.
    7. Click WRITE.
    8. Confirm that you want to erase all the data on the SD card by clicking YES. Note: the writing process will take a while.
    9. Remove the SD card from your machine when the writing process finishes.
    10. Insert the micro SD card into the Raspberry Pi and power it up. You will need to connect a keyboard and external monitor to the Raspberry Pi to do the next steps.
    11. When you see the prompt raspberrypi login:, type pi for the username and raspberry for the password. Note: the password won't show up as you type.
    12. Optional: You can change the password on your Raspberry Pi by entering the following command, typing the old password, and typing the new password twice:
      passwd
    2. Change the Raspberry Pi Configuration Settings
    1. Change the Keyboard Layout
      1. Open the Raspberry Pi configuration tool:
        sudo raspi-config
      2. Use the keyboard to select Localisation Options and hit Enter.
      3. Use the keyboard to select Keyboard and hit Enter.
      4. Ensure that the default keyboard layout is Generic 105-key PC (intl.) and hit Enter.
      5. Select Other and hit Enter.
      6. Select English (US) and hit Enter.
      7. Select English (US) again and hit Enter.
      8. Select The default for the keyboard layout and hit Enter.
      9. Select No compose key and hit Enter.
      10. Use the default configurations for the rest.
      11. Navigate down and select Finish to save changes and close raspi-config.
    2. Connect the Raspberry Pi to the Internet
      1. Open the Raspberry Pi configuration tool again:
        sudo raspi-config
      2. Use the keyboard to select System Options and hit Enter.
      3. Select Wireless LAN and hit Enter.
      4. Select US for the country and hit Enter. Note: typing U will jump to the U's so you don't have to scroll through all the other countries.
      5. Hit Enter again to select <Ok>.
      6. Enter the SSID of your wireless network (e.g. CUWireless) and hit Enter.
      7. Enter your network password and hit Enter.
      8. Navigate down and select Finish to save changes and close raspi-config.
    3. Change the Hostname
      1. Open the Raspberry Pi configuration tool again:
        sudo raspi-config
      2. Use the arrow keys on your keyboard to select System Options again and hit Enter.
      3. Select Hostname and hit Enter.
      4. Hit Enter again.
      5. Replace raspberrypi with bluebox and hit Enter.
      6. Navigate down and select Finish to save changes and close raspi-config.
    4. Enable SSH
      1. Open the Raspberry Pi configuration tool again:
        sudo raspi-config
      2. Use the arrow keys on your keyboard to select Interface Options.
      3. Select the SSH option on the list.
      4. Select <Yes> on the Would you like the SSH server to be enabled? prompt and hit Enter.
      5. Hit Enter on the The SSH server is enabled confirmation box.
      6. Navigate down and select Finish to save changes and close raspi-config.
      7. Select <No> when asked to reboot and hit Enter.
      8. Edit the host file so we can SSH using bluebox instead of the IP address:
        sudo nano /etc/hosts
      9. Add the information below to the end of the host file:
        10.10.10.10   bluebox
      10. Save the new configuration by typing Ctrl + X, then Y, then Enter.
      11. Reboot the Raspberry Pi:
        sudo reboot
    3. Update and Install Necessary Applications on the Raspberry Pi
    1. Login back into the Raspberry Pi after reboot.
    2. Ensure the Raspberry Pi is plugged into an ethernet connection.
    3. Check for updates on the Raspberry Pi. Note: this step will take a while:
      sudo apt update -y
      sudo apt upgrade -y
    4. Install the Apache web server:
      sudo apt install -y apache2
    5. Install PHP:
      sudo apt install -y php php-mbstring
    6. Install MariaDB:
      sudo apt install -y mariadb-server mariadb-client php-mysql
    7. Install SQLite:
      sudo apt-get install php7.4-sqlite
    8. Install ZipArchive:
      sudo apt-get install php7.4-zip
      sudo phpenmod zip
    9. Reboot the Raspberry Pi:
      sudo reboot
    4. Enable the Raspberry Pi as a Wireless Access Point
    1. Set A Static IP Address
      1. Edit the dhcpcd configuration file:
        sudo nano /etc/dhcpcd.conf
      2. Add the information below to the end of the configuration file to set a static IP address:
        interface wlan0
        static ip_address=10.10.10.10/24
        nohook wpa_supplicant
        denyinterfaces eth0
        denyinterfaces wlan0
      3. Save the new configuration by typing Ctrl + X, then Y, then Enter.
    2. Install Hostapd
      1. Install hostapd to transform the Raspberry Pi's network interface card into a wireless access point software:
        sudo apt install hostapd
      2. Stop the hostapd service:
        sudo service hostapd stop
      3. Create the network name and password:
        sudo nano /etc/hostapd/hostapd.conf
      4. Add the information below to the configuration file and save it (if you have a pi 3, use g or n for hw_mode, ieee80211n instead of ieee80211ac, and 6 for g and 11 for n for the channel). Important: Make sure for the ssid that if you have multiple BlueBoxes in close proximity that you use a different ssid for each one (i.e. BlueBox-LastName or BLueBox-Location):
        interface=wlan0
        ssid=BlueBox
        hw_mode=a
        ieee80211ac=1
        channel=48
        macaddr_acl=0
        wmm_enabled=1
        auth_algs=1
        ignore_broadcast_ssid=0
        wpa=0
      5. Optional: If you want to password protect the Raspberry Pi, change wpa=0 on the last line to wpa=2 and add the following before saving your configuration (change BlueBoxPassword to what you want for the Raspberry Pi's Wi-Fi password):
        wpa_passphrase=BlueBoxPassword
        wpa_key_mgmt=WPA-PSK
        wpa_pairwise=TKIP
        rsn_pairwise=CCMP
      6. Save the new configuration by typing Ctrl + X, then Y, then Enter.
      7. Edit hostapd to apply the configuration that we just made:
        sudo nano /etc/default/hostapd
      8. Find #DAEMON_CONF and add this on a new line below:
        DAEMON_CONF="/etc/hostapd/hostapd.conf"
      9. Save the new configuration by typing Ctrl + X, then Y, then Enter.
      10. Enable the wireless access point service and set it to start when your Raspberry Pi boots:
        sudo systemctl unmask hostapd
        sudo systemctl enable hostapd
      11. Enable routing so devices can use the Internet of the BlueBox when it is plugged in:
        sudo nano /etc/sysctl.conf
      12. Uncomment the following line by removing the hashtag before it:
        net.ipv4.ip_forward=1
      13. Save the new configuration by typing Ctrl + X, then Y, then Enter.
      14. Run this code:
        sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
    3. Install Dnsmasq
      1. Install dnsmasq for Domain Name Server (DNS) caching and Dynamic Host Configuration Protocol (DHCP) server for managing the server name and connections:
        sudo apt install -y dnsmasq
      2. Stop the dnsmasq service:
        sudo systemctl stop dnsmasq
      3. Configure the DHCP and DNS services for the wireless network by backing up the default configuration file first:
        sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig
      4. Create our own configuration:
        sudo nano /etc/dnsmasq.conf
      5. Add the information below to the configuration file:
        interface=wlan0
        dhcp-range=10.10.10.11,10.10.10.255,255.255.255.0,24h
        domain=wlan
        address=/bluebox.lan/10.10.10.10
      6. Save the new configuration by typing Ctrl + X, then Y, then Enter.
    4. Set Up the Firewall
      1. Install iptables if it doesn't already exist:
        sudo apt install iptables
      2. Add the following three firewall rules to enable routing traffic through the Raspberry Pi:
        sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
      3. Save the rules:
        sudo sh -c "iptables-save > /etc/iptables.ipv4.nat"
      4. Edit the local file so the firewall rules are loaded at boot:
        sudo nano /etc/rc.local
      5. Add the following code before exit 0:
        iptables-restore < /etc/iptables.ipv4.nat
      6. Save the new configuration by typing Ctrl + X, then Y, then Enter.
      7. Enable the dnsmasq service (you may need to type the Raspberry Pi password several times)::
        sudo systemctl enable dnsmasq
        sudo systemctl start dnsmasq
        sudo systemctl status dnsmasq
    5. Check for the BlueBox Network
      1. Restart the Raspberry Pi:
        sudo reboot
      2. As the Raspberry Pi is booting, ensure the boot steps have [  OK  ] next to them (i.e. none say failed). If anything says failed, you may need to revisit the steps and ensure you have no typos.
      3. Double-check that the SSID specified in the file shows up as an available wireless network.
    5. Set Up MariaDB on the Raspberry Pi
    1. Open your terminal on a Mac or Windows Powershell/Putty on a PC and SSH into the Raspberry Pi.
      ssh pi@10.10.10.10
    2. Enter your password when prompted (you won't see anything when typing your password).
    3. Connect to the MariaDB:
      sudo mysql -u root
    4. Add a new bluebox account with the blue-admin password, grant all privileges to the new user, and remove the default root account:
      CREATE USER 'bluebox'@'localhost' IDENTIFIED BY 'blue-admin';
      GRANT ALL PRIVILEGES ON *.* TO 'bluebox'@'localhost' WITH GRANT OPTION;
      DROP USER 'root'@'localhost';
    5. For subsequent logins to MariaDB, use the following:
      sudo mysql -u bluebox -p
    6. Enter your password when prompted.
    7. Create the new bluebox schema and select it for use:
      CREATE SCHEMA bluebox;
      USE bluebox;
    8. Add the MariaDB tables and data:
      CREATE TABLE `file` (
        `filename` varchar(255) NOT NULL,
        `dir` varchar(255) NOT NULL,
        `ext` varchar(4) NOT NULL,
        PRIMARY KEY (`filename`,`dir`)
      );

      CREATE TABLE `user` (
        `username` varchar(100) NOT NULL PRIMARY KEY,
        `password` varchar(255) NOT NULL,
        `salt` varchar(255) NOT NULL,
        `language` varchar(20) NOT NULL DEFAULT 'English',
        `version` DOUBLE(10,2) NOT NULL
      );

      CREATE TABLE `module` (
        `module_id` int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
        `title` varchar(255) NOT NULL,
        `description` text NOT NULL,
        `rsync` varchar(255),
        `dir` varchar(255) NOT NULL,
        `url` varchar(255) NOT NULL,
        `kiwix` varchar(255),
        `downloaded` char(1),
        `active` char(1),
        `language` varchar(20) NOT NULL DEFAULT 'English',
        `size` double(20,2) NOT NULL,
        `version` varchar(25) NOT NULL,
        `source` varchar(255)
      );

      CREATE TABLE `category` (
        `category_id` int(11) NOT NULL AUTO_INCREMENT,
        `name` varchar(255) NOT NULL,
        `type` varchar(255) NOT NULL,
        PRIMARY KEY (`category_id`)
      );

      CREATE TABLE `module_category` (
        `category_id` int(11) NOT NULL,
        `module_id` int(11) NOT NULL,
        PRIMARY KEY (`category_id`,`module_id`),
        CONSTRAINT `module_category_fk1` FOREIGN KEY (`category_id`) REFERENCES `category` (`category_id`) ON DELETE CASCADE ON UPDATE CASCADE,
        CONSTRAINT `module_category_fk2` FOREIGN KEY (`module_id`) REFERENCES `module` (`module_id`) ON DELETE CASCADE ON UPDATE CASCADE
      );

      INSERT INTO user
      VALUES ('bluebox', '8cb3a029f8d1f4c8dd8d09f52e367b9aecdee60f9d18d5bca709c6f2e0e0a71bd5134d28520bc7cb3fc09c91d2f0df78a6d7eb2394319931cea44e03051929d6', '29fd9a48f7aa7edbe12e7c34c5297fce4d3c6702218111960fe4ee157ad01f9fd8e8ed96fdcf974533c8f57276150076e189c7bd74f8bb978a848938e9594b88', 'English', 0);
    9. Type exit and hit Enter or type Ctrl + C to exit MariaDB.
    6. Install the BlueBox Home Page
    1. Remove the current home page:
      sudo rm /var/www/html/index.html
    2. Create the new home page:
      sudo nano /var/www/html/index.php
    3. Copy and paste the following content into the new home page:
      <?php
      // Initialize a file URL to the variable
      $html = file_get_contents("http://bluebox.creighton.edu/modules.php?version=true");
      preg_match_all('/\d\.\d*/s', $html, $version);
      $version = $version[0][0];
      $filename = "pi-{$version}.zip";
      $url = "https://bluebox.creighton.edu/{$filename}";

      // Use basename() function to return the base name of file
      $siteUpdate = basename($url);

      // Use file_get_contents() function to get the file from url and use file_put_contents() function to save the file by using base name
      $arrContextOptions= [
          "ssl" => [
              "verify_peer"=> false,
              "verify_peer_name"=> false,
          ],
      ];
      file_put_contents($siteUpdate, file_get_contents($url, false, stream_context_create($arrContextOptions)));

      // unzips all the contents of the zip folder and loads them to the server
      $zip = new ZipArchive;
      $zip->open($filename);
      $zip->extractTo("pi");

      shell_exec("cp -r ./pi/pi/* . && rm -rf pi && rm {$filename}");

      header("Location: .");
      exit;
      ?>
    7. Change PHP Configuration Settings
    1. Edit the php.ini file to allow larger file uploads:
      sudo nano /etc/php/7.4/apache2/php.ini
    2. Note: if the previous step doesn't have any information then you will need to locate the php.ini file by adding the following to any PHP page, loading that page, and then finding the location of the php.ini file:
      <?php
      echo phpinfo();
      ?>
    3. Search for the following lines in the file by typing Ctrl + W and pasting the following values. Then change the values from 2M/10M to 1G or something larger than the defaults:
      upload_max_filesize
      post_max_size
    4. Search for the following line ;extension=sqlite3 and remove the semi-colon in front of the line.
    5. Save the new configuration by typing Ctrl + X, then Y, then Enter.
    8. Change Folder and File Permissions
    1. Change ownership to the hostapd configuration file so changes can be made from the browser interface when updating the Wi-Fi information:
      sudo chmod +777 /etc/hostapd/hostapd.conf
    2. Change ownership of the html folder to be able to transfer files to the html directory:
      sudo chmod +777 /var/www/html/
    3. Change ownership of the index file to be able to run it on first use:
      sudo chown www-data:www-data /var/www/html/index.php
    4. Edit the sudo user file to allow the site to reboot the Raspberry Pi when needed:
      sudo nano /etc/sudoers
    5. Add this to the end of the file:
      www-data ALL = NOPASSWD: /sbin/reboot, /sbin/halt
    6. Save the new configuration by typing Ctrl + X, then Y, then Enter.
    7. Restart the Raspberry Pi:
      sudo reboot
    9. Setup the Kiwix Server (Required for Kiwix Modules)
    1. Download the latest linux armhf version of Kiwix Tools. Click the precompiled version link under GNU/Linux. DON'T click the big button on the right.
    2. Connect to the BlueBox network.
    3. Transfer the download to the Raspberry Pi using SSH via WINSCP or FileZilla.
    4. Ensure the Raspberry Pi is connected to the Internet.
    5. Change to the directory where you transferred the file. For example, if you transferred the file to /var/www/html, you would run the following:
      cd /var/www/html
    6. Unpack kiwix-tools in a folder:
      tar -xvf kiwix-tools_linux-armhf-*.tar.gz
    7. Remove the downloaded file:
      rm kiwix-tools_linux-armhf-*.tar.gz
    8. Rename and move the extracted folder to /var/kiwix:
      sudo mv kiwix-tools_linux-armhf-* /var/kiwix
    9. Make sure kiwix-manage, kiwix-search, and kiwix-serve are in the /var/kiwix/ directory:
      cd /var/kiwix
      ls
    10. Edit the configuration file to start Kiwix on boot:
      sudo nano /etc/rc.local
    11. Add the following just before the exit line:
      sudo /var/kiwix/kiwix-serve --library /var/www/html/modules/kiwix-library.xml --port=8080 --daemon
    12. Save the new configuration by typing Ctrl + X, then Y, then Enter.
    13. Run the following command to grant permissions for the user interface to edit the kiwix library file:
      sudo chmod 777 /var/www/html/modules/kiwix-library.xml
    10. Open the BlueBox Homepage
    1. Connect to the BlueBox network.
    2. Ensure the Raspberry Pi is connected to the Internet.
    3. Open a browser and enter bluebox/ or 10.10.10.10/ as the URL. The page content should download and install automatically. You should now see the BlueBox site.
    4. You can now download modules.
Step 3: Downloading and Installing Modules