diff --git a/docs/howto/howto-getting-started-foundriesio.md b/docs/howto/howto-getting-started-foundriesio.md index f772c4d..31648aa 100644 --- a/docs/howto/howto-getting-started-foundriesio.md +++ b/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 , or first create an account if you have not one. + +### Create a Factory + Browse > **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 - 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 + +In our example we will be creating a bootable microSD Card for the Raspberry Pi 4. + +#### Download LmP system image + +Login to , 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: 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: 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: mtu 1480 qdisc noop state DOWN group default qlen 1000 + link/sit 0.0.0.0 brd 0.0.0.0 +4: wlan0: 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: 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: + +From a console on the device run this command to register the device to your factory: + +```bash +sudo lmp-device-register -n +``` + +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 : + +![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 + diff --git a/docs/images/2022-05-11-1159-fio-targets.png b/docs/images/2022-05-11-1159-fio-targets.png new file mode 100644 index 0000000..d79762c Binary files /dev/null and b/docs/images/2022-05-11-1159-fio-targets.png differ diff --git a/docs/images/2022-05-11-1202-fio-target-details.png b/docs/images/2022-05-11-1202-fio-target-details.png new file mode 100644 index 0000000..318370c Binary files /dev/null and b/docs/images/2022-05-11-1202-fio-target-details.png differ diff --git a/docs/images/2022-05-11-1205-fio-target-run-details.png b/docs/images/2022-05-11-1205-fio-target-run-details.png new file mode 100644 index 0000000..f4b03c2 Binary files /dev/null and b/docs/images/2022-05-11-1205-fio-target-run-details.png differ diff --git a/docs/images/2022-05-11-1953-fio-activate.png b/docs/images/2022-05-11-1953-fio-activate.png new file mode 100644 index 0000000..641f5b5 Binary files /dev/null and b/docs/images/2022-05-11-1953-fio-activate.png differ diff --git a/docs/images/2022-05-11-1954-fio-activate-confirm.png b/docs/images/2022-05-11-1954-fio-activate-confirm.png new file mode 100644 index 0000000..26e9135 Binary files /dev/null and b/docs/images/2022-05-11-1954-fio-activate-confirm.png differ diff --git a/docs/images/2022-05-11-1956-fio-activate-complete.png b/docs/images/2022-05-11-1956-fio-activate-complete.png new file mode 100644 index 0000000..6f995c3 Binary files /dev/null and b/docs/images/2022-05-11-1956-fio-activate-complete.png differ diff --git a/docs/images/2022-05-11-1958-fio-devices.png b/docs/images/2022-05-11-1958-fio-devices.png new file mode 100644 index 0000000..ae3296e Binary files /dev/null and b/docs/images/2022-05-11-1958-fio-devices.png differ diff --git a/docs/images/2022-05-11-2002-fio-device-rpird102.png b/docs/images/2022-05-11-2002-fio-device-rpird102.png new file mode 100644 index 0000000..d110ff8 Binary files /dev/null and b/docs/images/2022-05-11-2002-fio-device-rpird102.png differ