Refine user documentation. (#24)

jglogan · web-flow · commit 94e06e28a0c9 · 2025-06-05T18:50:40.000-07:00
- Extract README sections into BUILDING and CONTRIBUTING documents. This
should work better than sections in README as it keeps the README short,
and the BUILDING and CONTRIBUTING files will stand out in the file list.
- Merged localdev document into BUILDING.
- Fixed broken links.
- Changed DNS setup so later DNS-dependent steps should work.
- Added h1 and link to SECURITY document.
diff --git a/BUILDING.md b/BUILDING.md
@@ -1,8 +1,35 @@
-# Develop using a local copy of Containerization
+# Building the project
 
-This page describes how to build and run container using a local copy of [`Containerization`](https://github.com/apple/containerization).
+To build the Containerization package, your system needs either:
 
-## Use the local copy of containerization
+- macOS 15 or newer and Xcode 17 beta.
+- macOS 16 Developer Preview.
+
+## Compile and test
+
+Build `container` and the background services from source, and run basic and integration tests:
+
+```bash
+make all test integration
+```
+
+Copy the binaries to `/usr/local/bin` and `/usr/local/libexec` (requires entering the an administrator password):
+
+```bash
+make install
+```
+
+## Compile protobufs
+
+`container` uses gRPC to communicate to the builder virtual machine that creates images from `Dockerfile`s, and depends on specific versions of `grpc-swift` and `swift-protobuf`. If you make changes to the gRPC APIs in the [container-builder-shim](https://github.com/apple/container-builder-shim) project, install the tools and re-generate the gRPC code in this project using:
+
+```bash
+make protos
+```
+
+## Develop using a local copy of Containerization
+
+To make changes to `container` that require changes to the Containerization project, or vice versa:
 
 1. Clone the [Containerization](https://github.com/apple/containerization) repository such that it sits next to your clone of the `container` repository.
 
@@ -43,7 +70,7 @@ This page describes how to build and run container using a local copy of [`Conta
     bin/container system start
     ```
 
-## Revert to the versioned Containerization package
+To revert to using the Containerization dependency from your `Package.swift`:
 
 1. Unset your `CONTAINERIZATION_PATH` environment variable, and update `Package.resolved`.
     
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,3 @@
+# Contributing 
+
+Contributions are welcome and encouraged! Read our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) to get started.
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
-# `container`
-
 ![introductory movie showing some basic commands](./docs/assets/landing-movie.gif)
 
+# `container`
+
 `container` is an application that you can use to create and run Linux containers as lightweight virtual machines on your Mac. It's written in Swift, and optimized for Apple Silicon. 
 
 The application consumes and produces OCI-compliant container images, so you can pull and run images from any standard container registry. You can push images that you build to those registries as well, and run the images in any other OCI-compliant application.
@@ -14,14 +14,9 @@ Install the `container` application on your Mac.
 
 ### Requirements
 
-You need an Apple Silicon Mac to build and run `container`.
-
-To build the Containerization package, your system needs either:
-
-- macOS 15 or newer and Xcode 17 beta.
-- macOS 16 Developer Preview.
+You need an Apple Silicon Mac to run `container`. To build the application, see the [BUILDING](./BUILDING.md) document.
 
-`container` is designed to take advantage of the features of the macOS 16 Developer Preview. You can run the application on macOS Sequoia, but the `container` maintainers typically will not address Sequoia issues that cannot be reproduced on the macOS 16 Developer Beta.
+`container` is designed to take advantage of the features of the macOS 16 Developer Preview. You can run the application on macOS Sequoia, but the `container` maintainers typically will not address Sequoia issues that cannot be reproduced on the macOS 16 Developer Preview.
 
 There are [significant networking limitations](https://github.com/apple/container#macos-sequoia-limitations) that impact the usability `container` on macOS Sequoia.
 
@@ -51,36 +46,9 @@ To retain your user data so that it is available should you reinstall later, run
 uninstall-container.sh -k
 ```
 
-## Build the application from source
-
-Build `container` and the background services from sources and run basic and integration tests:
-
-```bash
-make all test integration
-```
-
-Copy the binaries to `/usr/local/bin` and `/usr/local/libexec` (requires entering the administrator's password):
-
-```bash
-make install
-```
-
-### Protobufs
-
-`container` depends on specific versions of `grpc-swift` and `swift-protobuf`. You can install them and re-generate RPC interfaces with:
-
-```bash
-make protos
-```
-
-## Contributing 
-
-Contributions are welcome and encouraged! Read our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) to get started.  If you're developing using a local copy of 
-Containerization read the [docs here](./docs/localSwiftContainerization.md)
-
- ## More Info:
+## Next steps
 
 - Take [a guided tour of `container`](./docs/tutorial.md) by building, running, and publishing a simple web server image.
-- Read through [How to use the features of `container`.](./docs/how-to.md)
-- A brief description and [technical overview](./docs/technical-overview.md) of `container`.
+- Learn how to [use various `container` features](./docs/how-to.md).
+- Read a brief description and [technical overview](./docs/technical-overview.md) of `container`.
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,4 +1,6 @@
-If you believe that you have discovered a security or privacy vulnerability in our open source software, please report it to us using the GitHub private vulnerability feature. Reports should include specific product and software version(s) that you believe are affected; a technical description of the behavior that you observed and the behavior that you expected; the steps required to reproduce the issue; and a proof of concept or exploit.
+# Security process
+
+If you believe that you have discovered a security or privacy vulnerability in our open source software, please report it to us using the [GitHub private vulnerability feature](https://github.com/apple/container/security/advisories/new). Reports should include specific product and software version(s) that you believe are affected; a technical description of the behavior that you observed and the behavior that you expected; the steps required to reproduce the issue; and a proof of concept or exploit.
 
 The project team will do their best to acknowledge receiving all security reports within 7 days of submission. This initial acknowledgment is neither acceptance nor rejection of your report. The project team may come back to you with further questions or invite you to collaborate while working through the details of your report.
 
diff --git a/docs/technical-overview.md b/docs/technical-overview.md
@@ -40,11 +40,11 @@ The process `container-apiserver` is a launch agent that launches when you run t
 
 When `container-apiserver` starts, it launches an XPC helper `container-core-images` that exposes an API for image management and manages the local content store, and another XPC helper `container-network-vmnet` for the virtual network. For each container that you create, `container-apiserver` launches a container runtime helper `container-runtime-linux` that exposes the management API for that specific container.
 
-![diagram showing application functional organization](./docs/assets/functional-model-light.svg)
+![diagram showing application functional organization](/docs/assets/functional-model-light.svg)
 
 ## What limitations does `container` have today?
 
-With the initial release of `container`, you get basic facilities for building and running containers, but many common containerization features remain to be implemented. Consider [contributing](/community) new features and bug fixes to `container` and the Containerization projects!
+With the initial release of `container`, you get basic facilities for building and running containers, but many common containerization features remain to be implemented. Consider [contributing](/CONTRIBUTING.md) new features and bug fixes to `container` and the Containerization projects!
 
 ### Container to host networking
 
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -19,14 +19,10 @@ If you have not installed a Linux kernel yet, the command will prompt you to ins
 ```shellsession
 % container system start
 Verifying apiserver is running...
-Done
-Missing required runtime dependencies:
- 1. Initial Filesystem
- 2. Kernel
-Would like to install them now? [Y/n]: Y
-Installing default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]...
-Installing initial filesystem from [ghcr.io/apple/containerization/vminit:0.1.34]...
-%
+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                        
+Installing kernel...
 ```
 
 Then, verify that the application is working by running a command to list all containers:
@@ -100,9 +96,12 @@ Use the `--help` flag to see which abbreviations exist.
 
 ```bash
 sudo container system dns create test
+container system dns default set test
 ```
 
-Enter your administrator password when prompted. The command requires administrator privileges to create a file containing the domain configuration under the `/etc/resolver` directory, and to tell the macOS DNS resolver to reload its configuration files.
+Enter your administrator password when prompted. The first command requires administrator privileges to create a file containing the domain configuration under the `/etc/resolver` directory, and to tell the macOS DNS resolver to reload its configuration files.
+
+The second command makes `test` the default domain to use when running a container with an unqualified name. For example, if the default domain is `test` and you use `--name my-web-server` to start a container, queries to `my-web-server.test` will respond with that container's IP address.
 
 ## Build an image
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Contributing`
	`2`	`+`
	`3`	`+Contributions are welcome and encouraged! Read our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) to get started.`