Ocean container tutorial¶
What do you need to build an Ocean package ?¶
Rift : It’s a python tool that allows to build RPM package from specfiles (or src.rpm) and test it in virtual machine with a single command.
Ocean git repository : This git repository contains all Ocean packages specfiles and the Rift configuration.
Ocean Annex : This where sources files of the packages are stocked (this like a git lfs).
We provide a Docker container image which contains all the dependencies needed to build an Ocean package.
How to run the Ocean Container ?¶
Requirements¶
In order to run this container you will need :
Linux (Docker desktop may work on other OS but not officialy supported by Ocean Container)
Access to the /dev/kvm device
A OCI container runtime : In this documentation we will use Docker but something like podman works too
Between 15-20Gb of storage, since the container is about 10Gb
Step by step¶
First you will need to download it from the Ocean website (This is not a docker registry)
# curl https://ocean.eupex.eu/download/container/ocean-latest.tar | docker load
Warning
Do not use docker import, as the image is a tarball
This will download the latest build of the Ocean container as ‘’ocean:latest’’ on your machine.
Then to run the container you can use :
# docker run --rm -it --device /dev/kvm --privileged ocean:latest
Options breakdowns :
–rm : Delete the container after the execution
-it : make the container interactive
–device : mount a device into the container
–privileged : give extended privileges to this container (Required by Mock which is used by Rift)
ocean:latest : the image we are launching
Additionals options :
-v : Mount a shared directory between the host and the container (-v <local path>:<container path>)
Create an Ocean Package¶
First, you need to declare yourself as Ocean staff :
Start by make sure you are in the Ocean directory of the container, in /root/ocean. Then, edit the file packages/staff.yaml and add your name :
John Doe:
email: john.doe@eupex.eu
You can then use Rift to check the syntax :
# rift -v check staff
If the syntax of the staff file is incorrect, Rift will return an error.
From a src.rpm¶
To import a src.rpm into Ocean, you can use rift import :
# rift import -t 'John Doe' -m 'System Tools' -o 'My project' -r 'Needed for production' my-package.src.rpm
Options breakdowns :
-t : The maintainer of the package
-m : The module of the packages, Ocean has modules to group packages by interest : Kernel, FS, Tools, Computing…
-o : Where did you get this package ?
-r : Why did you add this package in the project ? Please provide meaningful reason to ease to the maintenance process
Note
The module must be declared in packages/modules.yaml and the maintainer packages/staff.yaml
Rift will create a folder in packages named ‘’my-package’’, with all the content of the src.rpm (sources, spec).
From scratch¶
# rift create -t 'John Doe' -m 'System Tools' -o 'My project' -r 'Needed for production' my-package
Options breakdowns :
-t : The maintainer of the package
-m : The module of the packages, Ocean has modules to group packages by interest : Kernel, FS, Tools, Computing…
-o : Where did you get this package ?
-r : Why did you add this package in the project ? Please provide meaningful reason to ease to the maintenance process
Rift will be create a folder in packages named ‘’my-package’’, with all the content needed
You can refer to Fedora packaging guidelines as a reference to write a good specfile.
Build your package¶
Once you have imported your package into the Rift project, you can build it to the RPM format. You can configure Rift so that it will move your generated packages into a repository called the “Working repository”. To do that, you need to declare the Working Repository path in the Rift configuration. The file “project.conf” is tracked by git and should only contains settings relevant at the project scope. To add local configuration to Rift, you must put it in the “local.conf” file.
# mkdir /tmp/packages
In the /root/ocean/local.conf file :
working_repo: /tmp/packages
Then, you can build your package and publish it to the working repo :
# rift build --publish my-package
Once the package is built you can find it in the working repository
Validate your package¶
The validation is a way of ensuring your package is working and compatible with the rest of the Ocean packages. To validate your package, use the rift validate command :
# rift validate my-package
In short, the validate command will build your package with Mock, which ensure your package can be build in a clean chroot and then start a minual virtual machine. Then Rift will try to install the built package into this virtual machine, to make sure the package does not conflict with another one and so that all dependencies can be satisfied. If tests are written, they are executed, like checking if the service provided by the package is able to start, if a certain binary is not present in the package, …
Rift Annex¶
The binary source file of the packages are not stored within the git repository but in the Rift annex. The Rift annex work like a git lfs : its replace the binary file content with a checksum and move the actual file somewhere else (Network share, http server, …).
The Ocean annex is not accessible yet, so we provided the container with a snapshot of it. If you want the get the sources of a package, you can use the rift annex command :
# rift annex restore packages/krb5/sources/krb5-1.18.2.tar.gz
> packages/krb5/sources/krb5-1.18.2.tar.gz: fetched from annex
Troubleshooting¶
Rift verbose¶
You can set the Rift level of verbosity with the -vv flag.
Mock build logs¶
You can look at mock build log at /var/lib/mock/rift-ocean-container-<ocean git branch>/result/build.log to have detailed log about your previous build.
Mock caching¶
Because Mock keep a cache in /var/lib/mock and /var/cache/mock and it can interfere with the current build, especially if you switch branches of the Ocean project.
KVM¶
You must have read and write access to ‘’/dev/kvm’’ in order for the Rift VM to work