What is a Raspberry Pi? It is a series of small single-board computer originally intended for Computer Science students to practise their skills. Their low cost and flexibility contributed to their popularity skyrocketing, and the recent models are rather powerful for their size.
Raspberry Pi usually come pre-installed with Raspberry Pi OS, a Linux distribution (distro) specifically designed for these computers' ARM CPU architecture.
However, the most widely supported RPi OS is 32-bit which comes with severe limitation in terms of compatibility with many modern programs, and the 64-bit version released in 2020 is still too new and not widely supported by some programs.
Therefore, we will be installing Ubuntu Server on our Pi. Ubuntu is one of the most popular distros, and the Server version is simply a stripped-down version that only comes with a Command Line Interface (CLI), ommiting the resource-intensive Graphical User Interface (GUI) or "Desktop" that you usually interact with using a mouse.
First, navigate to https://www.raspberrypi.com/software/ and install the Raspberry Pi Imager. This tool allows you to easily configure and flash images of many different operating systems onto your Pi. An image is basically a copy of some files, in this case the entire operating system.
Take the microSD card out of your Pi and mount it on your PC. You can do this by either directly inserting the SD card into a card reader on your PC or by using a USB adapter.
Open Raspberry Pi Imager, and select your Pi device. For our workshop, we will be using Raspberry Pi 4.
Select the Operating System. As discussed above, we will be using Ubuntu Server. Scroll down to Other general-purpose OS, select Ubuntu, then scroll down to find `Ubuntu Server 24.04.2 LTS(64-bit).
LTS stands for Long Term Support. 24.04 is the latest LTS release of Ubuntu, meaning it will receive 5 years of free security upgrades, while other interim production releases only get 9 months of support.
Select your SD card or USB adapter as the Storage. The imager will overwrite everything in the selected storage device, so make sure you have backed up important files. Once that is done, click Next.
On the pop-up, click on Edit Settings.
You will be prompted to enter OS Customisation configurations:
- Set Host Name: This is how your device will appear in the local network. You can name it whatever you want.
- Set username and password: This is your Ubuntu login user. I usually set the username to
userfor simplicity. - Configure wireless LAN: This will allow your Pi to automatically connect to Wi-Fi on first boot. For our workshop, please input the following details:
| Setting | Attribute |
|---|---|
| SSID | RaspPiWorkshop |
| Password | password |
| Wireless LAN Country | AU |
- Set locale settings: This will affect the time sync and keyboard layout. Please select the following:
| Setting | Attribute |
|---|---|
| Time zone | Australia/Brisbane |
| Keyboard layout | US |
Navigate to the Services tab at the top of the pop-up, then check Enable SSH, and make sure that Use password authentication is selected. This will allow us to SSH into our Pi using the terminal app on our PC later. Click Save.
You will receive a warning about the storage device being wiped. Make sure that this is the correct storage device, then click Yes.
Patiently wait for the OS to be installed on the SD card. Once it is done, you can remove the SD card and pop it back into the Pi. Now the Pi is ready to go!
What is MERN?
It stands for:
- M = MongoDB: a document-oriented NoSQL database program
- E = Express.js: a back-end web application framework for building RESTful APIs
- R = React.js: a front-end JavaScript library for building UI out of components
- N = Node.js: a server-side JavaScript runtime environment
With these technologies, we can host a full-fledged web application with a powerful back-end, a flexible and interactive front-end, and a scalable database, all on a single device.
Let's get started on building this environment to host a MERN stack app!
Clone this repo by running this command:
git clone https://github.com/wongy123/CNHomeLabWorkshop.gitNavigate into the cloned repository by running this command:
cd CNHomeLabWorkshop/cd stands for Change Directory
Run the InstallDocker.sh script to install docker on your Pi.
Docker is a platform for running and managing standalone environments called Containers. Each container usually runs an application or service. We will be using Docker to host our MongoDB database, which will allow us to easily backup and migrate the entire database if necessary.
Run this installation script by running this command:
./InstallDocker.shThere are several ways you can run scripts on Linux.
./script.shThis will launch a new shell in the background to execute the script. It requires the user calling this command to have permission to execute the script file.. script.shThis will run all the commands in the script file as if you had just copied them into the terminal and run them. No execute permission needed.source script.shThis does the same thing as. script.sh.
The difference between ./ and source is that any changes to local shell variables made in ./ will not affect the current shell, while those in source will.
For example, in our StartMongoDB.sh, lines 3 to 6 set four local variables. If we run the script with ./StartMongoDB.sh and follow up with echo $CONTAINER_NAME, we will not see anything printed in response to the echo command as that variable does not exist in our current shell. However, if we run the script with source StartmongoDB.sh and follow up with echo $CONTAINER_NAME, we will see mongodb as a response.
Run the InstallNode.sh script to install Node.js using Node Version Manager (NVM). NVM is a tool that allows you to quickly install different versions of Node.
Run the following commands to install nvm and Node:
# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"
# Download and install Node.js:
nvm install 22
# Verify the Node.js version:
node -v # Should print "v22.18.0".
nvm current # Should print "v22.18.0".
# Verify npm version:
npm -v # Should print "10.9.3".Pull the image for MongoDB by running this command:
docker pull arm64v8/mongo:4.4.18An image is basically a snapshot of a container. Building the image allows you to replicate the container at the time the snapshot was taken.
Now that we have the docker image for MongoDB, let's build and run it. The StartMongoDB.sh script builds the image, sets its storage volume to be on the host's /srv/mongodb/data directory, and runs the "mongodb" container automatically.
Run this script by running this command:
./StartMongoDB.shFinally, let's install Caddy. Caddy is a web server that can also reverse proxy.
To install Caddy using the InstallCaddy.sh script, run this command:
./InstallCaddy.shYou can now start developing and hosting a MERN stack web application on your Raspberry Pi!
Navigate to http://<pi-ip-address>/ to see your Caddy page! (Replace <pi-ip-address> with your Pi's actual address)
StudyBuddy is an open-source web application written by Angus Wong using the MERN tech stack. In this workshop, we will show you how you can deploy the web app on the Pi we have just configured!
Let's clone the repo onto your Pi! First, we will run cd to make sure we are back in the user's home directory. Then we will clone the repo and navigate into the StudyBuddy directory.
We will also run a git checkout command to switch to a branch specifically created for this workshop. In this command, the -b flag creates a local branch that we are going to checkout to, and the --track flag specifies the remote branch that this local branch will be tracking, in this case being the NoSubDirectory branch hosted on GitHub.
cd
git clone https://github.com/wongy123/StudyBuddy.git
cd StudyBuddy
git checkout -b NoSubDirectory --track origin/NoSubDirectoryNavigate to the client directory and install the required packages via npm, Node's default package manager. A package manager is a tool for managing dependencies. Basically, when we run the install command, npm will look at the package.json file and install the specified versions of all the packages listed in it. This helps ensure that to a certain extent, the project will always build with the same version of the same packages no matter what computer you are building on, preventing the "it works on my machine" predicament.
cd client
npm install # or npm iThe StudyBuddy React app located in the client directory also comes with a deploy.sh script which automatically builds the app and copies the content into /var/www/html. By convention, /var/www/html is the root directory of a web server. When the client navigates to the web server's URL, a http GET request is sent to the server, and the html file located in the root directory gets served in a response to the client, displaying the webpage on their web browser.
./deploy.shNow, let's install the required packages for the back-end Express API.
cd ../server/ # .. means the parent directory
npm iThe StudyBuddy API uses JWT to generate authentication tokens for logged in users. We must create a .env file with a secret key. We will use the nano editor to create this file.
nano .envInside of the editor, type the following line and replace {YOUR_KEY} with your own JWT secret key. This can just be a random string of text. Then press ctrl + x to exit, and press y and enter to save the contents.
JWT_SECRET={YOUR_KEY}For more information on the build steps and how to create admin or moderator users in the StudyBuddy API, please read the How to run API of the READMD.md.
Our StudyBuddy app is built and ready for deployment. We need to run aother script from the CNHomeLabWorkshop repo to start the Express API in the background as a service. This does the same thing as just running node server.js inside of the StudyBuddy/server/ directory, but running the command requires keeping the terminal running, whereas running it as a service means it can run in the background, and we can start the service automatically on boot.
cd
cd CNHomeLabWorkshop/
sudo cp StartNodeServer.sh /usr/local/bin/
sudo cp start-node-express@.service /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable start-node-express@$USER
sudo systemctl start start-node-express@$USEROnce this is done, you can navigate to http://<your-ip-address>:4000 on your PC's web browser and you should see the text Welcome to StudyBuddy API! on the page.
This is the final step! We are going to configure Caddy to do two things:
- When receiving requests on the
/apisubdirectory, redirect those requests to the Express API running on port:4000 - When receiving requests on the
/root, serve the/var/www/html/index.htmlfile. This is our React webpage
sudo nano /etc/caddy/CaddyfileReplace the :80 block with the following content:
:80 {
handle /api/* {
reverse_proxy localhost:4000
}
handle /* {
root * /var/www/html
try_files {path} /index.html
file_server
}
}This Caddyfile configuration receives requests only on port :80. This is the port for http requests which is unencrypted. If you have your own domain and wish to deploy your web application there instead, simply replace the :80 with your domain name such as testproject.com, and Caddy will automatically request a TLS certificate from Let's Encrypt for your domain, allowing the use of https protocol.
Press Ctrl + x to exit the Nano editor, then press y and enter to save the contents.
Now, run this command to reload Caddy:
sudo systemctl restart caddyCongratulations!! You have completed all the steps required to deploy StudyBuddy on your Raspberry Pi!
You can now navigate to http://<your-ip-address> and you will see the StudyBuddy website! Make sure you use http instead of https as we do not have a TLS certificate for now!