Install Fuchsia on a NUC

This guide provides instructions on how to install Fuchsia on a NUC (Next Unit of Computing) device.

The steps are:

Prerequisites.
Prepare the NUC.
Enable EFI booting.
Bootstrap the NUC.

1. Prerequisites

Before you start installing Fuchsia on a NUC device, make sure that you've completed the following tasks:

Get parts.
Build Fuchsia.
Prepare a USB drive.

Get parts

The following parts are required for this guide:

A NUC device (see example models)
A RAM stick (see example models)
An M.2 SSD stick (see example models)
A USB 3.0 flash drive
A keyboard
A mouse (Optional)
A monitor with an HDMI port
An HDMI cable
An Ethernet cable
A Phillips-head screwdriver (with a magnetic tip)

Build Fuchsia

Complete the Get started with Fuchsia guide to set up the Fuchsia development environment on your workstation.

If you have already completed the Get started guide above, do the following:

Set your build configuration to workstation.x64:
```
fx set workstation.x64
```
Build Fuchsia:
```
fx build
```
This generates a Fuchsia image you'll use later in the Bootstrap the NUC section.

Prepare a USB drive

Installing Fuchsia on a device requires you to prepare a bootable USB drive.

On a NUC, Fuchsia boots the device using a chain of bootloaders. The instructions in this section creates a bootable USB drive for Fuchsia, which handles the first two steps in the bootloader chain, Gigaboot and Zedboot .

Gigaboot is a UEFI boot shim with some limited functionality (for instance, netbooting and flashing). By default, Gigaboot chains into Zedboot, which is a bootloader built on top of Zircon. Zedboot then can boot the device into a Fuchsia product or allow you to pave a Fuchsia image to the device. (For more information on the bootable USB drive, see Prepare a USB flash drive to be a bootable disk.)

To prepare a bootable USB drive, do the following:

Plug the USB drive into your workstation.
Identify the path to the USB drive:
```
fx list-usb-disks
```
Create a Zedboot-based bootable USB drive:
```
fx mkzedboot <PATH_TO_USB_DRIVE>
```
Replace PATH_TO_USB_DRIVE with the path to the USB drive from the step above, for example:
```
$ fx mkzedboot /dev/disk2
```
This command creates a Zedboot-based bootable USB drive and ejects the drive.
Unplug the USB drive from the workstation.

You'll need this USB drive later in the Bootstrap the NUC section.

2. Prepare the NUC

Some NUC devices do not come with RAM or an SSD. In which case, you need to install them manually.

Figure 1. A NUC device and RAM and SSD sticks.

To install the RAM and SSD on your NUC, do the following:

Remove the Phillips screws on the bottom feet of the NUC.
Install the RAM.
Remove the Phillips screws that would hold the SSD in place.

Note: A Phillips screwdriver with a magnetic tip is useful here.
Install the SSD.
Mount the SSD in place using the screws from Step 3.
Put the bottom feet and screws back in.
Plug the power, monitor (via HDMI), and keyboard into the NUC.

3. Enable EFI booting

To enable EFI (Extensible Firmware Interface) booting on your NUC, do the following:

Reboot your NUC.
To enter the BIOS setup, press F2 while booting.
In the Boot Order window on the left, click the Legacy tab.
Uncheck Legacy Boot.
Click the Advanced button.
Confirm the following boot configuration:
- Under the Boot Priority tab:
  - UEFI Boot is checked.
- Under the Boot Configuration tab:
  - In the UEFI Boot window:
    - Boot USB Devices First is checked.
    - Boot Network Devices Last is checked.
    - Unlimited Network Boot Attempts is checked.
  - In the Boot Devices window:
    - USB is checked.
    - Network Boot is set to UEFI PXE & iSCSI.
- Under the Secure Boot tab:
  - Secure Boot is unchecked.
To save and exit BIOS, press F10 and click Yes.

4. Bootstrap the NUC

Installing Fuchsia on a device for the first time requires you to boot the device into Zedboot and pave a Fuchsia image to the device's storage.

To pave Fuchsia on your NUC, do the following:

Plug the Zedboot-based bootable USB drive into the NUC.
Connect the NUC directly to the workstation using an Ethernet cable (or connect the NUC to a router or WiFi modem in the same Local Area Network as the workstation).

Note: Network booting only works with the NUC's built-in Ethernet port – netbooting with an USB port (via an Ethernet-to-USB adapter) is not supported.
Reboot your NUC.

The NUC boots into Fuchsia's Zedboot mode, displaying Zedboot's signature blue screen.
On the Zedboot screen, press Alt + F3 to switch to a command-line prompt.

Note: If you cannot press Alt+F3 because the keyboard on the NUC is not working, see Keyboard not working after Zedboot in Troubleshoot.
On the NUC, view the HDD or SSD's block device path:
```
lsblk
```
Take note of the block device path (for example, the path might look like /dev/sys/platform/pci/00:17.0/ahci/sata0/block).

On the NUC, wipe and initialize the partition tables of the NUC:

install-disk-image wipe-partition-tables --block-device <BLOCK_DEVICE_PATH>

install-disk-image init-partition-tables --block-device <BLOCK_DEVICE_PATH>

Replace BLOCK_DEVICE_PATH with the block device path from the step above, for example:

$ install-disk-image wipe-partition-tables --block-device /dev/sys/platform/pci/00:17.0/ahci/sata0/block
$ install-disk-image init-partition-tables --block-device /dev/sys/platform/pci/00:17.0/ahci/sata0/block

On your workstation, pave the Fuchsia image to the NUC:
```
fx pave
```
When the paving is finished, unplug the USB drive from the NUC.

Fuchsia is now installed on your NUC. When you reboot the device, it will load Gigaboot, Zedboot, and Fuchsia all from your device's storage. So you don't need the USB drive plugged into the NUC any longer.

Later, if you need to install a new version of Fuchsia (for instance, after re-building a Fuchsia image using fx build), see the Flash a new Fuchsia image to the NUC section in Appendices.

Troubleshoot

Keyboard not working after Zedboot

In the Bootstrap the NUC section, after plugging the Zedboot USB drive into the NUC, if you notice that the keyboard on the NUC is not working, then skip Step 4 through 6 and perform the following workaround instead:

On your workstation, try to install Fuchsia on the NUC:
```
fx pave
```
This command may fail due to the partition tables issue on the NUC.

View the kernel logs:

fx klog

In the logs, look for an error message similar to the following:

Unable to find a valid GPT on this device with the expected partitions. Please run *one* of the following command(s):
fx init-partition-tables /dev/sys/platform/pci/00:17.0/ahci/sata0/block

To initialize the partition tables on the NUC, run the suggested command in the logs, for example:
```
$ fx init-partition-tables /dev/sys/platform/pci/00:17.0/ahci/sata0/block
```
Now, to install Fuchsia on the NUC, run the following command again:
```
fx pave
```

Paving or netbooting not working after Zedboot

In the Bootstrap the NUC section, after issuing an fx pave command, if paving does not complete, make sure the Ethernet cable is directly connected to the Ethernet port of the NUC, and is not using an Ethernet-to-USB adapter to connect to a USB port of the NUC – even though an Ethernet-to-USB adapter works after Fuchsia has been paved (for instance, when doing fx ota), the USB port doesn't work with Zedboot when paving.

Address already in use

In the Bootstrap the NUC section, when you run the fx pave command, you may run into the following error:

2022-01-20 15:23:00 [bootserver] cannot bind to [::]:33331 48: Address already in use
there may be another bootserver running

When you see this error, do the following:

Check the processes that are currently using the port 33331:

sudo lsof -i:33331

This command prints output similar to the following:

$ sudo lsof -i:33331
COMMAND   PID USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
ffx     69264 alice  15u  IPv6 0xb12345ed61b7e12d      0t0  UDP *:diamondport

Terminate all the processes in the list, for example:
```
kill 69264
```

Appendices

NUC models

For GPU support, get a NUC7 (Kaby Lake) or NUC8 (Coffee Lake), or a higher generation.

The list below shows some example models:

RAM and SSD models

The table below shows some RAM and SSD example models:

Item	Link	Notes
RAM	Crucial 8GB DDR4-2400 SODIMM	Works fine.
SSD	Samsung SSD 850 EVO SATA M.2 250GB	Works fine.
SSD	ADATA Ultimate SU800 M.2 2280 3D NAND SSD	Works fine.
SSD	CRUCIAL MX300 SSD	Works fine, but is discontinued.

Flash a new Fuchsia image to the NUC

Once a NUC is bootstrapped (via fx pave) and is running Fuchsia, you can start using Fuchsia's new flashing process to provision a new Fuchsia image to the NUC.

To flash a Fuchsia image to your NUC, do the following:

Connect the NUC directly to the workstation using an Ethernet cable (or connect the NUC to a router or WiFi modem in the same Local Area Network as the workstation).
Reboot your NUC.
To boot the NUC into Fastboot mode, press the f key at the Fuchsia boot screen.

Once the NUC is in Fastboot mode, you can see entering fastboot mode printed on the screen.

On your workstation, detect the NUC in Fastboot mode:

ffx target list

This command prints output similar to the following:

$ ffx target list
NAME                      SERIAL       TYPE       STATE       ADDRS/IP                           RCS
fuchsia-54b2-0389-644b    <unknown>    Unknown    Fastboot    [fe81::55b1:2ff:fe34:567b%en10]    N

Verify that the device's state is in Fastboot.

Flash a new Fuchsia image to the NUC:

Note: To build a new Fuchsia image, see the Build Fuchsia section above.
```
fx flash
```
When the flashing is finished, the NUC reboots and starts running the new Fuchsia image.

To confirm that the NUC is flashed successfully, run the following command:

ffx target list

This command prints output similar to the following:

$ ffx target list
NAME                      SERIAL       TYPE       STATE       ADDRS/IP                           RCS
fuchsia-54b2-0389-644b    <unknown>    Unknown    Product    [fe81::55b1:2ff:fe34:567b%en10]    N

Notice that the device's state is now Product.