diff --git a/apollo-router/tests/scaffold.rs b/apollo-router/tests/scaffold.rs index 3c026f50687..d0c75d92322 100644 --- a/apollo-router/tests/scaffold.rs +++ b/apollo-router/tests/scaffold.rs @@ -9,7 +9,7 @@ mod common; struct CleanUp; impl Drop for CleanUp { fn drop(&mut self) { - // let _ = fs::remove_dir_all("../temp"); + let _ = fs::remove_dir_all("../temp"); } } #[test] diff --git a/docs/source/customizations/native-tutorial.mdx b/docs/source/customizations/native-tutorial.mdx new file mode 100644 index 00000000000..211269e0a6b --- /dev/null +++ b/docs/source/customizations/native-tutorial.mdx @@ -0,0 +1,115 @@ +--- +title: Creating a custom router binary +--- + +To create your own router binary with custom plugins you will need to use the router as a library. +This page will walk you through creating your own Router binary from scratch. + + +> Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). +> Read [our licensing page](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/) for more details. + +# Prerequisites + +To compile the Apollo Router you will need to have the following installed. + +* [rust 1.60.0](https://www.rust-lang.org/tools/install) +* nodejs 16.9.1 + +Once you have the basics installed, install `xtask` and `scaffold` +```bash +cargo install cargo-xtask +cargo install cargo-scaffold +``` + +# Create new project + +1. Use cargo scaffold to create the project. It will ask some questions about project. + + ```bash + cargo-scaffold scaffold https://github.com/apollographql/router.git -r /scaffold + ``` + You will be asked some questions about your project. For the purposes of this tutorial use `starstuff`. + +2. After the project has been created change to the `starstuff` directory + ```bash + cd starstuff + ``` + +# Compile the router + +To create a debug build use the following command. +```bash +cargo build +``` +Your debug binary is now located in `target/debug/router` + + +For production, you will want to create a release build. +```bash +cargo build --release +``` +Your release binary is now located in `target/release/router` + +# Run the Apollo Router + +1. Download the example schema + + ```bash + curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql + ``` + +2. Run the Apollo Router + + During development it is convenient to use `cargo run` to run the Apollo Router as it will + ```bash + cargo run -- -hot-reload -config router.yaml -supergraph supergraph-schema.graphql + ``` + +> If you are using managed federation you can set APOLLO_KEY and APOLLO_GRAPH_REF environment variables instead of specifying the supergraph as a file. + +# Create a plugin + +1. From within your project directory scaffold a new plugin + ```bash + cargo plugin create hello_world + ``` +2. Select the type of plugin you want to scaffold: + ```bash + Select a plugin template: + > "basic" + "auth" + "tracing" + ``` + + The different templates are: + * basic - a barebones plugin. + * auth - a basic authentication plugin that could make an external call. + * tracing - a plugin that adds a custom span and a log message. + + Choose `basic` + +3. Add the plugin to the `router.yaml` + ```yaml + plugins: + hello_world: + message: "Starting my plugin" + ``` + +4. Run the Apollo Router and see your plugin start up + ```bash + cargo run -- -hot-reload -config router.yaml -supergraph supergraph-schema.graphql + ``` + + In your output you should see something like: + ```bash + Starting my plugin + ``` + +# Remove a plugin + +1. From within your project run the following command. It makes a best effort to remove the plugin, but your mileage may vary. + ```bash + cargo plugin remove hello_world + ``` +