|
|
| Line 1: |
Line 1: |
| = Developing and Building Modules =
| | {{admon/important|This page is deprecated| All Fedora Modularity Documentation has moved to the new [https://docs.pagure.org/modularity/ Fedora Modularity Documentation website] with source hosted along side the code in the [https://pagure.io/modularity Fedora Modularity website git repository]}} |
| | |
| This document describes the process of developing and building modules for the Fedora Modularity project using the [https://pagure.io/fm-orchestrator '''Module Build Service'''] running on your laptop. I will use my [https://github.com/asamalik/fake-proftpd-module-image '''proftpd module'''] as an example. | |
| | |
| We'll start with writing a [https://pagure.io/modulemd '''modulemd'''] file describing the module and its components, and finish by building one or more containers out of our module.
| |
| | |
| == Architecture ==
| |
| The final result of this guide is a container using a three-layer module container architecture which clearly separates the system base image (built out of a Base Runtime), the module itself (the one we are going to build), and the final configuration.
| |
| | |
| Examples for each layer: [https://github.com/asamalik/fake-gen-core-module-image '''Layer 1'''] | [https://github.com/asamalik/fake-proftpd-module-image '''Layer 2'''] | [https://github.com/container-images/proftpd '''Layer 3''']
| |
| | |
| [[File:three-layer-arch.png|800px]]
| |
| | |
| == Building ==
| |
| The following guide is rather comprehensive than descriptive. It is driven by examples linked from this document, but hosted elsewhere. These examples should be easy enough to help you with building your own modular container.
| |
| | |
| === Setting up the environment ===
| |
| | |
| The easiest way is to use my [https://github.com/asamalik/build-module '''Module Builder'''].
| |
| | |
| The only two things you need are:
| |
| # Docker running on your system
| |
| # The "[https://github.com/asamalik/build-module/blob/master/build_module '''build_module''']" script from the [https://github.com/asamalik/build-module '''Module Builder'''] repository.
| |
| | |
| === Developing and building the module ===
| |
| | |
| The first thing you need to do is to write a modulemd file describing your module. Your module needs to include all RPM dependencies for the thing you are modularizing - except those which are provided by the Base Runtime. Please see the list of Base Runtime binary packages.
| |
| | |
| An [https://github.com/asamalik/fake-proftpd-module-image/blob/master/proftpd.yaml '''example modulemd for my proftpd module'''] can help you with writing your own modulemd file.
| |
| | |
| ==== How to get the list of all the dependencies? ====
| |
| | |
| Well, nowadays, you can cheat and run a repoquery (command below) on the packages you want to use (proftpd in my case) in Fedora 25 and get the list of your dependencies this way. Then you just leave out all the packages which are already [https://github.com/asamalik/fake-gen-core-module-image/blob/master/packages/gen-core-binary-pkgs.txt '''provided by the Base Runtime'''].
| |
| | |
| Getting recursive dependencies of your package:
| |
| $ repoquery --requires --recursive --resolve PACKAGE_NAME
| |
| | |
| Again, an example can help you understand:
| |
| * [https://github.com/asamalik/fake-proftpd-module-image/blob/master/packages/gen-core-binary-pkgs.txt '''All Base Runtime packages''']
| |
| * [https://github.com/asamalik/fake-proftpd-module-image/blob/master/packages/proftpd-recursive-dependency-binary-pkgs.txt '''All proftpd dependencies''']
| |
| * [https://github.com/asamalik/fake-proftpd-module-image/blob/master/packages/diff.txt '''Proftpd dependencies not provided by the Base Runtime''']
| |
| | |
| However, in the modular world, there will be no place you can run repoquery against. So the Modularity team needs to come up with a tooling that makes this process as easy as possible.
| |
| | |
| ==== Building the module ====
| |
| When you think you have your modulemd ready, you need to place it in a local git repository. The names of both the repository and the modulemd must match the module name.
| |
| | |
| Example: If your module is called proftpd, the repo directory will also be named proftpd and the modulemd file proftpd.yaml.
| |
| | |
| Then you simply build it using the [https://github.com/asamalik/build-module/blob/master/build_module '''build_module'''] script:
| |
| | |
| <code>$ ./build_module /module/git/repo /results/directory</code>
| |
| | |
| The result will be an RPM repository containing all the packages from your module.
| |
| | |
| === Containers ===
| |
| | |
| When you have your module built, let's put it in a container, so we can use it.
| |
| | |
| ==== Building Layer 2 ====
| |
| | |
| First, upload your RPM repository from the previous step somewhere publicly accessible. I've used my [https://asamalik.fedorapeople.org/proftpd-module-repo/ '''Fedorapeople to host my modular packages'''].
| |
| | |
| Next step will be writing a Dockerfile to build a container image with your module. This container will be representing the Layer 2 in the three-layer architecture.
| |
| | |
| Since there is no official Base Runtime image, I have created [https://github.com/asamalik/fake-gen-core-module-image '''my own Fake Base Runtime'''] that you can use as your base image by specifying "<code>FROM asamalik/fake-gen-core-module</code>".
| |
| | |
| You also need to write a repo file for your module - see the example below - and add it to your container, so you can install the module in it.
| |
| | |
| Basically, you need to prepare a repository similar to this example:
| |
| * [https://github.com/asamalik/fake-proftpd-module-image '''The whole Layer 2 repository''']
| |
| ** [https://github.com/asamalik/fake-proftpd-module-image/blob/master/Dockerfile '''Dockerfile''']
| |
| ** [https://github.com/asamalik/fake-proftpd-module-image/blob/master/files/proftpd-module.repo '''repo file''']
| |
| | |
| When you have your Layer 2 repository ready, use "<code>docker build .</code>" to build the container image and "<code>docker tag username/imagename</code>" so you (and maybe other people) can use it as a base for the final layer.
| |
| | |
| ==== Building Layer 3 ====
| |
| The final layer will not install anything, it will just add configuration and the RUN statement to make the image work. You need to use your Layer 2 image as a base for this one.
| |
| | |
| An [https://github.com/container-images/proftpd '''example for the proftpd container'''].
| |
| | |
| And again, when you have your Dockerfile ready, use "<code>docker build .</code>" to build the container image.
| |
