Guide for new users

[sullivan50909]

Is there a guide for new users? I'm specifically looking for install instructions and a basic example. I'm trying to use the Install section of the readme, but it has a number of issues.

1. What OS's are supported? (be specific, not just Linux)
2. Can I install without brew? How?
3. What gets installed with Brew? What do I need to install manually?
4. How do I install CNI plugins (if they are not included in brew install nerdctl)
5. Mention that you must start your terminal as a user, not as root then su to user
6. How do I create the default bridge CNI network?

[yuchanns]

nerdctl is shipped with lima to support MacOS. https://github.com/lima-vm/lima
As for Linux, you can find instructions in each release detail. https://github.com/containerd/nerdctl/releases

[sullivan50909]

I feel like I'm missing a link somewhere. The only instructions I see on the Releases page are to extract the archive using
tar Cxzvvf /usr/local nerdctl-full-2.0.0-beta.0-linux-amd64.tar.gz
Is that all that is required?
When I tried installing with brew, a bunch of other stuff got installed. Are any additional packages needed if I just extract the tar?

[AkihiroSuda]

That single tar should be enough.

Rootless users may need this too

# for apt-get
sudo apt-get install -y dbus-user-session  uidmap

# for dnf
sudo dnf install -y dbus-daemon shadow-utils

See https://rootlesscontaine.rs/getting-started/common/

[sullivan50909]

I am running Rocky Linux 9.3 in a brand new VM with no special settings. I am trying to use nerdctl to run rootless containers. Stopping firewalld allowed me to get things running
sudo systemctl stop firewalld
This isn't a real solution, but it is a hint to the root cause of my most recent install problem.

[AkihiroSuda]

This seems to fix the issue

--- /home/suda.linux/.config/cni/net.d/nerdctl-bridge.conflist.bak	2024-02-14 17:27:37.281279702 +0900
+++ /home/suda.linux/.config/cni/net.d/nerdctl-bridge.conflist	2024-02-14 17:30:16.410469639 +0900
@@ -37,7 +37,8 @@
     },
     {
       "type": "firewall",
-      "ingressPolicy": "same-bridge"
+      "ingressPolicy": "same-bridge",
+      "backend": "iptables"
     },
     {
       "type": "tuning"

Originally posted by @AkihiroSuda in #2818 (comment)

Proper fix:

• [cherry-picked to v1.7.4] rootless: fix Not Authorized(uid): org.fedoraproject.FirewallD1.config #2819

[AkihiroSuda]

Is there a guide for new users? I'm specifically looking for install instructions and a basic example. I'm trying to use the Install section of the readme, but it has a number of issues.

Feel free to submit PRs to improve the docs.

1. What OS's are supported? (be specific, not just Linux)

Best tested (tested in nerdctl CI):

• Ubuntu 22.04 (recommended)
• Ubuntu 20.04

Well tested (tested in Lima CI: https://github.com/lima-vm/lima/blob/master/examples/README.md):

• Ubuntu 23.10
• Alpine Linux 3.19
• ArchLinux
• Debian GNU/Linux 12
• Fedora 39
• openSUSE Leap 15.5

Occasionally tested:

• AlmaLinux, Rocky Linux, Oracle Linux, CentOS Stream 9
• AlmaLinux, Rocky Linux, Oracle Linux, CentOS Stream 8
• Debian GNU/Linux 11

Experimental:

• Windows
• FreeBSD

2. Can I install without brew? How?

Yes. Actually, brew isn't recommended for nerdctl as it doesn't work with the macOS version of brew.

The recommended step is to download nerdctl-full-<VERSION>-linux-amd64.tar.gz from https://github.com/containerd/nerdctl/releases/ ,
and extract it under /usr/local:

sudo tar Cxzvvf /usr/local nerdctl-full-<VERSION>-linux-amd64.tar.gz

And then start containerd:

Rootful

sudo systemctl enable --now containerd
sudo nerdctl run -d --name nginx -p 80:80 nginx:alpine

Rootless

containerd-rootless-setuptool.sh install
nerdctl run -d --name nginx -p 8080:80 nginx:alpine

3. What gets installed with Brew? What do I need to install manually?

brew install nerdctl (does not work on macOS) only installs nerdctl.

Aside from nerdctl, you need to install containerd and CNI plugins at least.

• https://github.com/containerd/containerd/releases
• https://github.com/containernetworking/plugins/releases

brew users may also use brew install lima (works on macOS too) to create a Linux virtual machine
with a complete distribution of nerdctl bundled in.

brew install lima
lima nerdctl run hello-world

4. How do I install CNI plugins (if they are not included in brew install nerdctl)

Download from https://github.com/containernetworking/plugins/releases and extract it under /usr/local/libexec/cni.

5. Mention that you must start your terminal as a user, not as root then su to user

This is implied in:

nerdctl/docs/rootless.md

Line 3 in 0181cb0

See https://rootlesscontaine.rs/getting-started/common/ for the prerequisites.

Feel free to submit a PR to improve readability of this.

6. How do I create the default bridge CNI network?

Automatically created.