Creating a Runtime

Creating a runtime is rather simple. All we need is a functional tree, which we can launch a sandbox in. This needs to provide all utilities and libraries you want to include, including all the basic ones. A simple way to do this is to simply start with a minimal distribution base as your tree, and then install things inside it. To make this easy, MaPS provides a minimal debian base to get started quickly.

Note that we only start out with the debian runtime to be able to make this example generic. In principle, one can base runtimes on top of other more specialized runtimes. It is a good idea to have the runtimes be as compact as possible, but size restrictions are not imposed.

Initialise a tree

There is no special "initialization" process, it amounts to simply populating a directory with a workable tree. Here, we checkout the debian base from the MaPS repository, and copy the tree into a directory of choice.

maps package --initialize /path/to/tree

Launch a sandbox into the tree

At this point, our tree is mutable. One can freely modify this even from the host OS, but its usually more straightforward to set up things inside sandbox. Any changes made to this tree will be saved into the runtime itself.

maps package --sandbox /path/to/tree

Commit your changes

Once the runtime is ready, commit the runtime into your ostree repository. It is recommended to name your runtime in the triplet of reverse-dns/architecture/version. For example, "com.example.package/x86_64/2023.08"

maps package --commit /path/to/tree rev.dns.package/arch/version

Publishing your runtime

You can can upload your runtime to an instance of the maps upload server by specifying your server URL and authentication credentials. If the runtime you are trying to upload is called com.example.package/x86_64/2023.08, then you can upload it to an example server.

export TUSTARGET="https://maps-upload-server.example.com"
export MTDAUTH="username:password"
maps --upload "com.example.package/x86_64/2023.08"

An official server is under development. The procedure to get credentials for the official server, as well as specifications of the official server for setting up third party servers will be published soon.

A Note on Fakeroot

Right now, you cannot execute chown, chgrp, chmod etc while inside the runtime. This is standard behaviour of Linux user namespaces, and is not a choice made by maps, but a limitation we must live with. This means, sometimes, installing packages will fail as the install scripts can have these operations. As a workaround, one can use fakeroot with the env var FAKEROOTDONTTRYCHOWN set to '1'.

export FAKEROOTDONTTRYCHOWN='1'
fakeroot apt install openssh-client