Reorder README for Simplicity (#563)

TraceMachina · Dec 21, 2023 · b12dfb8 · b12dfb8
1 parent d823964
commit b12dfb8
Show file tree

Hide file tree

Showing 2 changed files with 97 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+⚠️ This software is very early in development and still in an alpha state with many quirks. If you use our ambitious project and please share feedback.
+
 # Native Link
 
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/TraceMachina/nativelink/badge)](https://securityscorecards.dev/viewer/?uri=github.com/TraceMachina/nativelink)
@@ -10,65 +12,85 @@ protocol](https://github.com/bazelbuild/remote-apis/blob/main/build/bazel/remote
 
 Supports Unix-based operating systems and Windows.
 
-## ❄️ Installing with Nix
-
-**Installation requirements:**
+## Getting Started with Native Link
 
-* Nix with [flakes](https://nixos.wiki/wiki/Flakes) enabled
+Below, you will find a few different options for getting started with Native Link.
 
-This build does not require cloning the repository, but you need to provide a
-config file, for instance the one at [nativelink-config/examples/basic_cas.json](./nativelink-config/examples/basic_cas.json).
 
-The following command builds and runs Native Link in release (optimized) mode:
+### 🦀 Installing with Cargo
 
-```sh
-nix run github:TraceMachina/nativelink ./basic_cas.json
+```bash
+cargo install --git https://github.com/TraceMachina/nativelink
 ```
 
-For use in production pin the executable to a specific revision:
+### ⚙️ Configuration
 
-```sh
-nix run github:TraceMachina/nativelink/<revision> ./basic_cas.json
+The `cas` executable reads a JSON file as it's only parameter, `--config`. See [nativelink-config](./nativelink-config/examples/basic_cas.json)
+for more details and examples.
+
+To grab the example in your current working directory, run:
+
+```bash
+curl -O https://raw.githubusercontent.com/TraceMachina/nativelink/main/nativelink-config/examples/basic_cas.json
 ```
 
-## 📦 Using the OCI image
+### Start Native Link
 
-See the published [OCI images](https://github.com/TraceMachina/nativelink/pkgs/container/nativelink)
-for pull commands.
+```bash
+cas basic_cas.json
+```
 
-Images are tagged by nix derivation hash. The most recently pushed image
-corresponds to the `main` branch. Images are signed by the GitHub action that
-produced the image. Note that the [OCI workflow](https://github.com/TraceMachina/nativelink/actions/workflows/image.yaml)
-might take a few minutes to publish the latest image.
+## 🧪 Evaluating Native Link
+
+Once you've built Native Link and have an instance running with the
+`basic_cas.json` configuration, launch a separate terminal session and run the
+following command to connect the running server launched above to Bazel or
+another RBE client:
 
 ```sh
-# Get the tag for the latest commit
-export LATEST=$(nix eval github:TraceMachina/nativelink#image.imageTag --raw)
+bazel test //... \
+  --remote_instance_name=main \
+  --remote_cache=grpc://127.0.0.1:50051 \
+  --remote_executor=grpc://127.0.0.1:50051 \
+  --remote_default_exec_properties=cpu_count=1
+```
 
-# Verify the signature
-cosign verify ghcr.io/tracemachina/nativelink:${LATEST} \
-    --certificate-identity=https://github.com/TraceMachina/nativelink/.github/workflows/image.yaml@refs/heads/main \
-    --certificate-oidc-issuer=https://token.actions.githubusercontent.com
+For Windows Powershell;
+
+```powershell
+bazel test //... `
+  --remote_instance_name=main `
+  --remote_cache=grpc://127.0.0.1:50051 `
+  --remote_executor=grpc://127.0.0.1:50051 `
+  --remote_default_exec_properties=cpu_count=1
 ```
+This causes Bazel to run the commands through an all-in-one `CAS`, `scheduler`
+and `worker`.
 
-For use in production pin the image to a specific revision:
 
-```sh
-# Get the tag for a specific commit
-export PINNED_TAG=$(nix eval github:TraceMachina/nativelink/<revision>#image.imageTag --raw)
+🎉 Tada 🎉 Native Link is working.
+
+
+## ❄️ Installing with Nix
+
+**Installation requirements:**
+
+* Nix with [flakes](https://nixos.wiki/wiki/Flakes) enabled
+
+This build does not require cloning the repository, but you need to provide a
+config file, for instance the one at [nativelink-config/examples/basic_cas.json](./nativelink-config/examples/basic_cas.json).
 
-# Verify the signature
-cosign verify ghcr.io/tracemachina/nativelink:${PINNED_TAG} \
-    --certificate-identity=https://github.com/TraceMachina/nativelink/.github/workflows/image.yaml@refs/heads/main \
-    --certificate-oidc-issuer=https://token.actions.githubusercontent.com
+The following command builds and runs Native Link in release (optimized) mode:
+
+```sh
+nix run github:TraceMachina/nativelink ./basic_cas.json
 ```
 
-> [!TIP]
-> The images are reproducible on `X86_64-unknown-linux-gnu`. If you're on such a
-> system you can produce a binary-identical image by building the `.#image`
-> flake output locally. Make sure that your `git status` is completely clean and
-> aligned with the commit you want to reproduce. Otherwise the image will be
-> tainted with a `"dirty"` revision label.
+For use in production pin the executable to a specific revision:
+
+```sh
+nix run github:TraceMachina/nativelink/<revision> ./basic_cas.json
+```
 
 ## 🌱 Building with Bazel
 
@@ -117,39 +139,6 @@ cargo run --bin cas -- ./nativelink-config/examples/basic_cas.json
 cargo run --release --bin cas -- ./nativelink-config/examples/basic_cas.json
 ```
 
-## 🧪 Evaluating Native Link
-
-Once you've built Native Link and have an instance running with the
-`basic_cas.json` configuration, launch a separate terminal session and run the
-following command to connect the running server launched above to Bazel or
-another RBE client:
-
-```sh
-bazel test //... \
-  --remote_instance_name=main \
-  --remote_cache=grpc://127.0.0.1:50051 \
-  --remote_executor=grpc://127.0.0.1:50051 \
-  --remote_default_exec_properties=cpu_count=1
-```
-
-For Windows Powershell;
-
-```powershell
-bazel test //... `
-  --remote_instance_name=main `
-  --remote_cache=grpc://127.0.0.1:50051 `
-  --remote_executor=grpc://127.0.0.1:50051 `
-  --remote_default_exec_properties=cpu_count=1
-```
-
-This causes bazel to run the commands through an all-in-one `CAS`, `scheduler`
-and `worker`.
-
-## ⚙️ Configuration
-
-The `cas` executable reads a JSON file as it's only parameter. See [nativelink-config](./nativelink-config)
-for more details and examples.
-
 ## 🚀 Example Deployments
 
 You can find a few example deployments in the [deployment-examples directory](./deployment-examples).

diff --git a/SECURITY.md b/SECURITY.md
@@ -23,3 +23,39 @@ If you'd rather communicate via email please contact <blaise@tracemachina.com>,
 
 See [Advisories](https://github.com/TraceMachina/nativelink/security/advisories)
 for publicly disclosed vulnerabilities.
+
+## Using OCI Images
+
+See the published [OCI images](https://github.com/TraceMachina/nativelink/pkgs/container/nativelink)
+for pull commands.
+
+Images are tagged by nix derivation hash. The most recently pushed image
+corresponds to the `main` branch. Images are signed by the GitHub action that
+produced the image. Note that the [OCI workflow](https://github.com/TraceMachina/nativelink/actions/workflows/image.yaml) might take a few minutes to publish the latest image.
+
+### Get the tag for the latest commit
+```sh
+export LATEST=$(nix eval github:TraceMachina/nativelink#image.imageTag --raw)
+```
+
+### Verify the signature
+```sh
+cosign verify ghcr.io/tracemachina/nativelink:${LATEST} \
+    --certificate-identity=https://github.com/TraceMachina/nativelink/.github/workflows/image.yaml@refs/heads/main \
+    --certificate-oidc-issuer=https://token.actions.githubusercontent.com
+```
+
+### Get the Tag for a Specific Commit
+For use in production pin the image to a specific revision:
+
+```sh
+# Get the tag for a specific commit
+export PINNED_TAG=$(nix eval github:TraceMachina/nativelink/<revision>#image.imageTag --raw)
+```
+
+> [!TIP]
+> The images are reproducible on `X86_64-unknown-linux-gnu`. If you're on such a
+> system you can produce a binary-identical image by building the `.#image`
+> flake output locally. Make sure that your `git status` is completely clean and
+> aligned with the commit you want to reproduce. Otherwise the image will be
+> tainted with a `"dirty"` revision label.