Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Reorder README for Simplicity #563

Merged
merged 1 commit into from
Dec 21, 2023
Merged

Reorder README for Simplicity #563

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 61 additions & 72 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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).
Expand Down
36 changes: 36 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.