Get started with UPboard and Node.js
In this guide we will build a simple Node.js web server project on a UPboard. At its most basic, the process for deploying code to a UPboard consists of two major steps:
- Setting up your UPboard with resinOS, the host OS that manages communication with resin.io and runs the core device operations.
- Pushing your Node.js project to the resin.io image builder, which pulls in all necessary dependencies and creates the container image for your application.
Once these steps are finished, your UPboard will download the container image, kick off your application, and begin sending logs to your resin.io dashboard!
What you will need
- A UP, currently we only support the first generation of the UPboard, but we will support the UP2 board in the future. See our supported devices list for other supported boards.
- A 4GB or larger USB drive.
- An ethernet cable or WiFi adapter. Check our list of supported WiFi adapters.
- A 5V @4A UPboard power supply.
- A USB keyboard.
- A HDMI LCD screen.
- A resin.io account.
If you find yourself stuck or confused, help is just a click away:
The troubleshooting section of the forums is where our engineers address any issues you may be having with resin.io.
We also have a community chat for more general discussion.
You can read about our approach to support at resin.io/support.
If you don't already have a resin.io account, make sure to sign up.
Adding an SSH Key
Resin.io uses git to push code from your computer to a dedicated repository. As part of the account creation process, you will be asked to add a public SSH key. The SSH key secures your connection to our server, letting us know you have the authority to make changes to the repository.
Note: You can click Skip to move past this step for now, but you will not be able to push code to your UPboard until you have added a public key to your account. This can be done at any time from the Preferences page on the dashboard.
If you have a public SSH key, simply paste it into the box provided and click Save Key:
You can also import your key from GitHub. If you choose this option, you will be asked to enter your GitHub username:
Don't have an SSH key?
If you are unfamiliar with SSH keys, we recommend you take a look at GitHub's excellent documentation. This will walk you through everything you need to create a key pair. Window's user? Be sure to check out these instructions.
Create an application
An application is a group of devices of the same type that all run the same code. When you provision a device, it is added to a specific application, but can be migrated to another application at any time.
To create an application, simply select the UPboard type from the drop-down list, type in a name, and click Create new application:
This will take you to the dashboard for your newly created application, where you can manage your whole fleet of UPboards.
Add your first device
To connect with resin.io, your UPboard will need a resinOS image that is configured for your application and your network. Start by clicking Add device in your application dashboard:
A list of available resinOS versions is shown in the dropdown. In general, the most recent version is recommend. You can also select whether you would prefer a Development or Production edition with a toggle:
Note: When you're first getting started, a Development image will be most useful, as it permits a number of testing and troubleshooting features. For production use, be sure to switch to a Production image. More details on the differences between Development and Production images can be found here.
A toggle is also used to select whether your network connection will be through Ethernet Only or with the option for WiFi + Ethernet. Selecting Wifi + Ethernet allows you to enter a WiFi SSID and WiFi Passphrase:
Clicking Advanced presents the option to select the rate at which your device checks for updates and the option to download just a configuration file (
config.json) rather than an entire image:
Once you have finished your image configuration, click the Download resinOS button. When the download completes, you should have a zipped image file with a name like
FirstApp is the name you gave your application on the dashboard.
The next step is to flash the downloaded image onto your USB drive using Etcher, a simple, cross platform USB drive writer and validator. Once you have Etcher installed, start it up. To give Etcher access to your USB drive, your system may prompt you to grant administrative privileges.
To create a bootable resinOS USB drive follow these steps:
- Click Select image and find your application's resinOS image file.
- If you haven't already done so, insert your USB drive into your computer. Etcher will automatically detect it. If you have more than one USB drive inserted, you will need to select the appropriate one.
- Click the Flash! button.
Etcher will now prepare a bootable USB drive and validate that it was flashed correctly. This can take roughly 3 or more minutes depending on the quality of your USB drive. You'll get a little ping when it's done, and Etcher will safely eject the USB drive for you.
Note: You can burn several USB drives with the same image file and all the devices will boot and provision into your application's fleet. You can also disable the auto-ejecting or validation steps from the Etcher settings panel.
Provision your device
In order to get resinOS up and running on your UPboard, you need to first set it up to boot from your USB drive rather than its internal eMMC memory. To do this, you will need to interrupt the boot process and direct the device to boot from your USB drive.
Note: ResinOS will completely write over the existing eMMC.
First, make sure the device is setup correctly:
- Ensure you have a HDMI screen attached and powered up.
- Make sure the the USB drive is plugged into one of the 4 available USB ports.
- Attach a USB keyboard to one of the other available USB ports.
- Attach a USB WiFi dongle or an ethernet cable to give the device access to the internet.
Now that you have your board setup, apply power to it using the supplied 5 Vdc barrel jack. Tap the
F7 key while the BIOS is loading in order to enter the device's boot menu. If all goes according to plan, you should see the boot menu as pictured below:
Using the keyboard arrow keys, select the the
UEFI : USB option and hit enter. Your UPboard will now boot from the USB drive and flash resinOS onto the internal eMMC memory. If your device is correctly connected to the internet, you should see progress of the flashing on your resin.io dashboard. Once resinOS is safely flashed onto the internal eMMC memory, the device will shut itself down and you should see all the user LEDs on the board switch off.
NOTE: The blue power LED will stay illuminated even once the device has shutdown. You can find the user LEDs on the underside of the board near the USB ports.
You can now remove the USB drive and power up the board again. Your UPboard should now be sitting happily waiting on the resin.io dashboard. If it still hasn't appeared after 1 or 2 minutes, double check your ethernet connection or that you entered the right WiFi credentials at download time. If you still can't get it online, contact us on support.
Now it's time to deploy some code!
Now that we have a device or two connected to a resin.io application, lets deploy some code and actually start building something.
To clone the project, run the following command in a terminal or your preferred git client:
$ git clone https://github.com/resin-io-projects/simple-server-node.git
Once the repo is cloned, change directory into the newly created
simple-server-node directory and add the resin git remote endpoint by running the command
git remote add shown in
the top-right corner of your application page:
$ cd simple-server-node $ git remote add resin <USERNAME>@git.resin.io:<USERNAME>/<APPNAME>.git
Note: On other git clients there may be an alternative way to add a remote repository.
So now we have set up a reference in our local git repository (the one on our development computer) to the resin.io application remote repository. So when we push new changes to this remote repository it will get compiled and built on our servers and deployed to every device in the application fleet.
Warning: The resin.io git repository is not intended as a code hosting solution, and we cannot guarantee the persistence of data in resin.io git remotes.
Now to deploy this code to all device(s) in the application just run the command:
$ git push resin master
If you want to completely replace the source code of the application with a new source tree, you may need to force the push by running
git push resin master --force, due to how git works.
Note: On your very first push, git may ask you if you would like to add this host to your list of allowed hosts. If the ECDSA key fingerprint matches
SHA256:NfwmqnKId5cx1RWpebbEuuM87bCJbdyhzRnqFES9Nnw, you are pushing to the right place. Type 'yes' to continue.
You'll know your code has been successfully compiled and built when our friendly unicorn mascot appears in your terminal:
This means your code is safely built and stored on our image registry. It should only take about 2 minutes to build your code and subsequent builds will be quicker because of build caching.
Your application will now be downloaded and executed by all the devices you have connected in your application fleet. You may have to wait about 6 minutes for the first push... So time for more tea, but don't worry, all subsequent pushes are much, much faster due to Docker layer sharing. You can see the progress of the device code updates on the device dashboard:
You should now have a node.js web server running on your device and see some logs on your dashboard. If you go to the
Actions page for your device, you can enable a public URL, this URL is accessible from anywhere in the world.
If you follow the URL, you will be served a page saying "Hello, World!". Alternatively you can point your browser to your devices IP address.
- Learn more about the Dockerfile that is used to build your application.
- Build an application that uses multiple containers.
- Get to know the web terminal, which can be used to SSH into your application containers and the host OS.
- Try out local mode, the most efficient way to rapidly develop and test your resin.io application.
These example projects will give you an idea of more things that can be done with resin.io:
SORRY! we currently don't have any other Node.js projects for the UPboard. How about submitting one to us at [email protected]?
Enjoy Resinifying All the Things!