Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darwin-containers/rund

OCI Container Runtime for Darwin
https://github.com/darwin-containers/rund

Last synced: 2 months ago
JSON representation

OCI Container Runtime for Darwin

Awesome Lists containing this project

README 

        
= 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 <>.



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 <>.

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! ^_^"

----