how-to-run-locally.md

How to run aktualizr-lite Locally

The following is a guide on how to run aktualizr-lite on your local Linux®-based host against FoundriesFactory®.

Work Directory Setup

mkdir local-device-001 && cd local-device-001

Optional Setup: Docker Compose and Docker

Docker Compose

python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install docker-compose

Docker

Rootless Docker Prerequisites

apt install -y newuidmap newgidmap slirp4netns

More details can be found https://docs.docker.com/engine/security/rootless/

mkdir docker-data
wget https://raw.githubusercontent.com/docker/engine/master/contrib/dockerd-rootless.sh
chmod u+x dockerd-rootless.sh

Dependency: Ostree/Libostree

Aktualizr-lite requires libostree built with libcurl—not with libsoup which is the default in Ubuntu. If ostree --version | grep libcurl yields an empty result, then OSTree & libostree should be built & installed locally.

Configure, Build and Install OSTree/Libostree

libostree itself has a bunch of prerequisites. What is required depends on the host system, such as Distro, version, what is already installed, etc. See the full list of dependencies. Most likely, the following will be required:

apt install -y libgpgme11-dev libarchive-dev libcurl4-openssl-dev e2fslibs-dev libfuse-dev libp11-dev liblzma-dev

Next we fetch, configure, and build:

mkdir ostree && cd ostree
git init && git remote add origin https://github.com/ostreedev/ostree
git fetch origin v2018.9 && git checkout FETCH_HEAD

./autogen.sh CFLAGS='-Wno-error=missing-prototypes' --with-libarchive --disable-man --with-builtin-grub2-mkconfig --with-curl --without-soup --prefix=/usr
sudo make -j6 install

Make sure that ostree --version | grep libcurl produces libcurl. If it does not, try ldconfig or check for other installations of OSTree on the host.

Setup the Rootfs

This is the system rootfs that aktualizer-lite will be managing.

Init the System Rootfs

mkdir sysroot
export OS=lmp
export OSTREE_SYSROOT=$PWD/sysroot
ostree admin init-fs $OSTREE_SYSROOT
ostree admin os-init $OS
ostree config --repo="${OSTREE_SYSROOT}/ostree/repo" set core.mode bare-user

Download and Extract the System Rootfs OSTree Repo

This is generated by one of your Factory's CI builds. To obtain it:

fioctl targets artifacts <build-number> -f <factory> intel-corei7-64/other/intel-corei7-64-ostree_repo.tar.bz2 > ./intel-corei7-64-ostree_repo.tar.bz2
tar -xjf intel-corei7-64-ostree_repo.tar.bz2

Populate the Local System Rootfs

export deploy_hash=$(ostree --repo=ostree_repo rev-parse intel-corei7-64-lmp)
ostree --repo=sysroot/ostree/repo pull-local ostree_repo $deploy_hash

Deploy the Pulled Version of System Rootfs

ostree config --repo="${OSTREE_SYSROOT}/ostree/repo" set core.mode bare-user-only
ostree admin deploy --os=$OS $deploy_hash

Install YAML to JSON Tool

Aktualizr-lite uses libfyaml to consume docker.yml files in json format. In order to resolve that binary dependency we need to install it in the same host where aktualizr-lite will be executing. The LmP targets install v0.6.3 so to replicate that install:

cd /tmp/
wget https://github.com/pantoniou/libfyaml/releases/download/v0.6.3/libfyaml-0.6.3.tar.gz && tar xf libfyaml-0.6.3.tar.gz
cd libfyaml-0.6.3
./bootstrap.sh
./configure --prefix /usr
make
sudo make install
sudo ldconfig

Aktualizr-lite Registration and Configuration

Registration

Fetch and Build lmp-device-register

git clone https://github.com/foundriesio/lmp-device-register/
cd lmp-device-register
cmake -S . -B build -DDOCKER_COMPOSE_APP=ON -DHARDWARE_ID=intel-corei7-64 -DDEVICE_FACTORY=<factory-name>
cmake --build build --target all
ls build/lmp-device-register
cd ..

Get the API Token

$FACTORY_API_TOKEN can be obtain from your Factory page, make sure you have chosen at least devices:create scope for your API token.

DEVICE_FACTORY=<you-factory-name> lmp-device-register -d $PWD -n <device-name>  --start-daemon 0 -T $FACTORY_API_TOKEN
chmod 700 .

Configure Local Env

Create a toml file/snippet, e.g. local.toml with the following content:

[pacman]
os = "lmp"
sysroot = "$PWD/sysroot"
booted = "staged"
docker_compose_bin = "$PWD/venv/bin/docker-compose"
compose_apps_root = "$PWD/compose-apps"

#compose_apps = "app-06"
#tags = "master"

[bootloader]
reboot_sentinel_dir = $PWD
reboot_command = "/bin/true"

[uptane]
polling_sec = 6

Replace $PWD with your workdir. sed -i "s|\$PWD|$PWD|" local.toml

Run a Dedicated Dockerd Instance (optional)

In another terminal, or in background (nohup <cmd> &):

dockerd-rootless.sh --experimental -D --log-level debug --data-root $PWD/docker-data/

Make sure you run export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock in the terminal in which you are going to run aktualizr-lite

Run aktualizr-lite From the Workdir and Enjoy

$LITE -c . daemon

To emulate device reboot after the system rootfs update run rm need_reboot from the workdir, otherwise the next aktualizr-lite run/restart will be treated as a rollback.