Merge pull request #82 from monstermunchkin/features/examples

Add examples

README.md

@@ -6,152 +6,10 @@ Type            | Service               | Status
 ---             | ---                   | ---
 CI              | Jenkins               | [![Build Status](https://travis-ci.org/lxc/distrobuilder.svg?branch=master)](https://travis-ci.org/lxc/distrobuilder)
 Project status  | CII Best Practices    | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1728/badge)](https://bestpractices.coreinfrastructure.org/projects/1728)
-## Example yaml file
 
-Save the following yaml as a file (for example `ubuntu.yaml`). To create
+## Example usage
-a simple `Ubuntu` rootfs in a folder called `ubuntu-rootfs` call
-`distrobuilder` as `distrobuilder build-dir ubuntu.yaml ubuntu-rootfs`.
 
-```yaml
+Save one of the [Ubuntu yaml snippets](./doc/examples/ubuntu.md) as
-image:
+`ubuntu.yaml`. To create a simple `Ubuntu` rootfs in a folder called
-  distribution: ubuntu # required
+`ubuntu-rootfs` call `distrobuilder` as `distrobuilder build-dir ubuntu.yaml
-  release: xenial # optional
+ubuntu-rootfs`.
-  variant: default # optional
-  description: Ubuntu Artful # optional
-  expiry: 30d # optional: defaults to 30d
-  architecture: x86_64 # optional: defaults to local architecture
-
-source:
-  downloader: debootstrap
-  url: http://us.archive.ubuntu.com/ubuntu
-  keys:
-    - 0x790BC7277767219C42C86F933B4FE6ACC0B21F3v
-  keyserver: pgp.mit.edu # optional
-
-  apt_source:: |-
-    deb {{ source.url }} {{ image.release }} main restricted universe multiverse
-    deb {{ source.url }} {{ image.release }}-updates main restricted universe multiverse
-    deb http://security.ubuntu.com/ubuntu {{ image.release }}-security main restricted universe multiverse
-
-targets:
-  lxc:
-    create-message: |-
-        You just created an {{ image.description }} container.
-
-        To enable SSH, run: apt install openssh-server
-        No default root or user password are set by LXC.
-
-    config:
-      - type: all
-        before: 5
-        content: |-
-          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.common.conf
-
-      - type: user
-        before: 5
-        content: |-
-          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.userns.conf
-
-      - type: all
-        after: 4
-        content: |-
-          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
-
-      - type: user
-        after: 4
-        content: |-
-          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
-
-      - type: all
-        content: |-
-          lxc.arch = x86_64
-
-files:
- - path: /etc/hostname
-   generator: hostname
-
- - path: /etc/hosts
-   generator: hosts
-
- - path: /etc/resolvconf/resolv.conf.d/original
-   generator: remove
-
- - path: /etc/resolvconf/resolv.conf.d/tail
-   generator: remove
-
- - path: /etc/machine-id
-   generator: remove
-
- - path: /etc/netplan/10-lxc.yaml
-   generator: dump
-   content: |-
-     network:
-       ethernets:
-         eth0: {dhcp4: true}
-     version: 2
-   releases:
-     - artful
-     - bionic
-
- - path: /etc/network/interfaces
-   generator: dump
-   content: |-
-     # This file describes the network interfaces available on your system
-     # and how to activate them. For more information, see interfaces(5).
-
-     # The loopback network interface
-     auto lo
-     iface lo inet loopback
-
-     auto eth0
-     iface eth0 inet dhcp
-   releases:
-     - trusty
-     - xenial
-
- - path: /etc/init/lxc-tty.conf
-   generator: upstart-tty
-   releases:
-    - precise
-    - trusty
-
-packages:
-    manager: apt
-
-    update: true
-    install:
-        - apt-transport-https
-        - language-pack-en
-        - openssh-client
-        - vim
-
-actions:
-    - trigger: post-update
-      action: |-
-        #!/bin/sh
-        set -eux
-
-        # Create the ubuntu user account
-        getent group sudo >/dev/null 2>&1 || groupadd --system sudo
-        useradd --create-home -s /bin/bash -G sudo -U ubuntu
-
-    - trigger: post-packages
-      action: |-
-        #!/bin/sh
-        set -eux
-
-        # Make sure the locale is built and functional
-        locale-gen en_US.UTF-8
-        update-locale LANG=en_US.UTF-8
-
-        # Cleanup underlying /run
-        mount -o bind / /mnt
-        rm -rf /mnt/run/*
-        umount /mnt
-
-        # Cleanup temporary shadow paths
-        rm /etc/*-
-
-mappings:
-  architecture_map: debian
-```

doc/examples/alpine.md

@@ -0,0 +1,60 @@
+# Alpine Linux
+
+```yaml
+image:
+  distribution: alpinelinux
+  release: 3.7.0
+  description: Alpine Linux
+  expiry: 30d
+  architecture: x86_64
+
+source:
+  downloader: alpinelinux-http
+  url: http://dl-cdn.alpinelinux.org/alpine/
+  keys:
+    - 0482D84022F52DF1C4E7CD43293ACD0907D9495A
+
+targets:
+  lxc:
+    create-message: |
+        You just created an Alpine container (release={{ image.release }}, arch={{ image.architecture }})
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/alpine.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/alpine.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+ - path: /etc/hostname
+   generator: hostname
+
+ - path: /etc/hosts
+   generator: hosts
+
+packages:
+    manager: apk
+
+    update: true
+    install:
+        - neovim
+```

doc/examples/archlinux.md

@@ -0,0 +1,62 @@
+# Arch Linux
+
+```yaml
+image:
+  distribution: archlinux
+  release: 2018.03.01
+  description: Arch Linux
+  expiry: 30d
+  architecture: x86_64
+
+source:
+  downloader: archlinux-http
+  url: https://archive.archlinux.org/iso
+  keys:
+    - 4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC
+
+targets:
+  lxc:
+    create-message: |
+      You just created an Arch Linux container (release={{ image.release }}, arch={{ image.architecture }})
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/archlinux.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/archlinux.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+  - name: hostname
+    path: /etc/hostname
+    generator: hostname
+
+  - name: hosts
+    path: /etc/hosts
+    generator: hosts
+
+packages:
+  manager: pacman
+
+  update: true
+  install:
+    - neovim
+```

doc/examples/centos.md

@@ -0,0 +1,95 @@
+# CentOS
+
+```yaml
+image:
+  distribution: centos
+  release: 7
+  variant: Minimal
+  description: CentOS {{ image.release }}
+  expiry: 30d
+  arch: x86_64
+
+source:
+  downloader: centos-http
+  url: http://centos.uib.no
+  keys:
+    - 24C6A8A7F4A80EB5
+  variant: Minimal
+
+targets:
+  lxc:
+    create-message: |
+        You just created a CentOS container (release={{ image.release }}, arch={{ image.architecture }})
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/centos.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/centos.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+ - name: hostname
+   path: /etc/hostname
+   generator: hostname
+
+ - name: hosts
+   path: /etc/hosts
+   generator: hosts
+
+packages:
+    manager: yum
+
+    update: true
+    install:
+        - vim
+
+actions:
+  - trigger: post-unpack
+    action: |-
+      #!/bin/sh
+      cd /mnt/cdrom/Packages
+      rpm -ivh --nodeps rpm-4.11.3-25.el7.x86_64.rpm
+      rpm -ivh --nodeps yum-3.4.3-154.el7.centos.noarch.rpm
+
+      # add cdrom repo
+      mkdir -p /etc/yum.repos.d
+      cat <<- EOF > /etc/yum.repos.d/cdrom.repo
+      [cdrom]
+      name=Install CD-ROM
+      baseurl=file:///mnt/cdrom
+      enabled=0
+      gpgcheck=1
+      gpgkey=file:///mnt/cdrom/RPM-GPG-KEY-CentOS-7
+      EOF
+
+      yum --disablerepo=\* --enablerepo=cdrom -y reinstall yum
+      yum --disablerepo=\* --enablerepo=cdrom -y groupinstall "Minimal Install"
+
+      rm -rf /mnt/cdrom /etc/yum.repos.d/cdrom.repo
+    releases:
+      - 7
+
+  - trigger: post-packages
+    action: |-
+      #!/bin/sh
+      rm -rf /var/cache/yum
+```

doc/examples/debian.md

@@ -0,0 +1,62 @@
+# Debian
+
+```yaml
+image:
+  distribution: debian
+  release: testing
+  description: Debian testing
+  expiry: 30d
+
+source:
+  downloader: debootstrap
+
+targets:
+  lxc:
+    create-message: |
+        You just created a Debian container (release={{ image.release }}, arch={{ image.architecture }}, variant={{ image.variant }})
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/debian.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/debian.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+ - name: hostname
+   path: /etc/hostname
+   generator: hostname
+
+ - name: hosts
+   path: /etc/hosts
+   generator: hosts
+
+packages:
+    manager: apt
+
+    update: true
+    install:
+        - systemd
+        - neovim
+
+mappings:
+  architecture_map: debian
+```

doc/examples/fedora.md

@@ -0,0 +1,59 @@
+# Fedora
+
+```yaml
+image:
+  distribution: fedora
+  release: 28
+  description: Fedora {{ image.release }}
+  expiry: 30d
+  arch: x86_64
+
+source:
+  downloader: fedora-http
+  url: https://kojipkgs.fedoraproject.org
+
+targets:
+  lxc:
+    create-message: |
+      You just created a Fedora container (release={{ image.release }}, arch={{ image.architecture }})
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/fedora.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/fedora.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+  - path: /etc/hostname
+    generator: hostname
+
+  - path: /etc/hosts
+    generator: hosts
+
+packages:
+  manager: dnf
+
+  update: true
+  install:
+    - systemd
+    - neovim
+```

doc/examples/ubuntu.md

@@ -0,0 +1,230 @@
+# Ubuntu
+## With debootstrap
+
+```yaml
+image:
+  distribution: ubuntu
+  release: artful
+  description: Ubuntu {{ image.release }}
+  architecture: amd64
+
+source:
+  downloader: debootstrap
+  url: http://us.archive.ubuntu.com/ubuntu
+  keys:
+    - 0x790BC7277767219C42C86F933B4FE6ACC0B21F32
+  keyserver: pgp.mit.edu
+
+  apt_sources: |-
+    deb {{ source.url }} {{ image.release }} main restricted universe multiverse
+    deb {{ source.url }} {{ image.release }}-updates main restricted universe multiverse
+    deb http://security.ubuntu.com/ubuntu {{ image.release }}-security main restricted universe multiverse
+
+targets:
+  lxc:
+    create-message: |
+      You just created an {{ image.description }} container.
+
+      To enable SSH, run: apt install openssh-server
+      No default root or user password are set by LXC.
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+ - path: /etc/hostname
+   generator: hostname
+
+ - path: /etc/hosts
+   generator: hosts
+
+ - path: /etc/init/lxc-tty.conf
+   generator: upstart-tty
+   releases:
+    - precise
+    - trusty
+
+files:
+ - path: /etc/hostname
+   generator: hostname
+
+ - path: /etc/hosts
+   generator: hosts
+
+ - path: /etc/resolvconf/resolv.conf.d/original
+   generator: remove
+
+ - path: /etc/resolvconf/resolv.conf.d/tail
+   generator: remove
+
+ - path: /etc/machine-id
+   generator: remove
+
+ - path: /etc/netplan/10-lxc.yaml
+   generator: dump
+   content: |-
+     network:
+       ethernets:
+         eth0: {dhcp4: true}
+     version: 2
+   releases:
+     - artful
+     - bionic
+
+ - path: /etc/network/interfaces
+   generator: dump
+   content: |-
+     # This file describes the network interfaces available on your system
+     # and how to activate them. For more information, see interfaces(5).
+
+     # The loopback network interface
+     auto lo
+     iface lo inet loopback
+
+     auto eth0
+     iface eth0 inet dhcp
+   releases:
+     - trusty
+     - xenial
+
+ - path: /etc/init/lxc-tty.conf
+   generator: upstart-tty
+   releases:
+    - precise
+    - trusty
+
+packages:
+    manager: apt
+
+    update: true
+    install:
+        - apt-transport-https
+        - language-pack-en
+        - openssh-client
+        - vim
+
+actions:
+    - trigger: post-update
+      action: |-
+        #!/bin/sh
+        set -eux
+
+        # Create the ubuntu user account
+        getent group sudo >/dev/null 2>&1 || groupadd --system sudo
+        useradd --create-home -s /bin/bash -G sudo -U ubuntu
+
+    - trigger: post-packages
+      action: |-
+        #!/bin/sh
+        set -eux
+
+        # Make sure the locale is built and functional
+        locale-gen en_US.UTF-8
+        update-locale LANG=en_US.UTF-8
+
+        # Cleanup underlying /run
+        mount -o bind / /mnt
+        rm -rf /mnt/run/*
+        umount /mnt
+
+        # Cleanup temporary shadow paths
+        rm /etc/*-
+
+mappings:
+  architecture_map: debian
+```
+
+## With Ubuntu base image
+
+```yaml
+image:
+  distribution: ubuntu
+  release: artful
+  variant: default
+  description: Ubuntu {{ image.release }}
+  expiry: 30d
+  arch: amd64
+
+source:
+  downloader: ubuntu-http
+  url: http://cdimage.ubuntu.com/ubuntu-base
+  keys:
+    - 0x46181433FBB75451
+    - 0xD94AA3F0EFE21092
+
+targets:
+  lxc:
+    create-message: |
+        You just created an Ubuntu container (release={{ image.release }}, arch={{ image.architecture }}, variant={{ image.variant }})
+
+    config:
+      - type: all
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.common.conf
+
+      - type: user
+        before: 5
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.userns.conf
+
+      - type: all
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/common.conf
+
+      - type: user
+        after: 4
+        content: |-
+          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
+
+      - type: all
+        content: |-
+          lxc.arch = {{ image.architecture_kernel }}
+
+files:
+ - path: /etc/hostname
+   generator: hostname
+
+ - path: /etc/hosts
+   generator: hosts
+
+ - path: /etc/init/lxc-tty.conf
+   generator: upstart-tty
+   releases:
+    - precise
+    - trusty
+
+packages:
+  manager: apt
+
+  update: true
+  install:
+    - systemd
+    - neovim
+
+mappings:
+  architecture_map: debian
+```