From f61f905dd1fdc97ad676b6c80c1f1e7d28c79746 Mon Sep 17 00:00:00 2001 From: Olly Pomeroy Date: Thu, 2 Nov 2023 10:34:07 +0000 Subject: [PATCH] docs: Remove documentation duplicated on the website Signed-off-by: Olly Pomeroy --- README.md | 133 ++----------------------------------------- docs/snapshotters.md | 33 ----------- docs/soci.md | 82 -------------------------- 3 files changed, 5 insertions(+), 243 deletions(-) delete mode 100644 docs/snapshotters.md delete mode 100644 docs/soci.md diff --git a/README.md b/README.md index d45ea8e9e..c238ac638 100644 --- a/README.md +++ b/README.md @@ -23,140 +23,17 @@ With Finch, you can leverage these existing projects without chasing down all th ## Getting Started with Finch on macOS -The project will in the near future have a more full set of documentation and tutorials. For now let's get started here. As mentioned above, `finch` integrates with `nerdctl`. While Finch doesn't implement 100% of the upstream commands, the most common commands are in place and working. The [nerdctl Command Reference](https://github.com/containerd/nerdctl#command-reference) can be relied upon as a starting point for documentation. +Finch's website ([runfinch.com](https://runfinch.com/)) provides full documentation for Finch. To help you get started see the following pages: -### Installing Finch - -To get started with Finch on macOS, the prerequisites are: - -* macOS catalina (10.15) or higher, newer versions are tested on a best-effort basis -* Intel or Apple Silicon M1 system for macOS -* Recommended minimum configuration is 2 CPU, 4 GB memory - -Download a release package for your architecture from the [project's GitHub releases](https://github.com/runfinch/finch/releases) page, and once downloaded double click and follow the directions. - -#### Installing Finch via [brew](https://brew.sh/) - -```sh -brew install --cask finch -``` - -Once the installation is complete, `finch vm init` is required once to set up the underlying system. This initial setup usually takes about a minute. - -```sh -finch vm init -INFO[0000] Initializing and starting Finch virtual machine... -.. -INFO[0067] Finch virtual machine started successfully -``` - -### Running containers and building images - -You can now run a test container. If you're familiar with container development, you can use the `run` command as you'd expect. - -```sh -finch run --rm public.ecr.aws/finch/hello-finch -``` - -If you're new to containers, that is so exciting! Give the command above a try after you've installed and initialized Finch. The `run` command pulls an image locally if it's not already present, and then creates and runs a container for you. Note the handy `--rm` option will delete the container instance once it's done executing. - -To build an image, try a quick example from the finch client repository. - -```sh -git clone https://github.com/runfinch/finch.git -cd finch/contrib/hello-finch -finch build . -t hello-finch -.. -``` - -Again if you're new to containers, you just built a container image. Nice! - -The `build` command will work with the build system (the Moby Project's BuildKit in Finch's case) to create an OCI image from a Dockerfile, which is a special sort of recipe for creating an image. This image can then be used to create containers. You can see your locally pulled and built images with the `finch images` command. - -Finch makes it easy to build and run containers across architectures with the `--platform` option. When used with the `run` command, it will create a container using the specified architecture. For example, on an Apple Silicon M1 system, `--platform=amd64` will create a container and run processes within it using an x86-64 architecture. - -```sh -uname -ms -Darwin arm64 - -finch run --rm --platform=amd64 public.ecr.aws/amazonlinux/amazonlinux uname -ms -Linux x86_64 -``` - -You can also use the `--platform` option with builds, making it easy to create multiplatform images. - -## Working with Finch - -We have plans to create some more documentation and tutorials here geared toward users who are new to containers, as well as some tips and tricks for more advanced users. For now, if you're ready to kick the tires, please do! You'll find most commands and options you're familiar with from other tools to present, and as you'd expect (or, as they are [documented upstream with nerdctl](https://github.com/containerd/nerdctl#command-reference)). Most of the commands we use every day are covered, including volume and network management as well as Compose support. If Finch doesn't do something you want it to, please consider opening an Issue or a Pull Request. +* [Installing Finch](https://runfinch.com/docs/managing-finch/macos/installation/) +* [Building your first container image](https://runfinch.com/docs/getting-started/building-images/) +* [Finch CLI Reference](https://runfinch.com/docs/cli-reference/finch_build/) +* [Finch Configuration Reference](https://runfinch.com/docs/configuration-reference/) ### Finch and other tools The installer will install Finch and its dependencies in its own area of your system, and it can happily coexist with other container development tools. Finch is a new project and not meant to be a direct drop-in replacement for other tools. Therefore, we don't recommend aliasing or linking other command names to `finch`. -### Configuration - -Finch has a simple and extensible configuration. A configuration file at `${HOME}/.finch/finch.yaml` will be generated on first run. Currently, this config file has options for system resource limits for the underlying virtual machine. These default limits are generated dynamically based on the resources available on the host system, but can be changed by manually editing the config file. - -For a full list of configuration options, check [the struct here](pkg/config/config.go#L30). - -An example `finch.yaml` looks like this: - -```yaml -# cpus: the amount of vCPU to dedicate to the virtual machine. (required) -cpus: 4 -# memory: the amount of memory to dedicate to the virtual machine. (required) -memory: 4GiB -# snapshotters: the snapshotters a user wants to use (the first snapshotter will be set as the default snapshotter) -# Supported Snapshotters List: -# - soci https://github.com/awslabs/soci-snapshotter/tree/main -# Once the option has been set the snapshotters will be installed on either finch vm init or finch vm start. -# The snapshotters binary will be downloaded on the virtual machine and will be configured and ready for use. -# To change your default snpahotter back to overlayfs, simply remove the snapshotters value from finch.yaml or set snapshotters to `overlayfs` -# To completely remove the snapshotters' binaries, shell into your VM and remove /usr/local/bin/{snapshotter binary} -# and remove the snapshotter configuration in the containerd config file found at /etc/containerd/config.toml -snapshotters: - - soci -# creds_helpers: a list of credential helpers that will be installed and configured automatically. -# Supported Credential Helpers List: -# - ecr-login https://github.com/awslabs/amazon-ecr-credential-helper -# Once the option has been set the credential helper will be installed on either finch vm init or finch vm start. -# The binary will be downloaded on the host machine and a config.json will be created and populated inside the ~/.finch/ folder -# if it doesn't already exist. If it already exists, the value of credsStore will be overwritten. -# To opt out of using the credential helper, remove the value from the credsStore parameter of config.json -# and remove the creds_helper value from finch.yaml. -# To completely remove the credential helper, either remove the binary from ~/.finch/creds-helpers or remove the creds-helpers -# folder entirely. (optional) -creds_helpers: - - ecr-login -# additional_directories: the work directories that are not supported by default. In macOS, only home directory is supported by default. -# For example, if you want to mount a directory into a container, and that directory is not under your home directory, -# then you'll need to specify this field to add that directory or any ascendant of it as a work directory. (optional) -additional_directories: - # the path of each additional directory. - - path: /Volumes -# vmType (Experimental): sets which Hypervisor to use to launch the VM. (optional) -# Only takes effect when a new VM is launched (only on vm init). -# One of: "qemu", "vz". -# - "qemu" (default): Uses QEMU as the Hypervisor. -# - "vz": Uses Virtualization.framework as the Hypervisor. -vmType: "qemu" -# rosetta (Experimental): sets whether to enable Rosetta as the binfmt_misc handler inside the VM. (optional) -# Only takes effect when a new VM is launched (only on vm init). -# Only available when using vmType "vz" on Apple Silicon running macOS 13+. -# If true, also sets vmType to "vz". -rosetta: false -``` - -### FAQ - -This section contains frequently-asked questions regarding working with Finch. - -#### How to shell into the VM? - -```sh -LIMA_HOME=/Applications/Finch/lima/data /Applications/Finch/lima/bin/limactl shell finch -``` - ## What's next? We are excited to start this project in the open, and we'd love to hear from you. If you have ideas or find bugs please open an issue. Please feel free to start a discussion if you have something you'd like to propose or brainstorm. Pull requests are welcome, as well! See the [CONTRIBUTING](CONTRIBUTING.md) doc for more info on contributing, and the path to reviewer and maintainer roles for those interested. diff --git a/docs/snapshotters.md b/docs/snapshotters.md deleted file mode 100644 index d7a35847f..000000000 --- a/docs/snapshotters.md +++ /dev/null @@ -1,33 +0,0 @@ -# Snapshotters Config Option - -## Issue - -[#506](https://github.com/runfinch/finch/pull/506) - -## Supported snapshotters - -- OverlayFS (default if none configured) -- [SOCI](https://github.com/awslabs/soci-snapshotter) - -## `snapshotters` option - -Users can use the snapshotters option at `${HOME}/.finch/finch.yaml` to set the snapshotters they would like to use. -All snapshotters listed will be installed on the VM, and the first snapshotter listed will be made the default snapshotter. -The default snapshotter will be used whenever a snapshotter is needed and not specified for a command. -Any other listed snapshotters can be used by specifying them with the `--snapshotter` flag: - -```console -# finch pull ... # uses the default snapshotter -# finch --snapshotter=mySnapshotter pull ... # uses mySnapshotter -``` - -```yaml -snapshotters: - - overlayfs - - soci - -# This example would set overlayfs as the default snapshotter and install SOCI on the VM so it can be used by the user if specified later. -``` - -To stop using a snapshotter, simply remove it from the `snapshotters` list. Snapshotters will not be automatically uninstalled from the VM once removed from the list. -To remove it completely the user must shell into the VM and remove the binaries for the snapshotter from `usr/local/bin` diff --git a/docs/soci.md b/docs/soci.md deleted file mode 100644 index 88b3d66dd..000000000 --- a/docs/soci.md +++ /dev/null @@ -1,82 +0,0 @@ -# Lazy-pulling using SOCI Snapshotter - -| :bird: Requirement for pull and run | finch >= 0.8.0 | -|-----------------------------------|----------------| - -| :bird: Requirement for push with SOCI | finch >= 0.9.0 | -|---------------------------------------|----------------| - -## Using SOCI - -[SOCI](https://github.com/awslabs/soci-snapshotter/tree/main) (short for “Seekable OCI” and pronounced “so-CHEE”) is a lazy-loading snapshotter that is able to skip the build-time conversion step when loading an image. - -SOCI does this by using a special artifact called the SOCI index that is comprosied of zTOCs that can be used to access parts of an image layer without fully unpacking the layer. - -By creating a seperate index and not converting the image, SOCI is able to keep image signatures consistent. - -- To enable SOCI add `"- soci"` to the `snapshotters` list in the finch config file (`${HOME}/.finch/finch.yaml`): - -```yaml -snapshotters: - - soci -``` - -This will set SOCI as your default snapshotter and you can then run commands as usual and SOCI will be used (i.e. `finch pull ...` will use SOCI by default). -If you don't want SOCI be the default snapshotter, but would still like it to be installed on the VM for later use you can set `snapshotters` as: - -```yaml -snapshotters: - - overlayfs - - soci -``` - -> **NOTE** -> More info on using the `snapshotters` config option can be found in [`snapshotters.md`](https://github.com/runfinch/finch/blob/main/docs/design/snapshotters.md). - -To get the full benefit of SOCI, users need to pull and run images that have a SOCI index. Although creating a SOCI index for images is not yet supported on Finch, -images that already have SOCI indices can be found [here](https://gallery.ecr.aws/soci-workshop-examples?page=1). -Indices can also be created using [ECR](https://aws-ia.github.io/cfn-ecr-aws-soci-index-builder/). - -## Performance Benefit - -In many cases, SOCI provides container start-up improvements when compared to other snapshotters. -As image size increases, the benefits of using SOCI often become even more significant. -This can be seen with some of the performance benefits that customers saw after SOCI was integrated with Fargate -([https://aws.amazon.com/blogs/aws/aws-fargate-enables-faster-container-startup-using-seekable-oci/](https://aws.amazon.com/blogs/aws/aws-fargate-enables-faster-container-startup-using-seekable-oci/)). - -### Example - -*Pulling an image with overlayfs:* - -```console -# finch --snapshotter=overlayfs pull public.ecr.aws/soci-workshop-examples/rabbitmq:latest -public.ecr.aws/soci-workshop-examples/rabbitmq:latest: resolved |++++++++++++++++++++++++++++++++++++++| -manifest-sha256:7d4d0320157c1493853df75ad68f2abefcc397c38023c499d6fd1d0736a93577: done |++++++++++++++++++++++++++++++++++++++| -config-sha256:74a35d13c21f7cada5874b4b66e1e930efe0ab8d2bea54bc90d93cebc1d44d6f: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:a571e766846a7a8f25f49ac22f5e2128e6b4ad17ad0bbd5d7fec8c5f6707d140: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:99803d4b97f3db529ae9ca4174b0951afac6b309e7deaa8ec3214c584e02b3a8: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:6ae56123b5f3fd69528cfef8099f28287eb22a574c5c5e7a7d479129f24c9956: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:1e76166effaab90f19fe3168cc354686c3195ca857a567c974cba12cfb36dc3f: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:778d7f6440dcc8d94f29eab78819fdbd296217cbeee40364f4cc9e9fc41790a3: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:13fff0192353d16aeb17f4f4f33e2636bf2120ae512c0cf7dc9abcf5a92344ba: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:d51b58b57cc4e9cfbf50fe8256ae47ece277221d320e0ee02cf9ec098052874e: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:491a78add9a9d6a3bff4c679a77161343f3f634161a81c4b2c8d7bcbed19e09e: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:bff9333d09b006aa7e28e75b69fa53452a8c649a279ff1462f53be9b32ef893f: done |++++++++++++++++++++++++++++++++++++++| -layer-sha256:31ce84a58f6fbf0179f8550cbc0ddd05018aa480387e20ee1aff1ca64bcba5a4: done |++++++++++++++++++++++++++++++++++++++| -elapsed: 12.5s total: 106.0 (8.5 MiB/s) -``` - -*Pulling the same image with SOCI:* - -```console -# finch pull public.ecr.aws/soci-workshop-examples/rabbitmq:latest -public.ecr.aws/soci-workshop-examples/rabbitmq:latest: resolved |++++++++++++++++++++++++++++++++++++++| -manifest-sha256:7d4d0320157c1493853df75ad68f2abefcc397c38023c499d6fd1d0736a93577: done |++++++++++++++++++++++++++++++++++++++| -config-sha256:74a35d13c21f7cada5874b4b66e1e930efe0ab8d2bea54bc90d93cebc1d44d6f: done |++++++++++++++++++++++++++++++++++++++| -elapsed: 6.7 s -``` - -From this small example, we can see how much more efficient SOCI was in lazy-loading the image. - -> **NOTE** -> Currently only `finch pull` and `finch run` have SOCI support (as of [Nerdctl 1.5.0](https://github.com/containerd/nerdctl/releases/tag/v1.5.0))