Quick-Start

Two quick-starts are provided, one for end-users, the other one for developers.

As an end user who wish to use PouchContainer, please read End User Quick-Start to install and explore PouchContainer.

As a developer who wish to hack on PouchContainer, please read Developer Quick-Start to start hacking and get involved in the project!

End User Quick-Start

You can install PouchContainer automatically on your machine with very few steps. Currently we support the following Linux Distributions: Alibaba Cloud Linux 2, Ubuntu and CentOS.

Alibaba Cloud Linux 2

1. Install PouchContainer

There is an official PouchContainer build in Alibaba Cloud Linux 2 (a.k.a. Aliyun Linux 2) Yum repo, you should be able to install it via Yum tool without adding any extra repo files explicitly. Note that Alibaba Cloud Linux 1 (Aliyun Linux 17.01) is not supported for now.

If you are an Alibaba Cloud Linux 2 user, simply run the following command to install the latest version of PouchContainer:

sudo yum install -y pouch

2. Start PouchContainer

sudo systemctl start pouch

Afterwards, you can pull an image and run PouchContainer containers.

Ubuntu

To install PouchContainer, you need a maintained version of Ubuntu 16.04 (Xenial LTS). Archived versions aren't supported or tested.

PouchContainer is conflict with Docker, so you must uninstall Docker before installing PouchContainer.

Prerequisites

PouchContainer supports LXCFS to provide strong isolation, so you should install LXCFS firstly. By default, LXCFS is enabled.

sudo apt-get install lxcfs

Install packages to allow 'apt' to use a repository over HTTPS:

sudo apt-get install curl apt-transport-https ca-certificates software-properties-common

1. Add PouchContainer's official GPG key

curl -fsSL https://mirrors.aliyun.com/opsx/pouch/linux/debian.orig/opsx@service.alibaba.com.gpg.key | sudo apt-key add -

Verify that you now have the key with the fingerprint F443 EDD0 4A58 7E8B F645 9C40 CF68 F84A BE2F 475F, by searching for the last 8 characters of the fingerprint.

$ apt-key fingerprint BE2F475F
pub   4096R/BE2F475F 2018-02-28
      Key fingerprint = F443 EDD0 4A58 7E8B F645  9C40 CF68 F84A BE2F 475F
uid                  opsx-admin <opsx@service.alibaba.com>

2. Set up the PouchContainer repository

Before you install PouchContainer for the first time on a new host machine, you need to set up the PouchContainer repository. We enabled stable repository by default, you always need the stable repository. To add the test repository, add the word test after the word stable in the command line below. Afterward, you can install and update PouchContainer from the repository.

sudo add-apt-repository "deb https://mirrors.aliyun.com/opsx/pouch/linux/debian.orig/ pouch stable"

3. Install PouchContainer

Install the latest version of PouchContainer.

# update the apt package index
sudo apt-get update
sudo apt-get install pouch

After installing PouchContainer, the pouch group is created, but no users are added to the group.

4. Start PouchContainer

sudo service pouch start

Afterwards, you can pull an image and run PouchContainer containers.

CentOS

To install PouchContainer, you need a maintained version of CentOS 7. Archived versions aren't supported or tested.

We have put rpm package to Aliyun mirrors, you can install PouchContainer using PouchContainer repository. If you install PouchContainer for the first on a new host machine, you need to set up the PouchContainer repository. Then, you can install and update PouchContainer from repository.

1.Install yum-utils

Install required packages. yum-utils provides the yum-config-manager utility.

sudo yum install -y yum-utils

2. Set up the PouchContainer repository

Use the following command to add PouchContainer repository.

sudo yum-config-manager --add-repo https://mirrors.aliyun.com/opsx/opsx-centos7.repo
sudo yum update

Note: The above command set up the stable repository, you can enable test repository by the following command.

sudo yum-config-manager --enable pouch-test

You can disable the test repository by running the yum-config-manager command with the --disable flag. To re-enable it, use the --enable flag. The following command disables the test repository.

sudo yum-config-manager --disable pouch-test

3. Install PouchContainer

Run the following command to install the latest version of PouchContainer. If it's the first time to install PouchContainer on your host, you will be prompted to accept the GPG key, and the key's fingerprint will be shown.

sudo yum install pouch

After installing PouchContainer, the pouch group is created, but no users are added to the group.

4. Start PouchContainer

sudo systemctl start pouch

Afterwards, you can pull an image and run PouchContainer containers.

Run pouch command with non-root users

To enable users other than root can run pouch command directly without sudo, pouchd creates a unix socket owned by pouch group. Users just need to have pouch group on the machine and add user to pouch group.

1. create the pouch group

If you want the unix socket to be owned by pouch group, make sure it exists or you need to create it.

sudo groupadd pouch

2. start pouchd

sudo service pouch restart

3. add user to group

Add user who wants to have access to the pouch group.

sudo gpasswd -a $USER pouch

Remind that you should relogin to make /etc/group take effect, check it by typing groups to see if your shell gets pouch group.

Run pouch command with auto-completion

Pouch provides a bash completion file locate at contrib/completion/bash/pouch, place this file under /usr/share/bash-completion/completions. Source it to make it take effect, then you can enjoy pouch/pouchd commands completion.

cp contrib/completion/bash/pouch /usr/share/bash-completion/completions
source /usr/share/bash-completion/completions/pouch

Uninstall pouch

On Ubuntu

sudo apt-get purge pouch

On CentOS

sudo yum remove pouch

After running the remove command, images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers and volumes, execute the following command:

sudo rm -rf /var/lib/pouch

Developer Quick-Start

This guide provides step by step instructions to deploy PouchContainer on bare metal servers or virtual machines. As a developer, you may need to build and test PouchContainer binaries via source code. To build pouchd which is so-called "PouchContainer Daemon" and pouch which is so-called "PouchContainer CLI", the following build system dependencies are required:

• Linux Kernel 3.10+
• Go 1.10.4+
• containerd: 1.0.3
• runc: 1.0.0-rc4
• runv: 1.0.0 (option)

NOTE: The PouchContainer is using overlayfs, which requires kernel to support multiple lowerdirs. On 4.x kernels, they always support multiple lowerdirs overlayfs. And RHEL and Centos 3.x kernels (> 3.10.0-693.el7.x86_64) also support it. Besides this, it needs filesystem to support d_type. If the backing filesystem is xfs, please reformat with ftype=1 to enable d_type support.

Prerequisites Installation

Since pouchd is a kind of container engine, and pouch is a CLI tool, if you hope to experience container management ability via pouch, there are several additional binaries needed:

• containerd: an industry-standard container runtime;
• runc: a CLI tool for spawning and running containers according to the OCI specification;
• runv: a hypervisor-based runtime for OCI.

Here are the shell scripts to install containerd and runc:

# install containerd
$ wget https://github.com/containerd/containerd/releases/download/v1.0.3/containerd-1.0.3.linux-amd64.tar.gz
$ tar -xzvf containerd-1.0.3.linux-amd64.tar.gz -C /usr/local
$
# install runc
$ wget https://github.com/opencontainers/runc/releases/download/v1.0.0-rc4/runc.amd64 -P /usr/local/bin
$ chmod +x /usr/local/bin/runc.amd64
$ mv /usr/local/bin/runc.amd64 /usr/local/bin/runc

runV Installation

If you wish to experience hypervisor-based virtualization additionally, you will still need to install runV.

More guide on experiencing PouchContainer with runV including runv Installation, please refer to PouchContainer run with runv guide.

PouchContainer Build and Installation

With all prerequisites installed, you can build and install PouchContainer Daemon and PouchContainer CLI. Clone the repository and checkout whichever branch you like (in the following example, checkout branch master):

mkdir -p $GOPATH/src/github.com/alibaba/
cd $GOPATH/src/github.com/alibaba/; git clone https://github.com/alibaba/pouch.git
cd pouch; git checkout master

Makefile target named build will compile the pouch and pouchd binaries into current bin directory. You can execute make build && make install to build binaries and install them in destination directory (/usr/local/bin by default).

make build && make install

Build Tags

Pouch not use build tags by default, if you want pouchd to support additional security options, build pouchd with tags like

make BUILDTAGS='seccomp apparmor selinux'

Supported build Tags

Start PouchContainer

With all needed binaries installed, you could start pouchd via:

$ pouchd
INFO[0000] starting containerd                           module=containerd revision=773c489c9c1b21a6d78b5c538cd395416ec50f88 version=v1.0.3
INFO[0000] setting subreaper...                          module=containerd
INFO[0000] loading plugin "io.containerd.content.v1.content"...  module=containerd type=io.containerd.content.v1
INFO[0000] loading plugin "io.containerd.snapshotter.v1.btrfs"...  module=containerd type=io.containerd.snapshotter.v1
WARN[0000] failed to load plugin io.containerd.snapshotter.v1.btrfs  error="path /var/lib/containerd/io.containerd.snapshotter.v1.btrfs must be a btrfs filesystem to be used with the btrfs snapshotter" module=containerd
INFO[0000] loading plugin "io.containerd.snapshotter.v1.overlayfs"...  module=containerd type=io.containerd.snapshotter.v1
INFO[0000] loading plugin "io.containerd.metadata.v1.bolt"...  module=containerd type=io.containerd.metadata.v1
WARN[0000] could not use snapshotter btrfs in metadata plugin  error="path /var/lib/containerd/io.containerd.snapshotter.v1.btrfs must be a btrfs filesystem to be used with the btrfs snapshotter" module="containerd/io.containerd.metadata.v1.bolt"
INFO[0000] loading plugin "io.containerd.differ.v1.walking"...  module=containerd type=io.containerd.differ.v1
INFO[0000] loading plugin "io.containerd.grpc.v1.containers"...  module=containerd type=io.containerd.grpc.v1

After pouchd's running, you could interact with pouchd by PouchContainer CLI:

$ pouch images
IMAGE ID             IMAGE NAME                                               SIZE
3e8fa85ddfef         docker.io/library/busybox:latest                         2699
504cf109b492         docker.io/library/redis:alpine                           2035

Feedback

We hope this guide would help you get up and run with PouchContainer. And feel free to send feedback via ISSUE, if you have any questions. If you wish to contribute to PouchContainer on this guide, please just submit a pull request.