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.

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

🚢 update viceroy package name and README #41

Merged
merged 5 commits into from
Jul 15, 2021
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
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
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

73 changes: 24 additions & 49 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,48 +5,19 @@ allows you to run services written against the Compute@Edge APIs on your local
development machine, and allows you to configure testing backends for your
service to communicate with.

In the near future, Viceroy will be packaged as part of the Fastly CLI and
integrate with other Compute@Edge workflows. But for the moment, you can use it
by hand, as described below.
Viceroy is normally used through the [Fastly CLI's `fastly compute serve`
command][cli], where it it fully integrated into the Compute@Edge workflows.
However, it is also a standalone open source tool with its own CLI and a
Rust library that can be embedded into your own testing infrastructure.

[cli]: https://developer.fastly.com/learning/compute/testing/#running-a-local-testing-server

## Installation

To install Viceroy, you'll need to first
[install Rust](https://www.rust-lang.org/tools/install) if you haven't already.

### Clone the repo

You'll need to get a copy of the Viceroy source code locally, by cloning the
[Viceroy repo](https://github.com/fastly/Viceroy/) like so:

```
git clone git@github.com:fastly/Viceroy.git
cd Viceroy
git submodule update --recursive --init
```

### Install via Cargo

Next, navigate to the `Viceroy` directory resulting from the `git clone` above,
and run:

```
cargo install --path cli
```

You should see a message that says `Installing viceroy-cli` followed by a large
number of compilation messages. The end result is that the `viceroy` command
is made available on your system.

### Updating Viceroy

To update Viceroy, navigate to the `Viceroy` directory you cloned above, and then:

```
git pull
git submodule update --recursive --init
cargo install --path cli
```
Then run `cargo install viceroy`, which will download and build the latest
Viceroy release.

## Usage

Expand All @@ -59,28 +30,22 @@ built by `fastly compute build`. The Fastly CLI should put the blob at
viceroy bin/main.wasm
```

This will start a local server (by default at: `http://127.0.0.1:7878`), which can be used to make requests to, and execute, your C@E Wasm module. This can be done by using [curl](https://curl.se/), or you can send a simple GET request by visiting the URL in your web browser.

**NOTE:** Viceroy expects to find a `fastly.toml` manifest. It will look only in the
current directory by default; you can specify a path to the file using the
`--manifest-path` option. The manifest is used to configure backends, which we
describe next.
This will start a local server (by default at: `http://127.0.0.1:7878`), which can
be used to make requests to your Compute@Edge service locally. You can make requests
by using [curl](https://curl.se/), or you can send a simple GET request by visiting
the URL in your web browser.

### Configuring backends

Most Compute@Edge services need to make requests to named backends (origin
servers), which are normally configured using the Fastly UI. For testing with
Viceroy, you can specify backends in a **dedicated** TOML file, which you
Viceroy, you can specify backends in your `fastly.toml` file, which you
provide to Viceroy using the `-C` flag:

```
viceroy bin/main.wasm -C backends.toml
viceroy bin/main.wasm -C fastly.toml
```

In the future, testing backends will be part of the `fastly.toml` manifest
managed by the Fastly CLI, but for now you should **not** use the `fastly.toml`
manifest, because the Fastly CLI will remove any additions you make.

Backends are specified in the TOML file within a `local_server.backends`
section:

Expand Down Expand Up @@ -141,6 +106,16 @@ particular:
* Caching directives are ignored; no caching is ever performed.
* Information about the TLS connection from the client is not available.

## Working with Viceroy's source

Note that this repository uses Git submodules, so you will need to run

```
git submodule update --recursive --init
```

to pull down or update submodules.

## Colophon

![Viceroy](doc/logo.png)
Expand Down
2 changes: 1 addition & 1 deletion cli/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[package]
name = "viceroy-cli"
name = "viceroy"
description = "Viceroy is a local testing daemon for Compute@Edge."
version = "0.2.2"
authors = ["Fastly"]
Expand Down
2 changes: 1 addition & 1 deletion scripts/publish.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ const VERIFY_TEMPDIR: &str = "verify-publishable";
/// The crates that we will publish.
//
// N.B. This list must be topologically sorted by dependencies.
const CRATES_TO_PUBLISH: &[&str] = &["viceroy-lib", "viceroy-cli"];
const CRATES_TO_PUBLISH: &[&str] = &["viceroy-lib", "viceroy"];

/// The crates that we will NOT publish.
//
Expand Down