Developing using Arch Linux on VirtualBox x86_64
with a systemd-nspawn container
/docs/gears/developer/setup/virtualbox/
Summary of the setup
Note
This setup is for VirtualBox users on x86_64
hardware, such as Intel Macs,
Intel Windows PCs, and Intel Linux boxes. It does not work on Apple Silicon.
In brief:
-
Download a virtual machine and run it in VirtualBox. It has all the tools you are going to need pre-installed – build tools, git, IDE etc.
-
In the virtual machine, run a single script to customize your setup for different types of things you might want to develop on UBOS.
Easy, right?
Prerequisites: install VirtualBox
- Download and install VirtualBox if you have not done so already.
Note
If you run other virtualization software on your machine (such as Hyper-V), you may need to turn that off before VirtualBox can run.
Steps in detail
-
Download the virtual appliance file. To do so, go to https://depot.ubosfiles.net/yellow/x86_64/images/index.html and look for a file whose name starts with
ubosdev
and has extension.ova
. If there are several files there with this extension, pick the one that has the most recent timestamp. -
In VirtualBox, select “File” / “Import Appliance…”
-
In section “Source”:
- Source: “Local File System” and then select the downloaded
.ova
file.
- Source: “Local File System” and then select the downloaded
-
In section “Settings”:
-
Change the default name to “ubosdev”.
-
For “MAC Address Policy:” “Generate new MAC addresses for all network adapters”.
-
“Additional Options”: “Import hard drives as VDI”.
-
Select “Finish”.
-
-
Importing the appliance will take a little bit of time. It will show up in the list of VMs as
ubosdev
or such. -
Start the VM.
-
Logon as
ubosdev
, there is no password.root
does not have a password either: we assume that’s safe enough on your computer. If you don’t think so, set one :-) -
Pick a better screen resolution:
- In “Search”, type “Settings” and run it.
- If there’s an error message saying “Network Unavailable” and “Error: NetworkManager not
running”: ignore it, we are not running Network Manager but
systemd-networkd
. - Select “Displays” and pick a resolution that makes sense for your computer setup.
- Close the settings app.
-
In “Search”, type “Console” and run it (you get the “Search” by selecting “Activities” in the menu bar).
-
Update your Arch host to the latest. First the package index, then package signing keys, then all installed packages:
% sudo pacman -Sy % sudo pacman -S archlinux-keyring % sudo pacman -Su
If there are a lot of updates (including the kernel, for example: look for updates to a package that starts with
linux-6.
…), reboot and resume from here after the system has come back up:% sudo systemctl reboot
-
Set up the UBOS development environment 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.
-
Once this command is complete, you can shutdown the VM any time if you like.
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. This setup so far has only installed one, which is good enough for most purposes.
To determine which container templates you 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. In this tutorial, we only instantiate one template once.
Ongoing development work
-
Run your Arch Linux development VM in VirtualBox.
-
To determine which UBOS Linux containers you have:
% ubosdev-container list
-
Inside your VirtualBox development VM, 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 viassh
, 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 theubosdev
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. -
To edit your code, the
geany
IDE is pre-installed on the Arch Linux host. Of course, you can install others from the Arch repositories or directly. -
You can 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
, typinghttp://ubosdev-yellow/
into your browser on the Arch Linux host will talk to the web server in your container. Firefox is pre-installed on the Arch Linux host.