rund

= rund
:project-handle: rund
:uri-project: https://github.com/darwin-containers/{project-handle}
:uri-ci: {uri-project}/actions?query=branch%3Amain
:source-highlighter: rouge

image:{uri-project}/workflows/CI/badge.svg?branch=main[GitHub Actions,link={uri-ci}]

rund is an experimental https://containerd.io[containerd] shim for running *Darwin* containers on Darwin.

rund doesn't offer the usual level of container isolation that is achievable on other OSes due to limited Darwin kernel API.

What rund provides:

* Filesystem isolation via https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/chroot.2.html[`chroot(2)`]
* Cleanup of container processes using process group
* OCI Runtime Specification compatibility (to the extent it is possible on Darwin)
* Host-network mode only
* bind mounts

You can https://www.youtube.com/watch?v=RS9C_4O_Ohg[view a video review of Darwin containers] and also https://earthly.dev/blog/macos-native-containers/[read an article].
Both were created by https://earthly.dev[Earthly].

== Installation and usage

See https://github.com/darwin-containers/homebrew-formula#readme[homebrew-formula] repository for end-user instructions.

== Development

This section describes development setup for hacking on rund code.

=== Prerequisites

* Disable https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection[System Integrity Protection].
SIP https://github.com/containerd/containerd/discussions/5525#discussioncomment-2685649[doesn't allow] to `chroot`.
* Install https://osxfuse.github.io[macFUSE] or https://www.fuse-t.org[fuse-t]
* Install https://bindfs.org/downloads/[bindfs] using https://github.com/mpartel/bindfs/issues/100#issuecomment-870699085[build instructions]

[[containerd]]
=== Usage with containerd

Prerequisite: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry[authenticate to GitHub Package Registry].

Then, run in Terminal:

[source,shell]
----
# Download rund
git clone https://github.com/darwin-containers/rund
cd rund
# Build rund
go build -o bin/ cmd/*.go
cd ..

# Download containerd
git clone https://github.com/darwin-containers/containerd
cd containerd
# Run containerd
sudo go run cmd/containerd/main.go

# Continue from a SEPARATE terminal, without stopping containerd

# Download base image
cd containerd
sudo go run cmd/ctr/main.go image pull ghcr.io/darwin-containers/darwin-jail/ventura:latest

# Aaaand... Run your first Darwin container!

# On Apple Silicon
sudo go run cmd/ctr/main.go run --rm -t --runtime "$(pwd)/../rund/bin/containerd-shim-rund-v1" ghcr.io/darwin-containers/darwin-jail/ventura-arm64:latest my_container /bin/sh -c 'echo "Hello from Darwin container ^_^"'

# On Intel
sudo go run cmd/ctr/main.go run --rm -t --runtime "$(pwd)/../rund/bin/containerd-shim-rund-v1" ghcr.io/darwin-containers/darwin-jail/ventura-i386:latest my_container /bin/sh -c 'echo "Hello from Darwin container ^_^"'
----

If you want to build image from scratch, see https://github.com/darwin-containers/darwin-jail[darwin-jail] project.

=== Usage with BuildKit

Perform all the steps from <<containerd>>.

Create `/etc/buildkit/buildkitd.toml` with the following contents:

[source,toml]
----
[worker.containerd]
runtime = "/path/to/rund/bin/containerd-shim-rund-v1"
----

Then, from terminal:

[source,shell]
----
# Download BuildKit
git clone https://github.com/darwin-containers/buildkit

# Run BuildKit daemon
cd buildkit
sudo go run ./cmd/buildkitd

# Continue from a SEPARATE terminal, without stopping neither containerd nor buildkitd

# Create Dockerfile
cat << EOF > Dockerfile
FROM ghcr.io/darwin-containers/darwin-jail/ventura:latest
RUN echo "Hello, World!"
EOF

# Aaaaad, build your first Darwin image
sudo go run ./cmd/buildctl build --frontend=dockerfile.v0 --local context=. -local dockerfile=.
----

=== Usage with Docker

Perform all the steps from <<containerd>>.
You don't need BuildKit daemon to use Docker on Darwin.

Create `/etc/docker/daemon.json` with the following contents:

[source,json]
----
{
  "data-root": "/private/d/",
  "default-runtime": "/path/to/rund/bin/containerd-shim-rund-v1",
  "runtimes": {
    "/path/to/rund/bin/containerd-shim-rund-v1": {
      "runtimeType": "/path/to/rund/bin/containerd-shim-rund-v1"
    }
  }
}
----

Then, from terminal:

[source,shell]
----
# Download Docker
git clone https://github.com/darwin-containers/moby

# Run Docker daemon
cd moby
cp vendor.mod go.mod
cp vendor.sum go.sum
sudo go run ./cmd/dockerd

# Continue from a SEPARATE terminal, without stopping neither containerd nor dockerd

# Install Docker cli
brew install docker

# Aaaand, run your first Darwin native container
sudo docker run --rm -it ghcr.io/darwin-containers/darwin-jail/ventura:latest echo "Hello from Darwin! ^_^"
----