how-to-run-locally.md

How to run altualizr-lite locally

The following is a guide on how to run aktualizr-lite on your local Linux-based host against the Foundries Factory.

Work dir setup

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

Optionally setup docker-compose and docker for your setup

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

Check for ostree/libostree and build it if needed

Aktualizr-lite requires libostree built with libcurl not with libsoup which is so by default in Ubuntu. So if ostree --version | grep libcurl yields an empty result then ostree&libostree should be built&install on a local system.

Configure, build and install ostree/libostree

libostree itself has a bunch of prerequisites. What specifically is required to install depends on a host system details, distribution, version, what is already installed, etc. Full list of dependencies can be found here. Most likely the following will be required to install

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

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 not try ldconfig or check for other installation of ostree on a host.

Setup a system rootfs that aktualizr-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 a system rootfs ostree repo generated by one of the CI builds of your Factory

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 with the Factory ostree repo

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 API token

$FACTORY_API_TOKEN can be obtain from https://app.foundries.io/settings/tokens/, 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 .

Configuration for 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 work dir. sed -i "s|\$PWD|$PWD|" local.toml

Run dedicated dockerd instance (optionally)

In another terminal, or run in background (nohup &)

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 th terminal in which you are going to run aktualizr-lite

Run aktualizr-lite from the work dir and enjoy...

$LITE -c . daemon

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