From ff59bb38e8da50ccab4075e3d8b6e6942524612e Mon Sep 17 00:00:00 2001 From: J Logan Date: Sun, 8 Jun 2025 17:30:40 -0700 Subject: [PATCH] Use bookworm in tutorial, disable console block copy. (#39) - Switched to use bookworm Python image as `curl` is not in slim. - Use `pre` tags for console blocks. We lose syntax highlighting, but get rid of the copy button. - Fix `dockerfile` tag in tutorial. - Fix GitHub typo in README. --- README.md | 2 +- docs/how-to.md | 41 ++++++++++---------- docs/tutorial.md | 99 ++++++++++++++++++++++++------------------------ 3 files changed, 72 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index e3455e5f..81b63e8b 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ If you're upgrading, first uninstall your existing `container` while preserving uninstall-container.sh -k ``` -Download the latest signed installer package for `container` from the [Github release page](https://github.com/apple/container/releases). +Download the latest signed installer package for `container` from the [GitHub release page](https://github.com/apple/container/releases). To install the tool, double click the package file and follow the instructions. Enter your administrator password when prompted, to give the installer permission to place the installed files under `/usr/local`. diff --git a/docs/how-to.md b/docs/how-to.md index 44b6d986..5694357c 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -34,7 +34,7 @@ With the `--volume` option of `container run`, you can share data between the ho This example mounts a folder named `assets` on your Desktop to the directory `/content/assets` in a container: -```shellsession +
 % 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                                                                                   
-Hello
Hello, world!

+<!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 -
 %
-```
+
Use the `--boot` option to see the logs for the virtual machine boot and init process: -```shellsession +
 % 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

Hello, world!

' > index.html @@ -156,13 +158,13 @@ The last argument `.` tells the builder to use the current directory (`web-test` After the build completes, list the images. You should see both the base image and the image that you built in the results: -```shellsession +
 % 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

Hello, world!

-% +```bash +container run -it --rm web-test curl http://192.168.64.3 ``` +
+% 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