Quick Start

This guide will get you up and running with several core Deviceplane features.

In three minutes, we'll show you how to register a device with Deviceplane, create and schedule an application, start receiving project metrics, and use the CLI to SSH into a device.

Signing up

Sign up or log in to Deviceplane. If it's your first time, create a new project. Otherwise, select the project you'd like to register a device on.

Registering a device

You don't have any devices registered yet, let's add one!

In order to register a device, we first need to install Docker on the device. An easy cross platform-way to do that is using the install script provided by Docker at get.docker.com on the device you want to register:

curl -fsSL https://get.docker.com | sh

After doing that, navigate to Devices on the sidebar, and click on "register device". It should give you a registration command that you can run on your device:

After your agent installs, you should be able to navigate back and see a device in your Devices sidebar tab!

Next, we'll create an application that will run on this device.

Creating and scheduling applications

Navigate to the Applications tab on the sidebar. Create an application, and name it "demo-go". We're going to be installing a simple application that mostly just provides metrics, and hosts a simple HTTP server on the device.

Let's create a release and add the following application config:

demo-go:
image: deviceplane/demo-go:latest
ports:
- 8080:8080

Note: this is based off of the demo-go image, for which the source code can be found on Github!

Now, let's schedule it onto our device. Go to the scheduling tab and select the "All Devices" option to schedule to all devices. This will schedule it to all devices that we add to our project. If we wanted to only schedule it to specific devices, we could add build a scheduling rule.

Now, take a look at our device. If we click on the device overview page, and scroll down to the Services section, we can see that our application's service is currently running on our device, with the release ID that we just created.

Click on the monitoring icon on that services row, and we can view the current metrics from that service. Next, let's see how we can forward these metrics.

Forwarding Metrics

Navigate to Monitoring on the sidebar. We need a Datadog API key for this part. If you don't plan to forward metrics to a metrics host, you can skip this part.

We'll get our API key and enter it in the Integrations tab.

Now, we can switch to the Service Metrics tab, and select the application/service we created in the last section. Click the "Add service metrics" button, and type in the wildcard character "*" in the metric name section to add all metrics. Then select the "Device" checkbox in the Properties section, and submit.

Switch to the Project Metrics tab, and enable the "Devices" metric with the "Device" checkbox checked.

And then switch to the Device Metrics tab, and add a couple device metrics. Add "Fileystem Size Bytes" and "Filesystem Free Bytes". These are useful for figuring out if our devices are running out of disk space.

Now that we've added all these metrics, let's switch into Datadog's metrics explorer. We should be able to type in "deviceplane" and have all of the metrics available via autocomplete. If you can't see the metrics populate, try refreshing the page.

This guide won't go into it, but you can also set alerts in Datadog, and use their Slack or Pagerduty integrations to get alerted.

SSH via CLI

The CLI enables you to perform most actions available in the UI, so you can quickly deploy, troubleshoot, and dig into issues via your terminal. It also offers output in JSON and YAML, so you can use it to write scriptable workflows. In this tutorial, we'll just show you how to SSH into a device using it. Note that you can also SSH into a device via the web UI.

First, let's download the CLI on your computer. If you click your user icon in the top right, you should see a dropdown that has "Download CLI" as one of the listed options. Click it, and select your OS.

Then, move the CLI to a folder in your $PATH, such as /usr/local/bin. This will let you run the deviceplane command anywhere, without needing the absolute file path. Afterwards, if you're on a UNIX-based system chmod +x [path to deviceplane], which will allow you to run the deviceplane command.

Now, you should be able to run deviceplane, and see the help output.

Let's generate a access key, so we can use the CLI to access our project.

Go to back to your browser, and in the same menu where you found "Download CLI", there should be an option to "Manage Access Keys". Click it, then create an access key. Copy the generated access key.

Go back to your CLI, run deviceplane configure, and enter your project name and your access key! You should now be able to run deviceplane device list to see the list of devices you have, as well as deviceplane ssh [device] to SSH into a device!

You're all set! Play around with the UI/CLI, or take a look at the rest of the docs to learn more.