Merge pull request #331 from B-AROL-O/feat/update-gs-foundries

[Feat] Update HOWTO: Getting started with Foundries.io

docs/howto/howto-getting-started-foundriesio.md

@@ -14,6 +14,10 @@ FoundriesFactory is a cloud service to build, test, deploy, and maintain secure,
 
 ## Step-by-step instructions
 
+Login to <https://app.foundries.io/>, or first create an account if you have not one.
+
+### Create a Factory
+
 Browse <https://app.foundries.io/factories>
 
 > **No Factories**
@@ -91,4 +95,211 @@ Review the displayed information, check "I agree", then click "Create Factory".
 
 ![2022-04-30-0911-fio-factories-test-fio-raspi4.png](../images/2022-04-30-0911-fio-factories-test-fio-raspi4.png)
 
+### Inspect the built system images
+
+If you click on tab "Targets" you will find the list of completed builds:
+
+![2022-05-11-1159-fio-targets.png](../images/2022-05-11-1159-fio-targets.png)
+
+As an example, click on version "2" to display the details of this specific target build:
+
+![2022-05-11-1202-fio-target-details.png](../images/2022-05-11-1202-fio-target-details.png)
+
+If you expand the "Runs" panel you have access to the build artifacts:
+
+![2022-05-11-1205-fio-target-run-details.png](../images/2022-05-11-1205-fio-target-run-details.png)
+
+Click on a specific artifact to display its contents.
+
+### Install the `fioctl` tool
+
+Install the `fioctl` tool following the instructions at <https://docs.foundries.io/latest/getting-started/install-fioctl/index.html> - for instance, on Linux
+
+```bash
+export FIOCTL_VERSION=v0.25
+sudo curl -o /usr/local/bin/fioctl -LO https://github.com/foundriesio/fioctl/releases/download/$FIOCTL_VERSION/fioctl-linux-amd64
+sudo chmod +x /usr/local/bin/fioctl
+```
+
+Verify the correct installation of `fioctl`
+
+```text
+gmacario@hw2228:~ $ fioctl
+Manage Foundries Factories
+
+Usage:
+  fioctl [command]
+
+Available Commands:
+  completion       Generate completion script
+  config           Manage configuration common to all devices in a factory
+  configure-docker Configure a hub.foundries.io Docker credential helper
+  devices          Manage devices registered to a factory
+  event-queues     Manage event queues configured for a Factory
+  help             Help about any command
+  keys             Manage keys in use by your factory fleet
+  login            Access Foundries.io services with your client credentials
+  logout           Remove Foundries.io client credentials from system
+  secrets          Manage secret crendentials configured in a factory
+  status           Get dashboard view of a factory and its devices
+  targets          Manage factory's TUF targets
+  teams            List teams belonging to a FoundriesFactory
+  users            List users with access to a FoundriesFactory
+  version          Show version information of this tool.
+  waves            Manage factory's waves
+
+Flags:
+  -c, --config string   config file (default is $HOME/.config/fioctl.yaml)
+  -h, --help            help for fioctl
+  -v, --verbose         Print verbose logging
+
+Use "fioctl [command] --help" for more information about a command.
+gmacario@hw2228:~ $
+```
+
+### Flash your device
+
+Follow the instructions at <https://docs.foundries.io/latest/getting-started/flash-device/index.html>
+
+In our example we will be creating a bootable microSD Card for the Raspberry Pi 4.
+
+#### Download LmP system image
+
+Login to <https://app.foundries.io/>, then select a Factory which you have access to - in our example, `test-fio-raspi4`.
+
+(Optional) Take note of the Source URLs and their related Commits - in our example:
+
+| Source | Commit |
+|--------|--------|
+| [test-fio-raspi4/lmp-manifest.git](https://source.foundries.io/factories/test-fio-raspi4/lmp-manifest.git) | [500142e1](https://source.foundries.io/factories/test-fio-raspi4/lmp-manifest.git/commit/?id=500142e17aa6480eb4428c1ca9b7466ed45f7396)
+| [test-fio-raspi4/meta-subscriber-overrides.git](https://source.foundries.io/factories/test-fio-raspi4/meta-subscriber-overrides.git) | [f594d249](https://source.foundries.io/factories/test-fio-raspi4/meta-subscriber-overrides.git/commit/?id=f594d249aabada5535a95606127651f79f0be85b) |
+
+
+Navigate to the "Targets" section of your Factory, then click the latest Target with the `platform-devel` Trigger. Expand the run in the "Runs" section with corresponds with the name of the board, then click "Download Simulator" (TBV).
+
+In our example, this operation will download file `lmp-factory-image-raspberrypi4-64.wic.gz` (218 MB).
+
+#### Flash LmP system image
+
+Write the image to a blank microSD Card using a tool such as [balenaEtcher](https://www.balena.io/etcher/).
+
+#### Boot Device and Connect to the Network
+
+1. Connect an Ethernet cable to the board
+2. Insert the microSD into the Raspberry Pi and
+3. Power up the board
+
+You board will connect to the network via Ethernet and will be ready to connect within a minute or two of booting.
+
+```text
+Linux-microPlatform 3.4.3-1-86-4-g500142e raspberrypi4-64 tty1
+
+raspberrypi4-64 login:
+```
+
+Default username/password: `fio`/`fio`
+
+Verify assigned IP address
+
+```text
+fio@raspberrypi4-64:~$ ip addr
+1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+    inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+    inet6 ::1/128 scope host
+       valid_lft forever preferred_lft forever
+2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
+    link/ether e4:5f:01:35:8f:96 brd ff:ff:ff:ff:ff:ff
+    inet 192.168.64.174/24 brd 192.168.64.255 scope global dynamic noprefixroute eth0
+       valid_lft 43123sec preferred_lft 43123sec
+    inet6 fdaf:ad6a:c9df::17a/128 scope global noprefixroute
+       valid_lft forever preferred_lft forever
+    inet6 fdaf:ad6a:c9df:0:d17:705f:18ab:1617/64 scope global noprefixroute
+       valid_lft forever preferred_lft forever
+    inet6 fe80::eab4:9416:5a41:8b86/64 scope link noprefixroute
+       valid_lft forever preferred_lft forever
+3: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN group default qlen 1000
+    link/sit 0.0.0.0 brd 0.0.0.0
+4: wlan0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN group default qlen 1000
+    link/ether ce:fd:ee:3d:6e:47 brd ff:ff:ff:ff:ff:ff permaddr dc:a6:32:4e:db:b2
+5: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default
+    link/ether 02:42:4f:27:c0:b7 brd ff:ff:ff:ff:ff:ff
+    inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0
+       valid_lft forever preferred_lft forever
+fio@raspberrypi4-64:~$
+```
+
+### Register your device
+
+Reference: <https://docs.foundries.io/latest/getting-started/register-device/index.html>
+
+From a console on the device run this command to register the device to your factory:
+
+```bash
+sudo lmp-device-register -n <device-name>
+```
+
+Example:
+
+```text
+fio@raspberrypi4-64:~$ sudo lmp-device-register -n rpird102
+Password:
+Token is not specified, getting an oauth token from Foundries' auth endpoint...
+
+----------------------------------------------------------------------------
+Visit the link below in your browser to authorize this new device. This link
+will expire in 15 minutes.
+  Device Name: 1f658bf4-cfb1-4546-88cf-01577b67da1b
+  User code: yDeY-Aevh
+  Browser URL: https://app.foundries.io/activate/
+
+Waiting for authorization /
+```
+
+From your browser visit the displayed URL <https://app.foundries.io/activate/>:
+
+![2022-05-11-1953-fio-activate.png](../images/2022-05-11-1953-fio-activate.png)
+
+Type the specified User code, then click "Next":
+
+![2022-05-11-1954-fio-activate-confirm.png](../images/2022-05-11-1954-fio-activate-confirm.png)
+
+Verify the displayed UUID, then click "Connect" if OK.
+
+![2022-05-11-1956-fio-activate-complete.png](../images/2022-05-11-1956-fio-activate-complete.png)
+
+Some more messages will be displayed on the console:
+
+```text
+fio@raspberrypi4-64:~$ sudo lmp-device-register -n rpird102
+Password:
+Token is not specified, getting an oauth token from Foundries' auth endpoint...
+
+----------------------------------------------------------------------------
+Visit the link below in your browser to authorize this new device. This link
+will expire in 15 minutes.
+  Device Name: 1f658bf4-cfb1-4546-88cf-01577b67da1b
+  User code: yDeY-Aevh
+  Browser URL: https://app.foundries.io/activate/
+
+Registering device, rpird102, to factory test-fio-raspi4.
+Device UUID: 1f658bf4-cfb1-4546-88cf-01577b67da1b
+Device is now registered.
+Starting aktualizr-lite daemon
+fio@raspberrypi4-64:~$
+```
+
+Verify on the "Devices" tab of the Factories page that the new device is now in the list of registered devices:
+
+![2022-05-11-1958-fio-devices.png](../images/2022-05-11-1958-fio-devices.png)
+
+Click on the device to get more details:
+
+![2022-05-11-2002-fio-device-rpird102.png](../images/2022-05-11-2002-fio-device-rpird102.png)
+
+NOTE: This device was registered on Gianpaolo RPi4, TBV whether the image will also work on the actual `rpird102`.
+
+TODO
+
 <!-- EOF -->