Absolute Beginners guide to installing HA on Intel NUC using Docker

Installation
,
1

Target Audience

Hello everyone, this is a first guide I’m writing which should help people looking to upgrade from a Raspberry Pi to Intel NUC to run their Home Assistant instances.

Assumptions

At this point, I assume the following

  • You have a fair understanding of how Home Assistant works.
  • You should know Docker to a certain extent.
    • If you are new, then I would request you to stop here and go to their official getting started guide here, go through to at least Part 3 and only then come back to this thread.
    • I used this video as well, Learn Docker in 12 minutes
  • You have an Intel NUC available for use
  • Willing to learn a little bit of Linux (I started it 3 days before writing this article)
  • Does not get scared with commands :wink:

Install Options

There are multiple ways of running HA, and this is a place where I was confused the most as to which route to take and why? To save you a little trouble, here are the possible options

Hass.io via HassOS Image for Intel NUC

You can get the official image from here and proceed as per the installation article, i.e. burn SD card, configure the network, so on and so forth.

Pro’s
  • Familiar Hass.io interface
  • Add-ons support
  • Widely used and most common installation with RPi
Cons
  • Nothing specific here other than the fact that if you choose this path, then you would not be able to do anything else on your NUC. I would personally not recommend this because NUC is a powerhouse and you should utilize it like one.

Install on your Windows 10, Ubuntu Linux on NUC

Steps described here but trust me don’t choose this path either. Even the articles say getting a virtual environment.

Ubuntu on NUC with Docker

This is the way to go and is described in this guide. Docker works best with Linux systems, don’t even bother with Windows :wink:, I have been there and the experience sucks.

Pro’s
  • You get a full Operating System (Ubuntu) which you can utilize for anything, its like having an extra computer with you.
  • Docker ensures all of your HA needs are fulfilled without you worrying of setting up the environment
  • Anything goes wrong with docker, destroy the containers and rebuild, just takes max a minute to come up.
  • A whole community supporting this setup, so anything goes wrong, do a little google and trust me someone might have faced and fixed that problem already.
Cons
  • Nothing I can think of at this point, please let me know in the comments if you find one.

There are other options as well but we will stick to the most talked about. Alright, now that we decided the path to go, let’s start setting up the system.

Setting up NUC

Pre-requisites

  • Ensure you have a keyboard and mouse connected with your NUC, you would need it initially.
  • Ensure your internet is working, NUC should be connected to WiFi or Ethernet.
  • Ensure that your NUC gets a static IP address from your router.
  • NUC should be on the latest BIOS, see instructions here
  • Create a bootable Ubuntu installation USB stick
  • NUC has SSD and RAM connected, explaining this is beyond the scope of this guide but should not be difficult to do with a simple google search or watching a youtube video.

Installing Ubuntu

Attach the bootable USB stick which you created previously and Power up the NUC. It should directly take you to the Ubuntu installation, it’s essentially a next, next, finish dialog. Nothing complicated here.

Installing Docker on Ubuntu

Open Terminal on your system and execute the commands in series as they are mentioned. These will basically add docker repository on your machine and finally install Docker. For more information, go here to know what each of these commands does

sudo apt-get update

sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io

By now, you should have a working Docker system ready on your machine. The first thing that we are going to do is installing Portainer via a Docker container. This will allow us to work with our local containers.

Installing Portainer (GUI for managing Docker containers)

In your terminal, execute the commands below

  1. Create a volume for Portainer Data
sudo docker volume create portainer_data
  1. Run Portainer in detach mode
docker run -d -p 9000:9000 --restart always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer

By now, you will have the Portainer GUI setup and running which you can access at http://localhost:9000 or http://:9000

The first time you log-in, it will ask you to create your user account, please go ahead and do that and after successful login, it will showcase a screen to choose which docker environment you want to choose, select Local from that list and you should finally see a screen like below

image
image2065×936 101 KB

Alright, we are all set with Portainer, let proceed onto installing Home Assistant

Install Home Assistant

We are going to take the official path of the installation here and use the following docker command.

Note, we are using /srv/homeautomation to store all of our docker containers, because typically in linux /srv folder is used to serve any content like website pages, etc. Also, it is not mandatory to use this folder.

docker run -d --name="home-assistant" --restart unless-stopped -v /srv/homeautomation/hass-config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant

It is going to download the docker image for you, this might take some time depending on your internet connection. Once done, you should be able to access your instance on http://localhost:8123 or http://your-nuc-ip-address:8123

From here on, things are pretty simple because you have already done this before. Just create a new user, login to HA and your Home Assistant is now working.

Note: This is not a hass.io installation, so no add-ons will work. If you were previously using any add-ons, those will have to be installed in separate docker containers

Mosquitto MQTT Installation

The most common requirement is to have an MQTT broker installed. For this, again, we are going to create another docker container which will connect to the local HA instance which we created above.

  1. Create volume for Mosquitto data
docker create volume mosquitto_data
  1. Create a blank file in the location where you want MQTT config to reside. Since I mentioned that all of our docker containers are residing under /srv/homeautomation/ folder, we will choose the same path.
    1. Create a folder called mosquitto under /srv/homeautomation/. Next, you need to create a blank mosquitto.conf file, this is the file which contains all the configuration related to your MQTT instance
sudo mkdir /srv/homeautomation/mosquitto

sudo touch /srv/homeautomation/mosquitto/mosquitto.conf
  1. Now we are ready to execute the docker run command and create a new container for Mosquitto
sudo docker run -itd \
--name="mosquitto" \
--restart on-failure \
-p 1883:1883 \
-p 9001:9001 \
-v /srv/homeautomation/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf \
-v mosquitto_data:/mosquitto/data \
-v mosquitto_data:/mosquitto/log \
eclipse-mosquitto
  1. This will create and run the MQTT container, check the portainer and you should see a new container running. The next thing we have to do is create an MQTT user which will be used to connect to our broker. This needs to be done inside the container where the broker is installed. In order to execute commands inside the container, we use the following:
sudo docker exec -it mosquitto sh

This will put us right back into the container’s shell and we’ll execute another command there

mosquitto_passwd -c /mosquitto/config/pwfile hass

where hass is the username. This command will prompt to enter credentials twice, please do that and you are done. Just exit the container’s shell by typing exit and hitting enter, this should put you back onto your Ubuntu’s terminal.

  1. The final thing that we have to do is to tell the broker about using the password file pwfile we just created. This is where we will modify the mosquitto.conf file which we created earlier. The problem with updating this file is that as a normal Ubuntu user, you would not have the required permissions to modify the file and that is where we are going to use sudo
sudo gedit /srv/homeautomation/mosquitto/mosquitto.conf

Go ahead and append the following line and save the file

password_file /mosquitto/config/pwfile
  1. Once this is done, you need to restart your mosquitto container for the changes to take effect. This can easily be done by going on Portainer >> Containers >> mosquitto and pressing the restart button at the top.
    image
    image1559×862 80 KB

This concludes our MQTT installation. Just configure MQTT component by modifying the configuration.yaml file as usual.

Modifying configurations

Alright, now that your HA is ready, MQTT is ready, we can go ahead and configure our entities. At this point, I would either install vscode (my preferred code editor) or work with syncthing (this is something very new that I have learned) or use the sudo gedit <file-name> to update the configurations.

Ubuntu should never sleep

To ensure that your Ubuntu is never going in sleep mode and always running, here is the command that you need to execute in your terminal

systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

In case, at a later stage, if you wish to enable sleeping then just modify the above command and replace mask with unmask

That’s all!

At this point, we have come to an end of this long guide. However there are a few todo items that I will potentially add if you guys are really interested but so far you should have a working HA instance on your NUC along with MQTT.

TODO: Update this post with SyncThing setup
TODO: Add AppDaemon setup

Quick note on Syncthing

It a tool which will allow you to keep your configurations in sync across devices. Since your NUC will mostly be running without a keyboard, mouse and a screen, it is going to be very difficult for you to modify the configurations. With this tool, you will be able to make changes from a different machine, like your laptop and those changes will sync to your NUC’s HA container.

Also, please let me know if there are any errors, or better ways of doing some of the things that I mentioned, also if you want to see something else as well covered in this guide

39 Likes
2

Good guide but there is another option.

Installing hassio on docker using the official documentation.

5 Likes
3

Are you by any chance referring to https://www.home-assistant.io/blog/2017/11/29/hassio-virtual-machine/?

4

No. The official documentation lists hassio on docker.

1 Like
5

Got it, I may have missed it but will update the guide detailing this setup as well. However, what would you say on the advantages of hassio against a standalone HA setup? Is it just mere convenience (having add-ons, etc) or there are some performance benefits as well?

6

Personally I don’t see any, but I know a lot of people like this configuration.

Just add-ons and snapshots like people would be accustomed to after ditching a hassio setup on a pi. No performance benefits at all. Just ease of use for beginners.

3 Likes
7

I have some issue with this command. Change it to the following resolve the issue.

sudo docker volume create portainer_data

2 Likes
8

Thanks! I was having the same issue.

9

This line was giving me “no such file” errors, it should read:
mosquitto_passwd -c /mosquitto/config/pwfile hass

10

Thanks @Nts and @Strider for the corrections. I have updated the post accordingly.

2 Likes
11

You’re welcome @piyush. Thank you for all the work you put into this guide, it was exactly what I was looking for and worked great!

1 Like
12

Thanks @piyush for this guide, it help me to get started with home assistant on docker. I did not use an Intel NUC but just running on a old laptop.

1 Like
13

@piyush great guide! You say that your favorite way to run HA on a NUC is with docker so you can run other things. I am not new to HA but I am new to home servers. What other services do you recommend running in parallel?

14

I run Unifi controller for my ubiquiti AP, databases, Plex, sonaar, radaar, lidaar to manage my media collection, syncthing, etc.

1 Like
15

Great guide, thank you. Ive installed HA as above but would prefer hass.io, how would I go about changing that.

Do I run everything here:

sudo -i

apt-get install software-properties-common

add-apt-repository universe

apt-get update

apt-get install -y apparmor-utils apt-transport-https avahi-daemon ca-certificates curl dbus jq network-manager socat

curl -fsSL get.docker.com | sh

curl -sL "https://raw.githubusercontent.com/home-assistant/hassio-build/master/install/hassio_install" | bash -s

but delete the line

curl -fsSL get.docker.com | sh

My lack of understanding tells me the above line reinstalls docker which I don’t need as that’s already done???

16

I made it to here:

garyk@hassnuc:~$ docker run -d -p 9000:9000 --restart always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer
docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post http://%2Fvar%2Frun%2Fdocker.sock/v1.39/containers/create: dial unix /var/run/docker.sock: connect: permission denied.

After executing this command:

garyk@hassnuc:~$ sudo usermod -aG docker garyk

17

You need to log out and back in for it to take effect.

18

Thank you.

19

Lots of stuff like mosquitto, portainer etc are hassio addons, and managing these via hassio is super easy compared to docker commands or, to a lesser extent, docker-compose.

1 Like
20

My plan, let me know if I’m wrong, is to install is to install hassio/ha in a container. Other containers I’d like to have are OpenSSH and Samba communicating with the host and the hassio/ha container. Is this reasonable? If so, where could I find instructions to go forward?