FreeBSD: add initial poudriere.md

Fri, 25 Aug 2017 15:36:59 +0200

author
David Demelier <markand@malikania.fr>
date
Fri, 25 Aug 2017 15:36:59 +0200
changeset 0
18c8c5dd363b
child 1
bbf887728d76

FreeBSD: add initial poudriere.md

FreeBSD/poudriere.md file | annotate | diff | comparison | revisions
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FreeBSD/poudriere.md	Fri Aug 25 15:36:59 2017 +0200
@@ -0,0 +1,183 @@
+FreeBSD poudriere howto
+=======================
+
+What is poudriere?
+------------------
+
+In short, poudriere is a tool for building packages into clean jails to make
+predictible and secure installation/upgrades.
+
+Installation
+------------
+
+### From packages
+
+    pkg install poudriere
+    pkg isntall dialog4ports
+
+### From ports
+
+    make -C /usr/ports/ports-mgmt/poudriere install clean
+    make -C /usr/ports/ports-mgmt/dialog4ports install clean
+
+Initial configuration
+---------------------
+
+This guide assumes that you use ZFS.
+
+### poudriere.conf
+
+The /usr/local/etc/poudriere.conf file does not require much information, the
+following options are required:
+
+    ZPOOL=zroot
+    ZROOTFS=/poudriere  
+    BASEFS=/poudriere
+    POUDRIERE_DATA=${BASEFS}/data
+    DISTFILES_CACHE=/poudriere/distfiles
+    RESOLV_CONF=/etc/resolv.conf
+
+Options:
+  - **ZPOOL**: your zfs pool name,
+  - **ZROOTFS**: zfs dataset to use,
+  - **BASEFS**: base directory for jails and ports,
+  - **POUDRIERE**: directory for packages, logs and such,
+  - **DISTFILES_CACHE**: directory where to store distfiles,
+  - **RESOLV_CONF**: file for DNS resolver.
+
+This means that:
+
+  - any jail created by poudriere will be stored in /poudriere/jails,
+  - result of builds will be kept in dedicated /poudriere/data directories.
+
+Create the zfs datasets for poudriere:
+
+    zfs create zroot/poudriere
+    zfs create zroot/poudriere/distfiles
+
+Jail creation
+-------------
+
+Before building package, you need to create a jail. The easiest way is to use
+the FTP method (default) which simply fetch release tarballs and extract them.
+
+Let's create a poudriere jail named **FreeBSD-11-1**.
+
+### Using FTP
+
+    poudriere jail -c -j FreeBSD-11-1 -v 11.1-RELEASE
+
+Ports fetching
+--------------
+
+You also need to have a ports tree to build ports from, you have several way to
+fetch them such as svn, portsnap and git. The default is portsnap and available
+directly from FreeBSD so use it.
+
+Let's create a default poudriere ports tree.
+
+    poudriere ports -c
+
+Building options
+----------------
+
+What's really interesting in building ports is to customize every options of
+them.
+
+For example, on a server you don't want to have desktop software and all of
+useless things like X.Org, dbus, avahi, pulseaudio and such.
+
+Poudriere uses different files for customizing options in the following order:
+
+  - /usr/local/etc/poudriere.d/make.conf
+  - /usr/local/etc/poudriere.d/<setname>-make.conf
+  - /usr/local/etc/poudriere.d/<tree>-make.conf
+  - /usr/local/etc/poudriere.d/<jailname>-make.conf
+  - /usr/local/etc/poudriere.d/<jailname>-<tree>-make.conf
+  - /usr/local/etc/poudriere.d/<jailname>-<setname>-make.conf
+  - /usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-make.conf
+
+For example, in our case we can basically customize our options by creating the
+file **/usr/local/etc/poudriere.d/freebsd-11-1-make.conf**.
+
+### Disabling desktop options
+
+On a server, we may disable the following options using the `OPTIONS_UNSET`
+variable.
+
+Note: we use the `+=` assignment to avoid resetting it.
+
+    # /usr/local/etc/poudriere.d/freebsd-11-1-make.conf
+    OPTIONS_UNSET+= DBUS NLS X11
+
+Configuring per-port options
+----------------------------
+
+It's also possible to edit port options in individual manner, for that purpose,
+we use the `poudriere options` command.
+
+Let's configure vim to remove options we don't care:
+
+    poudriere options -j FreeBSD-11-1 -c editors/vim
+
+If you defined the **OPTIONS_UNSET** described above, the **NLS** option should
+be disabled by default, now select **CONSOLE** as User interface option.
+
+Note: it's recommended to use `-c` option because it forces the edition of
+options.
+
+Building ports
+--------------
+
+Now that we have prepared our poudriere environment, let's build a port using
+the `poudriere bulk` command.
+
+    poudriere bulk -j FreeBSD-11-1 editors/vim
+
+Since we will probably build a high number of ports, we can use a file instead
+using the `-f` option.
+
+    # /etc/packages.conf
+    editors/vim
+    shells/zsh
+
+    poudriere bulk -j FreeBSD-11-1 -f /etc/packages.conf
+
+Using your repository
+---------------------
+
+Once you have built some packages, you may use it directly from `pkg` command
+because poudriere build a custom repository.
+
+In our case, the package repository is located into
+**/poudriere/data/packages/FreeBSD-11-1-default**
+
+### Disable FreeBSD official repository
+
+If you want to completely disable the official FreeBSD repository, create the
+following file:
+
+    # /etc/pkg/no-FreeBSD.conf
+    FreeBSD: {
+      enabled: no
+    }
+
+### Enable our own package repository
+
+Create the following file:
+
+    # /etc/pkg/local.conf
+    local: {
+      url: "/poudriere/data/packages/FreeBSD-11-1-default"
+    }
+
+Note: the **local** name can be replaced with anything.
+
+Update pkg repository and upgrade:
+
+    pkg update -f
+    pkg upgrade
+
+Then install our own packages:
+
+    pkg install vim zsh

mercurial