Skip to content

Commit

Permalink
Reorder README for Simplicity
Browse files Browse the repository at this point in the history
  • Loading branch information
@MarcusSorealheis
MarcusSorealheis committed Dec 21, 2023
1 parent 0d18d36 commit cb2b155
Show file tree
Hide file tree
Showing 3 changed files with 231 additions and 105 deletions.
134 changes: 64 additions & 70 deletions README.md
View file
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,7 +12,66 @@ protocol](https://github.com/bazelbuild/remote-apis/blob/main/build/bazel/remote

Supports Unix-based operating systems and Windows.

## ❄️ Installing with Nix
## Getting Started with Native Link

Below, you will find a few different options for getting started with Native Link.


### 🦀 Installing with Cargo

```bash
cargo install --git https://github.com/TraceMachina/nativelink
```

### ⚙️ Configuration

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
```

### Start Native Link

```bash
cas 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`.


🎉 Tada 🎉 Native Link is working.


## ❄️ Installing with Nix (Optional)

**Installation requirements:**

Expand All @@ -31,44 +92,10 @@ For use in production pin the executable to a specific revision:
nix run github:TraceMachina/nativelink/<revision> ./basic_cas.json
```

## 📦 Using the OCI image

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.

```sh
# Get the tag for the latest commit
export LATEST=$(nix eval github:TraceMachina/nativelink#image.imageTag --raw)

# 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 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)
## 📦 Working with Docker/Containers

# 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 canonical container workflow is still being developed and should be released soon. For diehard Docker users, check out [deployment-examples/docker-compose](./deployment-examples/docker-compose/README.md).

> [!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.

## 🌱 Building with Bazel

Expand Down Expand Up @@ -117,39 +144,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
49 changes: 14 additions & 35 deletions nativelink-config/examples/basic_cas.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,22 @@
"AC_MAIN_STORE": {
"memory": {
"eviction_policy": {
// 100mb.
"max_bytes": 100000000,
"max_bytes": 100000000
}
}
},
"WORKER_FAST_SLOW_STORE": {
"fast_slow": {
// "fast" must be a "filesystem" store because the worker uses it to make
// hardlinks on disk to a directory where the jobs are running.
"fast": {
"filesystem": {
"content_path": "/tmp/nativelink/data-worker-test/content_path-cas",
"temp_path": "/tmp/nativelink/data-worker-test/tmp_path-cas",
"eviction_policy": {
// 10gb.
"max_bytes": 10000000000,
"max_bytes": 10000000000
}
}
},
"slow": {
/// Discard data.
/// This example usage has the CAS and the Worker live in the same place,
/// so they share the same underlying CAS. Since workers require a fast_slow
/// store, we use the fast store as our primary data store, and the slow store
/// is just a noop, since there's no shared storage in this config.
"noop": {}
}
}
Expand All @@ -50,42 +41,34 @@
"cpu_vendor": "exact",
"cpu_arch": "exact",
"cpu_model": "exact",
"kernel_version": "exact",
// Example of how to set which docker images are available and set
// them in the platform properties.
// "docker_image": "priority",
"kernel_version": "exact"
}
}
}
},
"workers": [{
"local": {
"worker_api_endpoint": {
"uri": "grpc://127.0.0.1:50061",
"uri": "grpc://127.0.0.1:50061"
},
"cas_fast_slow_store": "WORKER_FAST_SLOW_STORE",
"upload_action_result": {
"ac_store": "AC_MAIN_STORE",
"ac_store": "AC_MAIN_STORE"
},
"work_directory": "/tmp/nativelink/work",
"platform_properties": {
"cpu_count": {
"values": ["16"],
"values": ["16"]
},
"memory_kb": {
"values": ["500000"],
"values": ["500000"]
},
"network_kbps": {
"values": ["100000"],
"values": ["100000"]
},
"cpu_arch": {
"values": ["x86_64"],
},
// Example of how to set which docker images are available and set
// them in the platform properties.
// "docker_image": {
// "query_cmd": "docker images --format {{.Repository}}:{{.Tag}}",
// }
"values": ["x86_64"]
}
}
}
}],
Expand All @@ -110,19 +93,19 @@
"execution": {
"main": {
"cas_store": "WORKER_FAST_SLOW_STORE",
"scheduler": "MAIN_SCHEDULER",
"scheduler": "MAIN_SCHEDULER"
}
},
"capabilities": {
"main": {
"remote_execution": {
"scheduler": "MAIN_SCHEDULER",
"scheduler": "MAIN_SCHEDULER"
}
}
},
"bytestream": {
"cas_stores": {
"main": "WORKER_FAST_SLOW_STORE",
"main": "WORKER_FAST_SLOW_STORE"
}
}
}
Expand All @@ -137,12 +120,8 @@
"experimental_prometheus": {
"path": "/metrics"
},
// Note: This should be served on a different port, because it has
// a different permission set than the other services.
// In other words, this service is a backend api. The ones above
// are a frontend api.
"worker_api": {
"scheduler": "MAIN_SCHEDULER",
"scheduler": "MAIN_SCHEDULER"
},
"admin": {}
}
Expand Down
Loading

0 comments on commit cb2b155

Please sign in to comment.