docs: Consolidate mac tips & tricks in ./docs/mac.md

We had serveral files with instructions, in particular for
networking, for macOS/Docker for Mac. Let's have just one place.

Signed-off-by: Rolf Neugebauer <rolf.neugebauer@docker.com>

README.md

@@ -41,9 +41,11 @@ See `linuxkit run --help`.
 
 `make test` or `make test-hyperkit` will run the test suite
 
-There are also docs for booting on [Google Cloud](docs/gcp.md).
+Additional, platform specific information is available for:
+- [macOS](docs/mac.md)
+- [Google Cloud](docs/gcp.md)
 
-More detailed docs will be available shortly, for running both single hosts and clusters.
+We'll add more detailed docs for other platforms in the future.
 
 ## Building your own customised image
 

docs/mac.md

@@ -0,0 +1,55 @@
+# LinuxKit on a Mac
+
+We recommend using LinuxKit in conjunction with
+[Docker for Mac](https://docs.docker.com/docker-for-mac/install/). For
+the time being it's best to be on the latest edge release. `linuxkit
+run` uses [HyperKit](https://github.com/moby/hyperkit) and
+[VPNKit](https://github.com/moby/vpnkit) and the edge release ships
+with updated versions of both.
+
+## Networking
+
+By default, `linuxkit run` creates a VM with a single network
+interface which, logically, is attached to a L2 bridge, which also has
+the VM used by Docker for Mac attached to it. This means that the LinuxKit
+VMs can be accessed from containers running on Docker for Mac.
+
+The LinuxKit VMs have IP addresses on the `192.168.65.0/24` subnet
+assigned by a DHCP server part of VPNKit. `192.168.65.1` is reserved
+for VPNKit as the default gateway and `192.168.65.2` is used by the
+Docker for Mac VM.
+
+By default, LinuxKit VMs get incrementally increasing IP addresses, but you can assign a fixed IP address with `linuxkit run -ip`. It's best to choose an IP address from the DHCP address range above, but care must be taking to avoid clashes of IP address.
+
+### Accessing services
+
+The simplest way to access networking services exposed by a LinuxKit VM is to use a Docker for Mac container.
+
+For example, to access an ssh server in a LinuxKit VM, create a ssh client container from:
+```
+FROM alpine:edge
+RUN apk add --no-cache openssh-client
+```
+and then run
+```
+docker build -t ssh .
+docker run --rm -ti -v ~/.ssh:/root/.ssh  ssh ssh <IP address of VM>
+```
+
+
+### Forwarding ports to the host
+
+While VPNKit has the general tooling to expose any VMs port on the
+localhost (just like it does with containers in Docker for Mac), we
+are unlikely to expose this as a general feature in `linuxkit run` as
+it is very specific to the macOS. However, you can use a `socat` container to proxy between LinuxKit VMs ports and localhost.  For example, to expose the redis port from the [RedisOS example](../examples/redis-os.yml), use this Dockerfile:
+```
+FROM alpine:edge
+RUN apk add --no-cache socat
+ENTRYPOINT [ "/usr/bin/socat" ]
+```
+and then:
+```
+docker build -t socat .
+docker run --rm -t -d -p 6379:6379 socat tcp-listen:6379,reuseaddr,fork tcp:<IP address of VM>:6379
+```

examples/sshd.md

@@ -1,41 +0,0 @@
-# SSH example
-
-The LinuxKit [sshd example](./sshd.yml) defines an image running a SSH
-daemon. You can build it as usual (though you should add your public
-key to the `contents` field in the `files` section).
-
-On some platforms you can then just ssh into the system once it is running, but on some platforms additional steps are required.
-
-
-## HyperKit/Docker for Mac
-
-If you use the HyperKit backend with Docker for Mac, the VM created with `moby run ...` is placed on the same network as the Docker for Mac VM (via VPNKit). 
-The VMs network is not directly accessible from the host, but is accessible from within containers run with Docker for Mac.
-
-So, to ssh into the VM created via `moby run sshd` it's best to do this via a container from within a container.
-
-You can build a small container with an ssh client with this Dockerfile:
-```
-FROM alpine:edge
-RUN apk add --no-cache openssh-client
-```
-Then:
-```
-docker build -t ssh .
-```
-
-And now:
-```
-docker run --rm -ti -v ~/.ssh:/root/.ssh  ssh ssh <IP address of VM>
-```
-
-The HyperKit backend for `moby run` also allows you to set the IP address of the VM, like:
-```
-moby run -ip 192.168.65.101 sshd
-```
-
-
-## Qemu/Linux
-
-TBD
-

projects/demo/dockerfiles/Dockerfile.socat

@@ -1,8 +0,0 @@
-# A dockerfile to build a socat container
-#
-# It sets the environment to talk to the local cluster
-FROM alpine:edge
-
-RUN apk add --no-cache socat
-
-ENTRYPOINT [ "/usr/bin/socat" ]