Developing on an Arch Linux workstation

/docs/gears/developer/setup/arch/

Prerequisites

These instructions assume you have a working (physical or virtual) development system running Arch Linux or Arch Linux ARM. Either an x64_64 or an ARM (aarch64) system will work.

It is not required, but if you can, run btrfs as the file system of your home directory. Its copy-on-write functionality will save you some disk space and some time.

Allow the Linux container to reach the internet

Your Arch Linux workstation must allow the development container (that you will create below) to reach the public internet. This is because:

  • The container must be able to install software from the Depot; and:
  • Many kinds of software you might run in the container need to interact with a web service on the public internet.

By default, your setup may not permit this.

How to configure your Arch Linux workstation to permit this depends on how you set up networking, but one common approach is to add these two lines:

IPv4Forwarding=1
IPv6Forwarding=1

to the [Network] section in your systemd .network file, such as /etc/systemd/network/wired.network (the name of your file will likely be different), so it looks something like this:

[Match]
Name=en*

[Network]
DHCP=ipv4
IPv4Forwarding=1
IPv6Forwarding=1

Add UBOS development tools

  1. Add the UBOS keyring so you can install the development tool packages:

    # curl -O https://depot.ubosfiles.net/yellow/$(uname -m)/os/ubos-keyring-0.9-2-any.pkg.tar.xz
# pacman -U ubos-keyring-0.9-2-any.pkg.tar.xz
# rm ubos-keyring-0.9-2-any.pkg.tar.xz

  2. Add the UBOS tools repo:

    # echo '' >> /etc/pacman.conf
# echo '[ubos-tools-arch]' >> /etc/pacman.conf
# echo 'Server = https://depot.ubosfiles.net/yellow/$arch/ubos-tools-arch' >> /etc/pacman.conf

  3. Install the packages:

    # pacman -Sy
# pacman -S ubos-tools-arch

  4. Initialize the UBOS development tools by running:

    % ubosdev-container setup

    This sets up development on the yellow release channel, which is the recommended channel for development.

    This might take 5-30 min, depending on your network, computer and disk speed.

Setting up a container for development

You will perform your actual UBOS development in a Linux container that runs UBOS Linux. In this setup, you can have multiple UBOS Linux container templates, and each of them can be instantiated multiple times.

For example, you might have different container templates for the different UBOS Release Channels.

To determine which container templates you currently have available (that depends on the previous step):

% ubosdev-container list-templates

Instantiate one of the available templates into a container to be used for development, such as:

% ubosdev-container create --name ubosdev-yellow --template ubos-develop-yellow

You can instantiate this template multiple times, in case you have multiple workstreams going and want to keep them separate. Or if you want several virtual Devices communicate with each other. In this tutorial, we only instantiate one template once.

Ongoing development work

  • To determine which UBOS Linux containers you have:

    % ubosdev-container list

  • Run your UBOS Linux container:

    % ubosdev-container run --name <name>

    where <name> is the name of an available container, e.g. ubosdev-yellow.

    This gives you console access to the container. This command is simply a wrapper around the systemd-nspawn command with options that are useful. You could run it directly, too.

    You shut down the container with 3 quick ^]s in the primary container console.

  • To open up a non-root shell inside your development container, if ubosdev-yellow is the name of your container, open a new terminal and execute:

    % sudo machinectl shell ubosdev@ubosdev-yellow

    This essentially does the same thing as if you were to log into your container as user ubosdev from the console or via ssh, but you don’t need to have any credentials set up.

  • When you run the container with ubosdev-container run, your home directory on your Arch Linux host will be the same as the home directory of the ubosdev user in the UBOS Linux container. This makes development much simpler because you can edit files either on the host or in the container; they are the same.

  • Depending on your networking setup, you may be able to connect to a Site running inside the UBOS Linux development container by using the container’s name as the hostname in the URL. So if one of your running containers is named ubosdev-yellow, typing http://ubosdev-yellow/ into your browser on the Arch Linux host may talk to the web server in your container.