.. _ocean_container_tutorial:
===================
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)
.. code-block:: console
# 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 :
.. code-block:: console
# 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 :)
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 :
.. code-block::
John Doe:
email: john.doe@eupex.eu
You can then use Rift to check the syntax :
.. code-block:: console
# 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 :
.. code-block:: console
# 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
^^^^^^^^^^^^
.. code-block:: console
# 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.
.. code-block::
# mkdir /tmp/packages
In the /root/ocean/local.conf file :
.. code-block::
working_repo: /tmp/packages
Then, you can build your package and publish it to the working repo :
.. code-block::
# 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 :
.. code-block::
# rift validate my-package
.. uml::
@startuml
title Ocean package validation with Rift
User -> Rift : rift validate
Rift -> Rift : Check package metadata
Rift -> rpmlint : Ask for verification\n of package sources
rpmlint -> Rift : Send errors and\nwarnings
...
Rift -> Mock : Ask for package build
Mock -> Rift : Send built package
...
Rift -> Qemu : Start a virtual machine
Rift -> VM : Install Ocean\ndeveloppement version
Rift -> VM : Install built package
VM -> Rift: Send installation sucess
group Optional (If tests are written for this package)
Rift -> VM: Send the test\n(Shell script)
VM -> Rift: Send the result
end
Rift -> User: Send result of the\nvalidation and associated files (rpm)
@enduml
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 :
.. code-block:: console
# 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-/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
Useful external documentation
-----------------------------
* `Fedora packaging guidelines `_
* `Get started with containers (Docker) `_
.. raw:: latex
\clearpage