DEV Community: Naomi Pentrel

An award-winning devportal is more than words

Naomi Pentrel — Wed, 07 Jan 2026 11:32:49 +0000

A reflection on 3 years as a Head of Developer Content.

The Viam docs cover a complex and large developer platform, SDKs in multiple languages and APIs that move at the speed of, well, a startup. And for that the docs received several awards.
But where did it start? This Web Archive capture shows what they looked like three years ago, before I started.

My team and I got to work, and a year after that humble starting point, the docs had transformed into something worth reading. We had won multiple awards at the Devportal awards, including the Best Overall SME Devportal award: we were on the right track.

Improving the docs website

A good docs portal isn't just about the technical writing: it is, after all, a website that users of your product have to interact with most days. With that in mind, we also made it a point to add usability features.

dynamic elements that allowed for filtering changelog entries, tutorials, and modules (the latter long before the product): A combination of Typesense, an open source search engine, and Algolia's InstantSearch.js, an open source UI library allowed us to add these dynamic components to our otherwise static site.
In text glossary items that show more info on hover. Hugo is a wonderful framework for creating docs sites if you want to add customization but don't want to use front-end frameworks to build components or the entire thing. In this case I was able to lean on and learn from the work that the writers at K8s had built, who also use Hugo.
Using GIFs to show features & hardware in action: I decided early on to lean on imagery to bring the product to live, because I feel hardware actuation is best conveyed that way. And with Hugo I was able to add shortcodes to allow us to serve GIFs as more bandwidth-friendly videos. Generally I used Hugo a lot to enforce SEO rules.

Automation with GitHub Actions

Keeping on top of the documentation surface area for a complex platform, whilst also maintaining a user-facing web application, is no small feat for a small team. We did what we could to make ends meet. Namely: automation. In our case with GitHub Actions:

Style guide checking with Vale - a linter that is focused on prose. After creating regexes that cover the rules from a style guide. Luckily Vale is a long time favourite of mine which I first found at MongoDB and used to write the rules they still use 5 years later - and which were later were released by someone else.
Code sample testing - I wrote an entire testing suite by putting code samples in files with project setup and teardown and markup to delineate the code samples. This allowed me to then use GitHub Actions and some bash scripts to automatically run the tests and to generate the code samples from them based on the markup delineations. While the initial cost is a bit higher - the end result was e2e tests that caught API changes and outages and provided confidence in the code samples.
Tooling to find dead links and surface links that needed forwarding. Htmltest is a great tool to check for broken links but checking for links that have gone away and should be forwarded was a bit harder. I finally solved this with a Netlify integration (I believe it was No more 404s). Netlify also helped me move from HTML level forwarding to HTTP level forwarding.

Generative AI

We also did a lot with generative AI. I wrote a POC for a tool that would update docs based on information from a PR, and then found a vendor that did this even better. Reviewing AI-generated content still requires enormous diligence - but something to look out for in the future. AI chat is far more advanced, and I was somewhat surprised how useful it was - if and only if used with diligence in fact checking.

I find myself wishing that people viewed generative AI output as a different kind of search, because I think this view of it retains the need for critical review better. I think we as an industry have some work to do in improving user literacy around how generative AI works, as it’s too easy for users to expect generative AI to have capabilities it doesn’t have (and to entrust AI chats with passwords and secrets).

The learnings from our AI usage can easily span multiple blog posts. So I’ll leave it at saying that if you’re looking for prebuilt embeddable AI chat tooling, I’d recommend Inkeep.

A single source of truth: SDK docs and "main" docs

Lastly, we leveraged automatic docs generation to reduce our workload. For example, we automatically generated main platform documentation from SDK docs. When I realized people had been copying code samples from SDK docs to the main docs (and vice versa), I pushed for a single source of truth. Code samples that show how to use individual API functions should live with the SDK. The SDK docs are generated from the docstrings in the SDK code, so this also meant that the docs were colocated with the code and therefore more likely to be up to date. So we built a system to ingest the SDK docs and generate parts of the main docs automatically. As the system ran, we were able to see and review new changes, and make edits to the SDK docs if needed. The result was better consistency and less work.

Conclusion

While the docs weren't all I worked on, they are the work I took most pride in. And 3 years later, as I hand over the docs, there is still work to be done - but I am happy with what we accomplished in the time.

Take a look for yourself: https://docs.viam.com/

Print, Paint, and Program a Guardian to Track Humans and Dogs Using a Pi, Camera, and Servo

Naomi Pentrel — Wed, 09 Aug 2023 11:57:19 +0000

In the run up to the new Zelda release, I realized you can build a stationary guardian robot with a servo and a camera.
Adding a bit of machine learning, you can then make the guardian detect objects or people or pets and follow them around by rotating its head.
Luckily, I am not the first one to have the idea to build a guardian and there was already a brilliant guardian 3D model on Thingiverse with space for LEDs and a servo.

In this tutorial, I will walk you through the steps to build your own functional guardian with a servo, a camera, some LEDs and the ML Model service and vision service.
Here's a video of the finished guardian detecting me:

Hardware requirements

To build your own guardian robot, you need the following hardware:

Hardware	Approximate price
Raspberry Pi + power cable	$60
Raspberry Pi Camera v1.3 + 50cm ribbon cable: The default 15cm ribbon cable is not long enough.	$15
180 degree SG90 servo: Because of the camera ribbon, I restricted the servo to only 180 degrees.	$4
3x 10mm RGB LEDs with common cathode	$4
cables	$5
4x M2 screws to attach the camera	$2
speaker: Optional if you want music. I used a 4Ω 2W speaker with connected aux in. You can use any speaker you can connect to your Pi.	Optional

Print or order the following printed 3D parts:

this head which fits the camera
the decorations for the head from this Guardian Robot model
the body, base cover, claws, and leg segments from the Guardian Robot, Hackable

To make the guardian's lights shine through its body, use filament that allows the light to shine through and paint the parts that shouldn't allow light to shine through.

Optionally, if you want to decorate your guardian, I recommend the following materials:

primer: Vallego Surface Primer Grey or other brand.
acrylic paint: I ordered armour modelling paint but found that mixing my own colors from a regular acrylic paint set worked best for me.
modeling grass, stones, glue: The Army Painter makes a Battlefields Basing Set which comes with all of this.
a base for the guardian: I used a wooden disk with a hole cut in the middle and a box with a hole in the top underneath.
ground texture: If you want the base to look more natural, you can use Vallejo Ground Texture Acrylic or something similar to create patches that look like stone.
wire: To allow you to position the legs better, you can thread wire through them.

Software requirements

You will use the following software in this tutorial:

Python 3
viam-server: Follow the installation instructions to install viam-server on your Raspberry Pi.

Assemble the robot

You can view a timelapse of the robot assembly here:
https://imgur.com/gallery/3sCrNh4

Assemble for testing

To assemble the guardian, start with the head and use four M2 screws to screw the camera with attached ribbon cable to the front half of the head.
Optionally, if the green of the camera is visible from the outside, use a marker to color the camera board.
Then put both parts of the head together.

Your servo probably came with mounting screws and a plastic horn for the gear.
Use the screws to attach the horn to the base of the head.

Next, get your Raspberry Pi and your servo and connect the servo to the Raspberry Pi by connecting the PWM wire to pin 12, the power wire to pin 2, and the ground wire to pin 8.

To make it easier for you to see which pin is which, you can print out this Raspberry Pi Leaf which has labels for the pins and carefully push it onto the pins or fold or cut it so you can hold it up to the Raspberry Pi pins.
If you use A4 paper, use this this Raspberry Pi Leaf instead.

If you are having trouble punching the pins through, you can pre-punch the pin holes with a pen.
Only attach the paper when the Pi is unplugged.
To make attaching the paper easier, use a credit card or a small screwdriver.

Then attach the head to the servo.

Next, get the three 10mm RGB LEDs ready.
Attach the common cathode of each LED to a ground pin on your Raspberry Pi.
Attach the wires for the red and the blue LEDs to GPIO pins.

Before continuing with assembly, you should test your components work as expected.
To be able to test the components, you need to install viam-server and configure your components.

Install `viam-server` and connect to your robot

Go to the Viam app and create a new robot called guardian.

Go to the Setup tab of your new robot's page and follow the steps to install viam-server on your computer.

Configure the components

Navigate to the Config tab of your robot's page in the Viam app.
Click on the Components subtab and navigate to the Create component menu.

Add the board.

Enter local for the name for your board component, select the type board, and select the pi model.
Then click Create component.
Add the camera.

Create a camera component with the name cam, the type camera and the model webcam.
Click Create Component to add the camera.
In the new camera panel, click the Video Path field to reveal a drop-down populated with camera paths that have been identified on your machine.
Select mmal service 16.1 (platform:bcm2835_v4l2-0).
Add the servo.

Create a servo component with the name servo, the type servo and the model pi.
Click Create Component to add the servo.
Configure the attributes by adding the name of your board, local, and the pin number of the pin on local that you connected your servo PWM wire to, 12:
```
{
    "pin": "12",
    "board": "local"
}
```

Click Save config in the bottom left corner of the screen.

Test the components

Navigate to your robot's Control tab to test your components.

Click on the servo panel and increase or decrease the servo angle to test that the servo moves.

Next, click on the board panel.
The board panel allows you to get and set pin states.
Set the pin states for the pins your LEDs are connected to to high to test that they light up.

Next, click on the camera panel and toggle the camera on to test that you get video from your camera.

Assemble and decorate

Now that you have tested your components, you can disconnect them again, paint and decorate your guardian, and then put the rest of the guardian together.
Remove the servo horn, and place one LED in the back of the Guardian head, leaving the wires hanging out behind the ribbon camera.

Then place the servo inside the Guardian body and attach the horn on the head to the servo's gear.
Carefully place the remaining two LEDs in opposite directions inside the body.
Thread all the cables through the hole in the lid for the base of the guardian, and close the lid.

Use a suitable base with a hole, like a box with a hole cut into the top, to place your guardian on top of and reconnect all the wires to the Raspberry Pi.

At this point also connect the speaker to your Raspberry Pi.

Then test the components on the robot's Control tab again to ensure everything still works.

Detect persons and pets

For the guardian to be able to detect living beings, you can use this Machine Learning model.
The model can detect a variety of things which you can see in the associated labels.txt file.

You can also train your own custom model based on images from your robot but the provided Machine Learning model is a good one to start with.

To use the provided Machine Learning model, copy the effdet0.tflite file and the labels.txt to your Raspberry Pi:

scp effdet0.tflite pi@guardian.local:/home/pi/effdet0.tflite
scp labels.txt pi@guardian.local:/home/pi/labels.txt

Next, navigate to the Config tab of your robot's page in the Viam app.
Click on the Services subtab and navigate to the Create service menu.

Add a ML model service.
The ML model service allows you to deploy the provided machine learning model to your robot.
Create an ML model with the name mlmodel, the type mlmodel and the model tflite_cpu.
Then click Create Service.
In the new ML Model panel, select Path to Existing Model On Robot for the Deployment.
Then specify the absolute Model Path as /home/pi/effdet0.tflite and the Label Path as /home/pi/labels.txt.
Add a vision service.
Next, add a detector as a vision service to be able to make use of the ML model.
Create an vision service with the name detector, the type vision and the model mlmodel.
Then click Create Service.
In the new detector panel, select the mlmodel you configured in the previous step.
Click Save config in the bottom left corner of the screen.
Add a transform camera.
To be able to test that the vision service is working, add a transform camera which will add bounding boxes and labels around the objects the service detects.
Click on the Components subtab and navigate to the Create component menu.
Create a transform camera with the name transform_cam, the type camera and the model transform.
Replace the attributes JSON object with the following object which specifies the camera source that the transform camera will be using and defines a pipeline that adds the defined detector:

   {
   "source": "cam",
   "pipeline": [
       {
       "type": "detections",
       "attributes": {
           "detector_name": "detector",
           "confidence_threshold": 0.6
       }
       }
   ]
   }

Click Save config in the bottom left corner of the screen.

Navigate to your robot's Control tab to test the transform camera.
Click on the transform camera panel and toggle the camera on, then point your camera at a person or pet to test if the vision service detects them.
You should see bounding boxes with labels around different objects.

Program the Guardian

With the guardian completely configured and the configuration tested, it's time to make the robot guardian behave like a "real" guardian by programming the person and pet detection, lights, music, and movement.

The full code is available at the end of the tutorials.

Set up the Python environment

We are going to use Virtualenv to set up a virtual environment for this project, in order to isolate the dependencies of this project from other projects.
Run the following commands in your command-line to install virtualenv, set up an environment venv and activate it:

python3 -m pip install --user virtualenv
python3 -m venv env
source env/bin/activate

Now, install the Python Viam SDK and the VLC module:

pip3 install viam-sdk python-vlc

Connect

Next, go to the Code sample tab on your robot page and select Python, then click Copy.

This code snippet imports all the necessary packages and sets up a connection with the Viam app in the cloud.

Next, create a file named main.py and paste the boilerplate code from the Code sample tab of the Viam app into your file.
Then, save your file.

Run the code to verify that the Viam SDK is properly installed and that the viam-server instance on your robot is live.

You can run your code by typing the following into your terminal:

python3 main.py

The program prints a list of robot resources.

On top of the packages that the code sample snippet imports, add the random and the vlc package to the imports.
The top of your code should now look like this:

import asyncio
import random
import vlc

from viam.robot.client import RobotClient
from viam.rpc.dial import Credentials, DialOptions
from viam.components.board import Board
from viam.components.camera import Camera
from viam.components.servo import Servo
from viam.services.vision import VisionClient

async def connect():
    creds = Credentials(
        type='robot-location-secret',
        payload='LOCATION SECRET FROM THE VIAM APP')
    opts = RobotClient.Options(
        refresh_interval=0,
        dial_options=DialOptions(credentials=creds)
    )
    return await RobotClient.at_address('ADDRESS FROM THE VIAM APP', opts)

You will update the main() method later.

Lighting

Next, you'll write the code to manage the LEDs.
Underneath the connect() function, add the following class which allows you to create groups of LEDs that you can then turn on and off with one method call:

class LedGroup:
    def __init__(self, group):
        print("group")
        self.group = group

    async def led_state(self, on):
        for pin in self.group:
            await pin.set(on)

If you want to test this code, change your main() method to:

async def main():
    robot = await connect()
    local = Board.from_robot(robot, 'local')
    red_leds = LedGroup([
        await local.gpio_pin_by_name('22'),
        await local.gpio_pin_by_name('24'),
        await local.gpio_pin_by_name('26')
    ])
    blue_leds = LedGroup([
        await local.gpio_pin_by_name('11'),
        await local.gpio_pin_by_name('13'),
        await local.gpio_pin_by_name('15')
    ])

    await blue_leds.led_state(True)

You can test the code by running:

python3 main.py

Your Guardian lights up blue.

Detections

Now, you'll add the code for the Guardian to detect persons and pets.
If you are building it for persons or cats or dogs, you'll want to use Person, Dog, Cat, and, if you have a particularly teddy-bear-like dog, Teddy bear.
You can also specify different ones based on the available labels in labels.txt.

Above the connect() method, add the following variable which defines the labels that you want to look for in detections:

LIVING_OBJECTS = ["Person", "Dog", "Cat", "Teddy bear"]

Then, above the main() method add the following function which checks detections for living creatures as they are defined in the LIVING_OBJECTS variable.

async def check_for_living_creatures(detections):
    for d in detections:
        if d.confidence > 0.6 and d.class_name in LIVING_OBJECTS:
            print("detected")
            return d

Idling

Underneath the check_for_living_creatures() function, add the following function which gets images from the Guardian's camera and checks them for living creatures and if none are detected moves the servo randomly.
If a creature is detected, the red LEDs will light up and music will play.

async def idle_and_check_for_living_creatures(cam, detector, servo, blue_leds, red_leds, music_player):
    living_creature = None
    while True:
        random_number_checks = random.randint(0, 5)
        if music_player.is_playing():
            random_number_checks = 15
        for i in range(random_number_checks):
            detections = await detector.get_detections_from_camera(cam)
            living_creature = await check_for_living_creatures(detections)
            if living_creature:
                await red_leds.led_state(True)
                await blue_leds.led_state(False)
                if not music_player.is_playing():
                    music_player.play()
                return living_creature
        print("START IDLE")
        await blue_leds.led_state(True)
        await red_leds.led_state(False)
        if music_player.is_playing():
            music_player.stop()
        await servo.move(random.randint(0, 180))

Focus

There is one last function that you need to add before you can write the full main() function and that is a function to focus on a given creature.
The function calculates the center of the detected object and then checks if that center is close to the middle of the entire image.
If it is not near the middle of the entire image, the function moves the servo to the left or right to attempt to center the object.

Add the following function above your main() function:

async def focus_on_creature(creature, width, servo):
    creature_midpoint = (creature.x_max + creature.x_min)/2
    image_midpoint = width/2
    center_min = image_midpoint - 0.2*image_midpoint
    center_max = image_midpoint + 0.2*image_midpoint

    movement = (image_midpoint - creature_midpoint)/image_midpoint
    angular_scale = 20
    print("MOVE BY: ")
    print(int(angular_scale*movement))

    servo_angle = await servo.get_position()
    if (creature_midpoint < center_min or creature_midpoint > center_max):
        servo_angle = servo_angle + int(angular_scale*movement)
        if servo_angle > 180:
            servo_angle = 180
        if servo_angle < 0:
            servo_angle = 0

        if servo_angle >= 0 and servo_angle <= 180:
            await servo.move(servo_angle)

    servo_return_value = await servo.get_position()
    print(f"servo get_position return value: {servo_return_value}")

Main logic

The main logic for the guardian robot:

initializes all the variables
turns all LEDs blue
loads a music file guardian.mp3
runs an infinite loop where it calls the idle_and_check_for_living_creatures() function and when a creature is found calls the focus_on_creature() function

Copy a suitable music file to the directory where your code is running and name it guardian.mp3.

Replace your main() function with the following:

async def main():
    robot = await connect()
    local = Board.from_robot(robot, 'local')
    cam = Camera.from_robot(robot, "cam")
    img = await cam.get_image()
    servo = Servo.from_robot(robot, "servo")
    red_leds = LedGroup([
        await local.gpio_pin_by_name('22'),
        await local.gpio_pin_by_name('24'),
        await local.gpio_pin_by_name('26')
    ])
    blue_leds = LedGroup([
        await local.gpio_pin_by_name('11'),
        await local.gpio_pin_by_name('13'),
        await local.gpio_pin_by_name('15')
    ])

    await blue_leds.led_state(True)

    music_player = vlc.MediaPlayer("guardian.mp3")

    # grab Viam's vision service for the detector
    detector = VisionClient.from_robot(robot, "detector")
    while True:
        # move head periodically left and right until movement is spotted.
        living_creature = await idle_and_check_for_living_creatures(cam, detector, servo, blue_leds, red_leds, music_player)
        await focus_on_creature(living_creature, img.width, servo)
    # Don't forget to close the robot when you're done!
    await robot.close()

if __name__ == '__main__':
    asyncio.run(main())

Now, run the code:

python3 main.py

If everything works, your guardian should now start to idle and when it detects humans or dogs or cats turn red, start music, and focus on the detected being.

Run the program automatically

One more thing.
Right now, you have to run the code manually every time you want your Guardian to work.
You can also configure Viam to automatically run your code as a process.

To be able to run the Python script from your Raspberry Pi, you need to install the Python SDK on your Raspberry Pi and copy your code onto the Raspberry Pi.

ssh into your Pi and install pip:

sudo apt install python3-pip

Create a folder guardian inside your home directory:

mkdir guardian

Then install the Viam Python SDK and the VLC module into that folder:

pip3 install --target=guardian viam-sdk python-vlc

Exit out of your connection to your Pi and use scp to copy your code to your Pi into your new folder.
Your hostname may be different:

scp main.py pi@guardian.local:/home/pi/guardian/main.py

Also copy your music file over:

scp guardian.mp3 pi@guardian.local:/home/pi/guardian/guardian.mp3

Now navigate to the Config tab of your robot's page in the Viam app.
Click on the Processes subtab and navigate to the Create process menu.

Enter main as the process name and click Create process.

In the new process panel, enter python3 as the executable, main.py as the argument, and the working directory of your Raspberry Pi as /home/pi/guardian.
Click on Add argument.

Click Save config in the bottom left corner of the screen.

Now your guardian starts behaving like a guardian automatically once booted!

Next steps

You now have a functioning guardian robot which you can use to monitor your pets or people. Or simply use to greet you when you get back to your desk.

Of course, you’re free to adapt the code to make it do something else, add more LEDs, or even train your own custom model to use.

Full Code

import asyncio
import random
import vlc

from viam.robot.client import RobotClient
from viam.rpc.dial import Credentials, DialOptions
from viam.components.board import Board
from viam.components.camera import Camera
from viam.components.servo import Servo
from viam.services.vision import VisionClient

LIVING_OBJECTS = ["Person", "Dog", "Cat", "Teddy bear"]


async def connect():
    creds = Credentials(
        type='robot-location-secret',
        payload='SECRET_FROM_VIAM_APP')
    opts = RobotClient.Options(
        refresh_interval=0,
        dial_options=DialOptions(credentials=creds)
    )
    return await RobotClient.at_address('guardian-main.vw3iu72d8n.viam.cloud', opts)


async def check_for_living_creatures(detections):
    for d in detections:
        if d.confidence > 0.6 and d.class_name in LIVING_OBJECTS:
            print("detected")
            return d


async def focus_on_creature(creature, width, servo):
    creature_midpoint = (creature.x_max + creature.x_min)/2
    image_midpoint = width/2
    center_min = image_midpoint - 0.2*image_midpoint
    center_max = image_midpoint + 0.2*image_midpoint

    movement = (image_midpoint - creature_midpoint)/image_midpoint
    angular_scale = 20
    print("MOVE BY: ")
    print(int(angular_scale*movement))

    servo_angle = await servo.get_position()
    if (creature_midpoint < center_min or creature_midpoint > center_max):
        servo_angle = servo_angle + int(angular_scale*movement)
        if servo_angle > 180:
            servo_angle = 180
        if servo_angle < 0:
            servo_angle = 0

        if servo_angle >= 0 and servo_angle <= 180:
            await servo.move(servo_angle)

    servo_return_value = await servo.get_position()
    print(f"servo get_position return value: {servo_return_value}")


class LedGroup:
    def __init__(self, group):
        print("group")
        self.group = group

    async def led_state(self, on):
        for pin in self.group:
            await pin.set(on)


async def idle_and_check_for_living_creatures(cam, detector, servo, blue_leds, red_leds, music_player):
    living_creature = None
    while True:
        random_number_checks = random.randint(0, 5)
        if music_player.is_playing():
            random_number_checks = 15
        for i in range(random_number_checks):
            detections = await detector.get_detections_from_camera(cam)
            living_creature = await check_for_living_creatures(detections)
            if living_creature:
                await red_leds.led_state(True)
                await blue_leds.led_state(False)
                if not music_player.is_playing():
                    music_player.play()
                return living_creature
        print("START IDLE")
        await blue_leds.led_state(True)
        await red_leds.led_state(False)
        if music_player.is_playing():
            music_player.stop()
        await servo.move(random.randint(0, 180))


async def main():
    robot = await connect()
    local = Board.from_robot(robot, 'local')
    cam = Camera.from_robot(robot, "cam")
    img = await cam.get_image()
    servo = Servo.from_robot(robot, "servo")
    red_leds = LedGroup([
        await local.gpio_pin_by_name('22'),
        await local.gpio_pin_by_name('24'),
        await local.gpio_pin_by_name('26')
    ])
    blue_leds = LedGroup([
        await local.gpio_pin_by_name('11'),
        await local.gpio_pin_by_name('13'),
        await local.gpio_pin_by_name('15')
    ])

    await blue_leds.led_state(True)

    music_player = vlc.MediaPlayer("guardian.mp3")

    # grab Viam's vision service for the detector
    detector = VisionClient.from_robot(robot, "detector")
    while True:
        # move head periodically left and right until movement is spotted.
        living_creature = await idle_and_check_for_living_creatures(cam, detector, servo, blue_leds, red_leds, music_player)
        await focus_on_creature(living_creature, img.width, servo)
    # Don't forget to close the robot when you're done!
    await robot.close()

if __name__ == '__main__':
    asyncio.run(main())

Docker Containers vs VMs

Naomi Pentrel — Sun, 21 Jul 2019 15:26:11 +0000

Virtual Machines (VMs) and Docker containers are two technologies that can help with resource utilization, enabling you to run multiple apps in isolated environments on the same infrastructure.

Given a terminal on a VM or a container, either will behave much as though it was in fact a dedicated machine. This can make it hard to differentiate between VMs and containers, especially if you are just getting started with Docker. To help with that, this blog post will show you how both function under the hood, while pointing out their similarities and differences. No previous knowledge of VMs or containers is necessary for this post.

Virtual Machines and Containers

VMs have been around for a long time, allowing physical machines to run multiple operating systems and multiple isolated apps. VMs are similar to "regular" physical computers: they run an operating system, have a lot of libraries installed, and run applications. The difference is that a virtual machine does not have its own dedicated hardware. Instead, VMs use the physical machine's underlying infrastructure through software that imitates dedicated hardware. The software that virtualizes hardware for VMs is called a hypervisor.

Source: https://docs.docker.com/get-started/#containers-and-virtual-machines

The fact that each VM has its own operating system makes VMs require quite a bit of storage and other resources. To reduce the needed resources per running application, people came up with containers.

While containerization had been around for a while on various operating systems, the community rallied behind Docker which was first released in 2013. During that time, the tech world (and the DevOps world in particular) was looking for solutions that would make deploying and scaling microservices more efficient. Docker managed to address that need by making Linux's LXC containerization easier to use and more accessible. They took the heavy lifting and planning that usually went into configuring a container and turned it into writing a Docker file which then did that work for you. This ease of use is what made Docker so popular; the fact that Docker was open source from the start certainly also helped.

Containers allow developers to minimize the resources they need by only packaging an application and its exact dependencies. Instead of running on a hypervisor the containers run on top of a container runtime environment which is installed on an operating system. While VMs use virtualized hardware, containers use underlying resources of the host operating system.

Source: https://docs.docker.com/get-started/#containers-and-virtual-machines

Comparing VMs and containers to houses and apartments can help make these differences more apparent: A house has its own water pipes, its own internet cable, and its own garbage disposal system. Apartments on the other hand have these resources managed by their apartment complex and can access the resources of the entire building without having to each have their own separate version. House rules ensure that apartment residents do not irritate each other and get a fair share of all resources.

Virtual Machines are like houses in this comparison. They each have their own operating system with its own dedicated resources (e.g. kernel, filesystem, process tree, network stack). The VM accesses CPU, storage, RAM etc. through a hypervisor which virtualizes the hardware.

Containers are much more like apartments. They only have exactly what they need to run their application. They share the underlying operating system's resources (e.g. kernel, filesystem, process tree, network stack) which are isolated by the container runtime environment which enforces rules around the resources particular containers have access to. Overall, this model makes containers a much more lightweight solution.

These differences in how containers and VMs function under the hood make containers a lot faster to provision and means they are often (and generally should be) used as immutable, non-persistent constructs. Containers live and die and are largely not something you ought to care about (unless they all die at the same time!). VMs, on the other hand, often have a longer life span, you spend more time configuring them and you probably care if something happens to them.

On a high level, the differences between containers and VMs can be summarized by saying that VMs are considered to be a virtualization technology and containers an application delivery technology.

Learn more

This was our concise overview of VMs and containers. If you are interested to learn more, check out:

Docker Jargon: FROM Dockerfile to Container

Naomi Pentrel — Sun, 21 Jul 2019 15:25:32 +0000

There are quite a few terms that get thrown around in the Docker community. Even the word Docker has a (slightly hidden) meaning. In Docker Deep Dive Nigel Poulton explains that "the word 'Docker' comes from a British colloquialism meaning dock work_er_ - somebody who loads and unloads cargo ships."

While you can use Docker without knowing where its name originated from, it is important that you know the jargon. To that end, this blog post will show you the main terms in the Docker world along with their meaning.

If you’re new to Docker or have always wanted a more thorough explanation, this post is for you. You do not need any special knowledge to follow along. After reading this post you will know the meaning of the following terms:

Docker
Docker Container
Docker Image
Dockerfile
Layers
Docker Volumes
Docker Engine
Image Registries

Docker markets itself as a container platform that helps developers build, ship, and run any application in any environment. Apps written on your computer will run the exact same way on your friend's computer, a bare metal server, the cloud, etc. That includes hosts with different operating systems such as Windows and Mac computers. To run Linux containers on both of these, Docker uses a light-weight Linux VM that operates on top of a hypervisor (xhyve for Mac and Hyper-V or VirtualBox for Windows).

You can look at the benefits of Docker from the perspective of two groups of people: DevOps folks, and developers. If you're a developer, the benefit of Docker is that you can set up one environment which you can use for both testing and for production. Iterating on, testing, and deploying changes should be very fast. On top of that, containers solve the problem of 'it works for me'-bugs because everything will be exactly the same regardless where you deploy. If you do DevOps, containers allow you to focus more on container management while removing the responsibility of configuring machines. Now that you know about Docker, the next step is Docker containers.

A container packages code and dependencies together to create a light-weight, abstracted, portable app. Containerizing apps allows you to maximize the utilization of a machine's resources by allowing you to run many apps. Each container is run in its own isolated environment. Docker containers are created on top of Docker Images.

A Docker Image can be thought of as a blueprint of an application. It's important to understand the difference between images and containers: An image is not the same as a running container - it's merely a snapshot of a container. Given such a snapshot the Docker engine knows how to create a container when a docker run command is issued but the snapshot itself is only a lifeless read-only blueprint.

A way to remember this is René Magritte’s famous painting The treachery of Images in which he cleverly depicted a pipe under which he wrote ‘Ceci n’est pas une pipe’ meaning ‘This is not a pipe’.

To build such a snapshot, you use a Dockerfile, i.e. a file on disk that contains instructions for creating an image. When you issue a docker build command, Docker uses a base image (e.g. a centos image or a ubuntu image). On top of the base image Docker executes each instruction within the Dockerfile to produce a new Docker Image. The file changes that occur when each instruction is executed are stored as a read-only filesystem, also called a layer. Most images consist of multiple layers (one for each line of instructions from the Dockerfile that was used to create the image). Since all layers are read-only the Docker Image is immutable.

Source: https://docs.docker.com/terms/images/docker-filesystems-multilayer.png

When a container is run, the Docker engine, in particular its storage engine, takes care of presenting the layers that form an image as a single unified object (somewhat similar to git commits). On top of this unified object, the Docker engine then adds a read-write filesystem which makes it an actual container. Any file changes that occur happen inside this top layer which is the only layer that can be modified when a container is run. This setup makes containers very resource-efficient, as multiple containers can be run using the same image.

Source: https://docs.docker.com/storage/storagedriver/

The read-writable layer on top of the image within a container is meant to be thin and is not designed to hold persistent data. If you do need to have persistent data, Docker suggests to use Docker Volumes. Volumes are independent constructs that can be attached to containers. If a container is killed or dies, the volume will still be accessible even if the container is removed. With containers you generally shouldn't care about them dying or being killed, because they are not special and you can easily create new ones. Tools like Kubernetes allow you to automatically spin up new containers should anything happen to the running ones.

Containers, Images, and Volumes are all managed by the Docker Engine which needs to be installed on top of an operating system. The Docker Engine is a client-server application made up of the Docker daemon, a REST API that specifies interfaces for interacting with the daemon, and a command line interface (CLI). When you issue a Docker command on the command line, the Docker CLI will use the daemon's REST API to communicate with the daemon. The daemon will in turn work with the host operating system to allocate operating system resources (CPU, storage, etc) for containers.

Source: http://orhandogan.net/docker/

The last thing to mention are Image Registries like Docker Hub, Google Container Registry, and Azure Container Registry. These fulfill a similar function GitHub fulfills for code: they host Docker images which can be used by yourself and others. Docker Hub has a library full of official images like this MongoDB image. You can use these official images as base images for your own images. If you would like to look at the Dockerfiles that were used to create the official images, you can find the links to them on the pages of the official images. It's also possible to host your own private registry of images.

Learn more

This concludes our overview of Docker Jargon. If you are interested to learn more, check out:

DEV Community: Naomi Pentrel

An award-winning devportal is more than words

Improving the docs website

Automation with GitHub Actions

Generative AI

A single source of truth: SDK docs and "main" docs

Conclusion

Print, Paint, and Program a Guardian to Track Humans and Dogs Using a Pi, Camera, and Servo

Hardware requirements

Software requirements

Assemble the robot

Assemble for testing

Install viam-server and connect to your robot

Configure the components

Test the components

Assemble and decorate

Detect persons and pets

Program the Guardian

Set up the Python environment

Connect

Lighting

Detections

Idling

Focus

Main logic

Run the program automatically

Next steps

Full Code

Docker Containers vs VMs

Virtual Machines and Containers

Learn more

Docker Jargon: FROM Dockerfile to Container

Learn more

Install `viam-server` and connect to your robot