Hello, world!
% ls -l ~/Desktop/assets total 8 -rw-r--r--@ 1 fido staff 2410 May 13 18:36 link.svg @@ -42,18 +42,18 @@ total 8 total 4 -rw-r--r-- 1 root root 2410 May 14 01:36 link.svg % -``` +The argument to `--volume` in the example consists of the full pathname for the host folder and the full pathname for the mount point in the container, separated by a colon. The `--mount` option uses a comma-separated `key=value` syntax to achieve the same result: -```shellsession +
% container run --mount source=${HOME}/Desktop/assets,target=/content/assets docker.io/python:slim ls -l /content/assets
total 4
-rw-r--r-- 1 root root 2410 May 14 01:36 link.svg
%
-```
+
## Build and run a multiplatform image
@@ -67,18 +67,19 @@ container build --arch arm64 --arch amd64 --tag registry.example.com/fido/web-te
Try running the command `uname -a` with the `arm64` variant of the image to see the system information that the virtual machine reports:
-```shellsession
+% container run --arch arm64 --rm registry.example.com/fido/web-test:latest uname -a Linux 7932ce5f-ec10-4fbe-a2dc-f29129a86b64 6.1.68 #1 SMP Mon Mar 31 18:27:51 UTC 2025 aarch64 GNU/Linux % -``` +When you run the command with the `amd64` architecture, the x86-64 version of `uname` runs under Rosetta translation, so that you will see information for an x86-64 system: -```shellsession -container run --arch amd64 --rm registry.example.com/fido/web-test:latest uname -a +
+% container run --arch amd64 --rm registry.example.com/fido/web-test:latest uname -a Linux c0376e0a-0bfd-4eea-9e9e-9f9a2c327051 6.1.68 #1 SMP Mon Mar 31 18:27:51 UTC 2025 x86_64 GNU/Linux -``` +% +The command to push your multiplatform image to a registry is no different than that for a single-platform image: @@ -92,7 +93,7 @@ container images push registry.example.com/fido/web-test:latest Use the `inspect` command and send the result to the `jq` command to get pretty-printed JSON for the images or containers that you specify: -```shellsession +
% container images inspect web-test | jq
[
{
@@ -128,11 +129,11 @@ Use the `inspect` command and send the result to the `jq` command to get pretty-
"memoryInBytes": 1073741824,
},
...
-```
+
Use the `list` command with the `--format` option to display information for all images or containers. In this example, the `--all` option shows stopped as well as running containers, and `jq` selects the IP address for each running container:
-```shellsession
+% container ls --format json --all | jq '.[] | select ( .status == "running" ) | [ .configuration.id, .networks[0].address ]' [ "my-web-server", @@ -142,25 +143,25 @@ Use the `list` command with the `--format` option to display information for all "buildkit", "192.168.64.2/24" ] -``` +## View container logs The `container logs` command displays the output from your containerized application: -```shellsession +
% container run -d --dns-domain test --name my-web-server --rm registry.example.com/fido/web-test:latest my-web-server % curl http://my-web-server.test -Use the `--boot` option to see the logs for the virtual machine boot and init process: -```shellsession +Hello +<!DOCTYPE html><html><head><title>Hello</title></head><body><p><img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!</p></body></html> % container logs my-web-server 192.168.64.1 - - [15/May/2025 03:00:03] "GET / HTTP/1.1" 200 - % -``` +
% container logs --boot my-web-server [ 0.098284] cacheinfo: Unable to detect cache hierarchy for CPU 0 [ 0.098466] random: crng init done @@ -184,13 +185,13 @@ Use the `--boot` option to see the logs for the virtual machine boot and init pr [ 1.122742] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready 2025-05-15T02:24:39+0000 debug vminitd : sec=1747275879 usec=478412 [vminitd] setTime % -``` +## View system logs The `container system logs` command allows you to look at the log messages that `container` writes: -```shellsession +
% container system logs | tail -8 2025-06-02 16:46:11.560780-0700 0xf6dc5 Info 0x0 61684 0 container-apiserver: [com.apple.container:APIServer] Registering plugin [id=com.apple.container.container-runtime-linux.my-web-server] 2025-06-02 16:46:11.699095-0700 0xf6ea8 Info 0x0 61733 0 container-runtime-linux: [com.apple.container:RuntimeLinuxHelper] starting container-runtime-linux [uuid=my-web-server] @@ -201,4 +202,4 @@ The `container system logs` command allows you to look at the log messages that 2025-06-02 16:46:12.293193-0700 0xf6eaa Info 0x0 61733 0 container-runtime-linux: [com.apple.container:RuntimeLinuxHelper] `start` xpc handler [uuid=my-web-server] 2025-06-02 16:46:12.368723-0700 0xf6e93 Info 0x0 61684 0 container-apiserver: [com.apple.container:APIServer] Handling container my-web-server Start. % -``` +diff --git a/docs/tutorial.md b/docs/tutorial.md index 1fb96d67..b65b41f7 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -16,14 +16,16 @@ container system start If you have not installed a Linux kernel yet, the command will prompt you to install one: -```shellsession +
% container system start + Verifying apiserver is running... Installing base container filesystem... -No default kernel configured. -Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: y +No default kernel configured. +Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: y Installing kernel... -``` +% +Then, verify that the application is working by running a command to list all containers: @@ -33,17 +35,17 @@ container list --all If you haven't created any containers yet, the command outputs an empty list: -```shellsession +
% container list --all ID IMAGE OS ARCH STATE ADDR % -``` +### Get CLI help You can get help for any `container` CLI command by appending the `--help` option: -```shellsession +
% container --help OVERVIEW: A container platform for macOS @@ -76,17 +78,17 @@ SYSTEM SUBCOMMANDS: system, s Manage system components % -``` +### Abbreviations You can save keystrokes by abbreviating commands and options. For example, abbreviate the `container list` command to `container ls`, and the `--all` option to `-a`: -```shellsession +
% container ls -a ID IMAGE OS ARCH STATE ADDR % -``` +Use the `--help` flag to see which abbreviations exist. @@ -124,8 +126,8 @@ curl -L -o logo.jpg https://github.com/apple/container/tree/main/docs/assets/log In the `web-test` directory, create a file named `Dockerfile` with this content: -```docker -FROM docker.io/python:slim +```dockerfile +FROM docker.io/python:3-bookworm WORKDIR /content COPY logo.jpg ./ RUN echo '
Hello, world!
% container images list -NAME TAG DIGEST -docker.io/library/python slim 56a11364ffe0fee3bd60af6d... -web-test latest bf91dc9d42f0110d3aac41dd... +NAME TAG DIGEST +python 3-bookworm 8300f4e04ed367fafc5877b3... +web-test latest 464b4a20ac896b8e48e3d248... % -``` +## Run containers @@ -173,20 +175,20 @@ Using your container image, run a web server and try out different ways of inter Use `container run` to start a container named `my-web-server` that runs your webserver: ```bash -container run --name my-web-server --dns-domain test --detach --rm web-test +container run --name my-web-server --detach --rm web-test ``` The `--detach` flag runs the container in the background, so that you can continue running commands in the same terminal. The `--rm` flag causes the container to be removed automatically after it stops. When you list containers now, `my-web-server` is present, along with the container that `container` started to build your image. Note that its IP address, shown in the `ADDR` column, is `192.168.64.3`: -```shellsession +
% container ls -ID IMAGE OS ARCH STATE ADDR -buildkit ghcr.io/apple/container-builder-shim/builder:2.1.1 linux arm64 running 192.168.64.2 -my-web-server web-test:latest linux arm64 running 192.168.64.3 +ID IMAGE OS ARCH STATE ADDR +my-web-server web-test:latest linux arm64 running 192.168.64.3 +buildkit ghcr.io/apple/container-builder-shim/builder:0.0.3 linux arm64 running 192.168.64.2 % -``` +Open the website, using the container's IP address in the URL: @@ -204,24 +206,24 @@ open http://my-web-server.test You can run other commands in `my-web-server` by using the `container exec` command. To list the files under the content directory, run an `ls` command: -```shellsession +
% container exec my-web-server ls /content index.html logo.jpg % -``` +If you want to poke around in the container, run a shell and issue one or more commands: -```shellsession -% container exec --tty --interactive my-web-server bash -root@my-web-server:/content# ls +
+% container exec --tty --interactive my-web-server sh +# ls index.html logo.jpg -root@my-web-server:/content# uname -a -Linux my-web-server 6.1.68 #1 SMP Mon Mar 31 18:27:51 UTC 2025 aarch64 GNU/Linux -root@my-web-server:/content# exit +# uname -a +Linux my-web-server 6.12.28 #1 SMP Tue May 20 15:19:05 UTC 2025 aarch64 GNU/Linux +# exit % -``` +The `--tty` and `--interactive` flag allow you to interact with the shell from your host terminal. The `--tty` flag tells the shell in the container that its input is a terminal device, and the `--interactive` flag connects what you input in your host terminal to the input of the shell in the container. @@ -231,12 +233,16 @@ You will often see these two options abbreviated and specified together as `-ti` Your web server is accessible from other containers as well as from your host. Launch a second container using your `web-test` image, and this time, specify a `curl` command to retrieve the `index.html` content from the first container. -```shellsession -% container run -it --rm web-test curl http://192.168.64.3 -
Hello, world!
+% container run -it --rm web-test curl http://192.168.64.3 +<!DOCTYPE html><html><head><title>Hello</title></head><body><p><img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!</p></body></html> +% ++ If you set up the `test` domain earlier, you can achieve the same result with: ```bash @@ -271,11 +277,12 @@ container images push registry.example.com/fido/web-test:latest ### Pull and run your image -To validate your published image, remove your existing web server image, and then run using the remote image: +To validate your published image, stop your current web server container, remove the image that you built, and then run using the remote image: ```bash +container stop my-web-server container images delete web-test registry.example.com/fido/web-test:latest -container run --name my-web-server --dns-domain test --detach --rm registry.example.com/fido/web-test:latest +container run --name my-web-server --detach --rm registry.example.com/fido/web-test:latest ``` ## Clean up @@ -292,18 +299,12 @@ container stop my-web-server If you list all running and stopped containers, you will see that the `--rm` flag you supplied with the `container run` command caused the container to be removed: -```bash -% container ls --all -ID IMAGE OS ARCH STATE ADDR -buildkit ghcr.io/apple/container-builder-shim/builder:2.1.1 linux arm64 running 192.168.64.2 +
+% container list --all +ID IMAGE OS ARCH STATE ADDR +buildkit ghcr.io/apple/container-builder-shim/builder:0.0.3 linux arm64 running 192.168.64.2 % -``` - -To shut down and remove all containers, run: - -```bash -container rm --all --force -``` +### Stop the container service