lee/container
1
0
Fork 0
mirror of https://github.com/apple/container.git synced 2026-07-21 00:41:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Use bookworm in tutorial, disable console block copy. (#39)

Browse Source 
- 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.
This commit is contained in:
J Logan
2025-06-08 17:30:40 -07:00
committed by GitHub
parent 50557aa786
commit ff59bb38e8
3 changed files with 72 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -1
View File
@@ -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`.
docs/how-to.md
+21 -20
View File
@@ -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
<pre>
% 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
%
```
</pre>
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
<pre>
% 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
%
```
</pre>
## 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
<pre>
% 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
%
```
</pre>
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
<pre>
% 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
```
%
</pre>
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
<pre>
% 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,
},
...
```
</pre>
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
<pre>
% 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"
]
```
</pre>
## View container logs
The `container logs` command displays the output from your containerized application:
```shellsession
<pre>
% 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
<!DOCTYPE html><html><head><title>Hello</title></head><body><p><img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!</p></body></html>
&lt;!DOCTYPE html>&lt;html>&lt;head>&lt;title>Hello&lt;/title>&lt;/head>&lt;body>&lt;p>&lt;img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!&lt;/p>&lt;/body>&lt;/html>
% container logs my-web-server
192.168.64.1 - - [15/May/2025 03:00:03] "GET / HTTP/1.1" 200 -
%
```
</pre>
Use the `--boot` option to see the logs for the virtual machine boot and init process:
```shellsession
<pre>
% 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
%
```
</pre>
## View system logs
The `container system logs` command allows you to look at the log messages that `container` writes:
```shellsession
<pre>
% 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.
%
```
</pre>
docs/tutorial.md
+50 -49
View File
@@ -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
<pre>
% 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...
```
%
</pre>
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
<pre>
% container list --all
ID IMAGE OS ARCH STATE ADDR
%
```
</pre>
### Get CLI help
You can get help for any `container` CLI command by appending the `--help` option:
```shellsession
<pre>
% container --help
OVERVIEW: A container platform for macOS
@@ -76,17 +78,17 @@ SYSTEM SUBCOMMANDS:
system, s Manage system components
%
```
</pre>
### 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
<pre>
% container ls -a
ID IMAGE OS ARCH STATE ADDR
%
```
</pre>
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 '<!DOCTYPE html><html><head><title>Hello</title></head><body><p><img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!</p></body></html>' > 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
<pre>
% 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...
%
```
</pre>
## 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
<pre>
% 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
%
```
</pre>
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
<pre>
% container exec my-web-server ls /content
index.html
logo.jpg
%
```
</pre>
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
<pre>
% 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
%
```
</pre>
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
<!DOCTYPE html><html><head><title>Hello</title></head><body><p><img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!</p></body></html>
%
```bash
container run -it --rm web-test curl http://192.168.64.3
```
<pre>
% container run -it --rm web-test curl http://192.168.64.3
&lt;!DOCTYPE html>&lt;html>&lt;head>&lt;title>Hello&lt;/title>&lt;/head>&lt;body>&lt;p>&lt;img src="logo.jpg" style="width: 2rem; height: 2rem;">Hello, world!&lt;/p>&lt;/body>&lt;/html>
%
</pre>
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
<pre>
% 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
```
</pre>
### Stop the container service