From fee42adca6860c73e3df6098d497438466923503 Mon Sep 17 00:00:00 2001 From: Daniel Voogsgerd Date: Wed, 5 Mar 2025 16:35:24 +0100 Subject: [PATCH 1/2] fix: Remove broken links --- book.toml | 4 +++ src/SUMMARY.md | 5 +-- src/before-reading.md | 2 +- src/branescript/advanced.md | 2 +- src/branescript/basics.md | 12 +++---- src/branescript/hello-world.md | 35 +++++++++--------- src/branescript/introduction.md | 2 +- src/branescript/workflows-data.md | 16 ++++----- src/config/admins/backend.md | 2 +- src/config/admins/infra.md | 2 +- src/config/admins/node.md | 18 +++++----- src/config/admins/proxy.md | 4 +-- src/config/users/container.md | 4 +-- src/config/users/data.md | 2 +- src/overview.md | 2 +- src/packages/ecu.md | 2 ++ src/policy-experts/installation.md | 16 ++++----- src/policy-experts/policy-file.md | 2 +- src/scientists/bscript/introduction.md | 2 +- src/scientists/installation.md | 8 ++--- src/scientists/packages.md | 36 +++++++++---------- src/software-engineers/base64.md | 10 +++--- src/software-engineers/data.md | 6 ++-- src/software-engineers/filesystem.md | 2 +- src/software-engineers/hello-world.md | 4 +-- src/software-engineers/installation.md | 8 ++--- src/software-engineers/introduction.md | 2 +- src/system-admins/backends/introduction.md | 2 +- src/system-admins/installation/branectl.md | 12 +++---- .../installation/control-node.md | 4 +-- src/system-admins/installation/proxy-node.md | 4 +-- src/system-admins/installation/worker-node.md | 8 ++--- src/system-admins/introduction.md | 14 +++----- 33 files changed, 126 insertions(+), 128 deletions(-) create mode 100644 src/packages/ecu.md diff --git a/book.toml b/book.toml index 5dc0771..d11cb69 100644 --- a/book.toml +++ b/book.toml @@ -10,3 +10,7 @@ default-theme = "navy" site-url = "/manual/" git-repository-url = "https://github.com/braneframework/manual" git-repository-icon = "fa-github" + +[preprocessor.variables.variables] +specification_root = "https://braneframework.github.io/specification" +brane_docs_root = "https://braneframework.github.io/brane/unstable" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e899e69..78e1543 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -46,10 +46,6 @@ - [Variables](./scientists/bscript/variables.md) - [Control flow](./scientists/bscript/control-flow.md) - [Datasets in a workflow](./scientists/bscript/datasets.md) - - [Using the Brane-IDE](./scientists/jupyter.md) @@ -74,6 +70,7 @@ # Packages - [Introduction](./packages/introduction.md) - [`container.yml` documentation](./packages/container_yml.md) +- [Executable code unit](./packages/ecu.md) # BraneScript diff --git a/src/before-reading.md b/src/before-reading.md index 3922c18..4344987 100644 --- a/src/before-reading.md +++ b/src/before-reading.md @@ -21,4 +21,4 @@ Looked at from the highest level of abstraction, Brane has a client part (in the ## Where next To continue reading, we suggest you start at the first chapter for your role. You can select it in the sidebar to the left. -If you are part of the fifth, "hidden" role (the Brane administrators), you have [your own book](/admins); we recommend you continue there. It also details how to obtain, compile and run the framework for testing purposes. +If you are part of the fifth, "hidden" role (the Brane developers), you have [your own book]({{ specification_root }}); we recommend you continue there. It also details how to obtain, compile and run the framework for testing purposes. diff --git a/src/branescript/advanced.md b/src/branescript/advanced.md index 6e1dc4f..5550865 100644 --- a/src/branescript/advanced.md +++ b/src/branescript/advanced.md @@ -160,4 +160,4 @@ Note that there are a few peculiarities about parallel statements: println(res); ``` which will print `84`. - > info For a complete overview of all merge strategies, check the [BraneScript documentation](../../branescript/statements.md). + > info For a complete overview of all merge strategies, check the [BraneScript documentation]({{ specification_root }}/appendix/languages/bscript/features.html#parallel-statements). diff --git a/src/branescript/basics.md b/src/branescript/basics.md index bae7c4a..b6680cf 100644 --- a/src/branescript/basics.md +++ b/src/branescript/basics.md @@ -1,5 +1,5 @@ # Basic concepts -In the [previous chapter](./workflow.md), we discussed your first "Hello, world!"-workflow. In this chapter, we will extend upon this, and go over the basic language features of BraneScript. We will talk about things like variables, if-statements and loops, parallel statements and builtin-functions. +In the [previous chapter](./hello-world.md), we discussed your first "Hello, world!"-workflow. In this chapter, we will extend upon this, and go over the basic language features of BraneScript. We will talk about things like variables, if-statements and loops, parallel statements and builtin-functions. More complex features, such as arrays, function definitions, classes or Data and IntermediateResults, are left to the next few chapters. @@ -17,7 +17,7 @@ So, how can we use this? The first step is to declare a new variable, to make Br ```bscript let := ; ``` -where `` is some identifier that you want to use for your variable (existing only of alphanumeric characters and an underscore, `_`), and `` is some code that _evaluates_ to a certain value. We've already seen an example of this: a function call is an expression, since it has a return value that we can pass to other functions or statements. Other expressions include _literal values_ (e.g., `true`, `42`, `3.14` or `"Hello, there!"`) or logical or mathmatical operations (e.g., addition, subtraction, logical conjunction, comparison, etc). For some more examples, see [below](#arrays), or check the [BraneScript documentation](../../branescript/expressions.md) for a full overview. +where `` is some identifier that you want to use for your variable (existing only of alphanumeric characters and an underscore, `_`), and `` is some code that _evaluates_ to a certain value. We've already seen an example of this: a function call is an expression, since it has a return value that we can pass to other functions or statements. Other expressions include _literal values_ (e.g., `true`, `42`, `3.14` or `"Hello, there!"`) or logical or mathmatical operations (e.g., addition, subtraction, logical conjunction, comparison, etc). For some more examples, see [below](#arrays), or check the [BraneScript documentation]({{ specification_root }}/appendix/languages/bscript/features.html#expressions) for a full overview. Yet another example of an expression is a _variable reference_, which effectively reads a particular variable. To use it, simply specify the identifier of the variable you declared (`ID`) any time you can use an expression. For example: ```bscript @@ -57,7 +57,7 @@ foo := foo * 2; ## Functions -Something that you've already seen used in the [previous chapter](./workflow.md) and the previous section, is the use of _function calls_. +Something that you've already seen used in the [previous chapter](./hello-world.md) and the previous section, is the use of _function calls_. This concept is used in almost any language, and essentially represents a temporary jump to some other part of code that is executed, and then the program continues from the function call onwards. Crucially, we typically allow these snippets to take in some values - _arguments_ - and hand us back a value when they are done - a _return value_. @@ -82,14 +82,14 @@ let fourty_two := add(add(add(2, add(zero(), 20)), zero()), 20); println(fourty_two); // Should print '42' ``` -Note that BraneScript uses the same syntax for calling imported functions (see the [previous chapter](./workflow.md) with the `hello_world()`-function), builtin functions (think `println()`; see [below](#builtin-functions)) and defined functions (check the [relevant chapter](./funcs-classes.md)). +Note that BraneScript uses the same syntax for calling imported functions (see the [previous chapter](./hello-world.md) with the `hello_world()`-function), builtin functions (think `println()`; see [below](#builtin-functions)) and defined functions (check the [relevant chapter](./funcs-classes.md)). To be complete, you can import all of the functions within a package using the import-statement: ```bscript import ; ``` -You've already seen examples of this in the [previous chapter](./workflow.md). +You've already seen examples of this in the [previous chapter](./hello-world.md). ## Control flow @@ -336,4 +336,4 @@ If you have the idea you understand these basic constructs a little, congratulat In the [next chapter](./funcs-classes.md), we examine how to define functions and classes and how to use the latter. Then, in the [chapter after that](./data-results.md), we examine BraneScript's builtin `Data`-class, which is integral to writing useful workflows. Finally, in the [last chapter](./advanced.md) of the BraneScript-part, we discuss some of the finer details of BraneScript as a language. -Separate from these introductory chapters, there is also the complete and more formal overview of the language in the [BraneScript documentation](../../branescript/introduction.md). Those chapters should cover all of its details, and function as useful reference material once you've grasped the basics. +Separate from these introductory chapters, there is also the complete and more formal overview of the language in the [BraneScript documentation]({{ specification_root }}/appendix/languages/bscript/introduction.html). Those chapters should cover all of its details, and function as useful reference material once you've grasped the basics. diff --git a/src/branescript/hello-world.md b/src/branescript/hello-world.md index 0da42d3..16a4769 100644 --- a/src/branescript/hello-world.md +++ b/src/branescript/hello-world.md @@ -15,7 +15,7 @@ Next, it is good practise to write a header comment to explain what a file does. // A BraneScript workflow for printing "Hello, world!" to the screen. ``` -Next, we have to tell the Brane system which packages we want to use in our workflow. To do so, we will use the [`import`](../../branescript/statements.md#imports)-statement. This statement takes the identifier if the package, followed by a semicolon (`;`). +Next, we have to tell the Brane system which packages we want to use in our workflow. To do so, we will use the [`import`]({{ specification_root }}/appendix/languages/bscript/features.html#import-statements)-statement. This statement takes the identifier if the package, followed by a semicolon (`;`). > info Note that all Brane statements end with a semicolon `;`. If you forget it, you may encounter weird syntax errors; so if you don't know what the error means but it's a syntax error, you should first check for proper usage of the semicolons. @@ -25,13 +25,13 @@ We want to import the `hello_world` package, so we add: import hello_world; ``` -This will import _all_ of the package's functions into the global namespace. Be aware of this, since this may lead to naming conflicts. See the [advanced workflows](./advanced-workflows.md#scoping)-chapter for ways of dealing with this. +This will import _all_ of the package's functions into the global namespace. Be aware of this, since this may lead to naming conflicts. See the [advanced workflows](./advanced.md#scoping)-chapter for ways of dealing with this. -In our case, this imports only one function: the `hello_world()` function. As you can read in the [package's README](https://github.com/epi-project/brane-std/tree/main/hello_world), this function takes no arguments, but returns a string who's value is: `Hello, world!`. +In our case, this imports only one function: the `hello_world()` function. As you can read in the [package's README](https://github.com/braneframework/brane-std/tree/main/hello_world), this function takes no arguments, but returns a string who's value is: `Hello, world!`. > info If you do not want to go to the internet to find out what a package does, you can also use the `inspect`-subcommand of the `brane`-executable: > ```bash -> brane inspect hello_world +> brane package inspect hello_world > ``` > which will print something like: > Details about the 'hello_world' package. @@ -52,7 +52,7 @@ However, running the file like this will probably not work. Remember that the pa // (as you would in other languages) println(hello_world()); ``` -See the [BraneScript documentation](../../branescript/builtins.md) for a full overview of all supported builtins. +See the [BraneScript documentation](TODO) for a full overview of all supported builtins. We now have a workflow that should print `Hello, world!` when we run it, which is what we set out to do! @@ -74,7 +74,7 @@ Be sure to save it somewhere where you can find it. Remember, we will refer to i ## Running a workflow -After you have written a workflow file, you can run it using the `brane` executable. Thus, make sure you have it installed and available in your PATH (see the [installation](../installation.md) chapter). +After you have written a workflow file, you can run it using the `brane` executable. Thus, make sure you have it installed and available in your PATH (see the [installation](../scientists/installation.md) chapter). There are two modes of running a workflow: you can run it locally, in which all tasks are executed on your own machine and using the packages that are available locally. Alternatively, you can also run it on a remote instance, in which the tasks are executed on domains and nodes within that instance, using packages available only in that instance. @@ -83,13 +83,12 @@ Typically, you test your workflow locally first to make sure that it works and c To run it locally, you first have to make sure you have all the packages available locally. For us, this is the `hello_world` package. You can check whether you have it by running `brane list`, and then install it if you don't by downloading it from GitHub: ```bash -brane import epi-project/brane-std hello_world +brane package import braneframework/brane-std hello_world ``` -For more details on this, see the [previous chapter](../packages.md). -With the packages in place, you can then use the `brane run`-command to run the file we have just created: +With the packages in place, you can then use the `brane workflow run`-command to run the file we have just created: ```bash -brane run hello_world.bs +brane workflow run hello_world.bs ``` (Replace `hello_world.bs` with the path to the file you have created) @@ -104,17 +103,17 @@ If your workflow failed, Brane will try to offer you as much help as it can. Mak ### Remote execution The procedure for executing a workflow on a remote instance is very comparable to running a workflow locally. -The first step is to make sure that the instance has all the packages you need. Use a combination of `brane search` and `brane push` to achieve this (see the [previous chapter](../packages.md) for more information). +The first step is to make sure that the instance has all the packages you need. Use a combination of `brane search` and `brane push` to achieve this. Then, to execute your workflow, you can do the same, but now specify the `--remote` flag to use the instance currently selected: ```bash -brane run --remote ... +brane workflow run --remote ... ``` Thus, to run our workflow on the remote instance we are currently loggin-in to, we would use to the following command: ```bash # We assume your already executed 'brane instance add' -brane run --remote hello_world.bs +brane workflow run --remote hello_world.bs ``` If your packages are in order, this should produce the same result as when executing the workflow locally. @@ -123,13 +122,13 @@ If your packages are in order, this should produce the same result as when execu ## The REPL As an alternative to writing an entire file and running that, you can also use the Brane Read-Eval-Print Loop (REPL). This is an interactive environment that you can use to provide workflows in a segmented way, typically providing one statement at a time and seeing the result immediately. -> warning The REPL works in most cases, but it is known to be buggy for some design patterns (see subsequent chapters). If you run into an issue where something works in a file but not in a REPL, you can typically solve it by writing the separate statements in a single line. Please also let us know by [raising an issue](https://github.com/epi-project/brane/issues). +> warning The REPL works in most cases, but it is known to be buggy for some design patterns (see subsequent chapters). If you run into an issue where something works in a file but not in a REPL, you can typically solve it by writing the separate statements in a single line. Please also let us know by [raising an issue](https://github.com/BraneFramework/brane/issues). Because our workflow is so short, we will re-do it in the REPL. First, open it by running: ```bash -brane repl +brane workflow repl ``` This should welcome you with the following: @@ -149,9 +148,9 @@ which should produce: Which is the same result as with the separate file, instead that we've now interleaved writing and executing the workflow. -You can also use the REPL in a remote scenario, by providing the `--remote` option when running it, similar to `brane run`: +You can also use the REPL in a remote scenario, by providing the `--remote` option when running it, similar to `brane workflow run`: ```bash -brane repl --remote +brane workflow repl --remote ``` Every command executed in this REPL is executed on the specified instance. @@ -159,4 +158,4 @@ Every command executed in this REPL is executed on the specified instance. ## Next -In the [next chapter](./workflows-data.md), we will treat datasets and intermediate results, which are an essential component to writing workflows. If you are already familiar with those, you can also check the [subsequent chapter](./advanced-workflows.md), which introduces the finer concepts of workflow writing. Alternatively, you can also checkout the full [BraneScript documentation](../branescript/introduction.md). +In an [upcoming chapter](./data-results.md), we will treat datasets and intermediate results, which are an essential component to writing workflows. If you are already familiar with those, you can also check the [subsequent chapter](./advanced.md), which introduces the finer concepts of workflow writing. Alternatively, you can also checkout the full [BraneScript documentation](../branescript/introduction.md). diff --git a/src/branescript/introduction.md b/src/branescript/introduction.md index ffefbaa..b67b232 100644 --- a/src/branescript/introduction.md +++ b/src/branescript/introduction.md @@ -25,4 +25,4 @@ In the [first chapter](./hello-world.md), we will write a simple "Hello, world!" ## Nexts You can start this series by reading the [next chapter](TODO), which will set you on your journey. It is recommended to follow the chapters in-order if it is your first time reading about BraneScript, but you can also jump between them using the sidebar on the left. -Alternatively, if you are looking for more technical details on how the BraneScript language is specified, we recommend you to inspect the [specifications](/specification/branescript/introduction.md) of the language in the [Brane: A Specification](/specification) book. +Alternatively, if you are looking for more technical details on how the BraneScript language is specified, we recommend you to inspect the [specifications]({{ specification_root }}/appendix/languages/bscript/introduction.html) of the language in the [Brane: A Specification]({{ specification_root }}) book. diff --git a/src/branescript/workflows-data.md b/src/branescript/workflows-data.md index 89fc046..f5a9fd8 100644 --- a/src/branescript/workflows-data.md +++ b/src/branescript/workflows-data.md @@ -1,5 +1,5 @@ # Workflows and Data -In the [previous chapter](./workflow.md), we've discussed writing the simplest workflow possible in BraneScript. In this chapter, we will build on this, and examine the concepts of _data_ and _intermediate results_. +In the [previous chapter](./hello-world.md), we've discussed writing the simplest workflow possible in BraneScript. In this chapter, we will build on this, and examine the concepts of _data_ and _intermediate results_. We will start by introducing the concepts of data and intermediate results as far as Brane is concerned. Then, we will write a second workflow in this series to use these concepts in practise. Finally, we will show you how to create a local dataset and then run your workflow. @@ -23,7 +23,7 @@ Put differently, a dataset is something that can serve as the input to your work ## Using Data in a Workflow In this section, we will use the concept of Data in a workflow to see how one can use it in practise. -For this tutorial, we will write a workflow that prints the contents of a specific dataset and then creates a copy of it. To do so, we will use the [cat](https://github.com/epi-project/brane-std/tree/main/cat) and [copy_result](https://github.com/epi-project/brane-std/tree/main/copy_result) packages from the Brane standard library. Moreover, for now we will assume that there is some dataset with the identifier `colours` that we are interested in printing and copying. +For this tutorial, we will write a workflow that prints the contents of a specific dataset and then creates a copy of it. To do so, we will use the [cat](https://github.com/braneframework/brane-std/tree/main/cat) and [copy_result](https://github.com/braneframework/brane-std/tree/main/copy_result) packages from the Brane standard library. Moreover, for now we will assume that there is some dataset with the identifier `colours` that we are interested in printing and copying. To begin, create a second workflow file, which we will call `data.bs`. Open it with your favourite editor, and start by adding the import for the packages: ```bscript @@ -32,7 +32,7 @@ import copy_result; // Provides 'copy_result()' ``` Next, we will create a _Dataset reference_. This is what refers to a specific dataset, so that Brane knows what we are talking about. Datasets are referenced by some identifier, and are assumed to be unique within a single instance. -To create one, we will use the builtin `Data`-[class](../../branescript/statements.md#classes). It has only one field, `name`, which is the identifier of the dataset to use. We will create it as follows: +To create one, we will use the builtin `Data`-[class]({{ specification_root }}/branescript/statements.md#classes). It has only one field, `name`, which is the identifier of the dataset to use. We will create it as follows: ```bscript // ... @@ -40,7 +40,7 @@ new Data{ name := "colours" }; ``` This is the generic BraneScript syntax for instantiating a class with a single field. Because `Data` is a builtin, however, Brane will treat it as a special value. -Note, however, that we currently do nothing with the created data reference; it is created and immediately dropped. To prevent this, we will store it in a [variable](../../branescript/statements.md#variable-declarations): +Note, however, that we currently do nothing with the created data reference; it is created and immediately dropped. To prevent this, we will store it in a [variable]({{ specification_root }}/branescript/statements.md#variable-declarations): ```bscript // ... @@ -71,7 +71,7 @@ You may note that the `cat()`-function actually takes two parameters: a data ref > info In the future, though, we hope to introduce some kind of _Data type system_ that can aid in dealing with this. -For the `cat`-function specifically, this extra argument defines which file you want to print in the dataset. Because our dataset will consist of a single file, we pass it `"-"` which has this meaning (see its [documentation](https://github.com/epi-project/brane-std/tree/main/cat)). +For the `cat`-function specifically, this extra argument defines which file you want to print in the dataset. Because our dataset will consist of a single file, we pass it `"-"` which has this meaning (see its [documentation](https://github.com/braneframework/brane-std/tree/main/cat)). Our workflow is now able to print a specific dataset. We will now use the same data reference to copy it to a new one, for which we will use the `copy_result()` function. @@ -92,7 +92,7 @@ For completeness, we can show that the copied dataset is the same as the origina // Add this below the copy println(cat(data_copy, "contents")); ``` -Note that we now have to specify `"contents"` instead of `"-"`. To see why, we refer you to the documentation of the [cat](https://github.com/epi-project/brane-std/tree/main/cat)-package. +Note that we now have to specify `"contents"` instead of `"-"`. To see why, we refer you to the documentation of the [cat](https://github.com/braneframework/brane-std/tree/main/cat)-package. The only thing left to do is to commit the result returned by the function to make it a persistent dataset. To do so, we use the `commit_result`-builtin: ```bscript @@ -125,7 +125,7 @@ commit_result("colours_copy", data_copy); ## Running a Workflow with Data -Running a workflow with Data goes exactly the same as running a workflow without. Make sure that your local machine or the remote instance has the packages available it needs to, and then run your file using the `brane run`-command (see the [previous chapter](./workflow.md#running-a-workflow) for more information). +Running a workflow with Data goes exactly the same as running a workflow without. Make sure that your local machine or the remote instance has the packages available it needs to, and then run your file using the `brane workflow run`-command (see the [previous chapter](./hello-world.md#running-a-workflow) for more information). However, there is one extra concern that comes into play when running a workflow with data; and that is that the dataset has to be available where you are running it. @@ -202,6 +202,6 @@ you should now see both the `colours` and `colours_copy` datasets! ## Next -Now that you are able to run package functions and work with data, you have the most elementary parts of writing workflows under your belt. A good next step is to examine the [BraneScript documentation](../../branescript/introduction.md) to learn all the features of the language, such as if-statements, for-loops or parallel-statements. +Now that you are able to run package functions and work with data, you have the most elementary parts of writing workflows under your belt. A good next step is to examine the [BraneScript documentation]({{ specification_root }}/branescript/introduction.md) to learn all the features of the language, such as if-statements, for-loops or parallel-statements. Alternatively, you can also go the [next chapter](./advanced-workflows.md) in this series that will deal with some pretty typical patterns and useful concepts in Brane. It assumes that you are either already famliliar with basic control flow in BraneScript (ifs, fors, whiles) or that you are at least able to recognize them. diff --git a/src/config/admins/backend.md b/src/config/admins/backend.md index c8f838a..219b4aa 100644 --- a/src/config/admins/backend.md +++ b/src/config/admins/backend.md @@ -1,5 +1,5 @@ # The backend file -_source [`BackendFile`](/docs/brane_cfg/backend/struct.BackendFile.html) in [`brane_cfg/backend.rs`](/docs/src/brane_cfg/backend.rs.html)._ +_source [`BackendFile`]({{ brane_docs_root }}/brane_cfg/backend/struct.BackendFile.html) in [`brane_cfg/backend.rs`]({{ brane_docs_root }}/src/brane_cfg/backend.rs.html)._ The backend file, or more commonly referenced as the `backend.yml` file, is a worker node configuration file that describes how to connect to the container execution backend. Its location is defined by the [`node.yml`](./node.md) file. diff --git a/src/config/admins/infra.md b/src/config/admins/infra.md index 1d1a90f..3813f89 100644 --- a/src/config/admins/infra.md +++ b/src/config/admins/infra.md @@ -1,5 +1,5 @@ # The infrastructure file -_source [`InfraFile`](/docs/brane_cfg/infra/struct.InfraFile.html) in [`brane_cfg/infra.rs`](/docs/src/brane_cfg/infra.rs.html)._ +_source [`InfraFile`]({{ brane_docs_root }}/brane_cfg/infra/struct.InfraFile.html) in [`brane_cfg/infra.rs`]({{ brane_docs_root }}/src/brane_cfg/infra.rs.html)._ The infrastructure file, or more commonly referenced as the `infra.yml` file, is a control node configuration file that is used to define the worker nodes part of a particular BRANE instance. Its location is defined by the [`node.yml`](./node.md) file. diff --git a/src/config/admins/node.md b/src/config/admins/node.md index bd7543d..a33338e 100644 --- a/src/config/admins/node.md +++ b/src/config/admins/node.md @@ -1,5 +1,5 @@ # The node file -_source [`NodeConfig`](/docs/brane_cfg/node/struct.NodeConfig.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`NodeConfig`]({{ brane_docs_root }}/brane_cfg/node/struct.NodeConfig.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ The node file, or more commonly referenced as the `node.yml` file, is a central-, worker- and proxy node configuration file that describes the environment in which the node should run. Most notably, it defines the type of node, where any BRANE software (`branectl`, services) may find other configuration files and which ports to use for all of the services. @@ -30,7 +30,7 @@ node: ... Because there are quite a lot of nested fields, we will discuss the various variants of the `node`-map in subsequent sections. ### Central nodes -_source [`CentralConfig`](/docs/brane_cfg/node/struct.CentralConfig.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`CentralConfig`]({{ brane_docs_root }}/brane_cfg/node/struct.CentralConfig.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ The first variant of the `node`-map is the `!central` variant, which defines a central node. There are two fields in this map: - `paths`: A map that defines all paths relevant to the central node. Specifically, it maps a string identifier to a string path. The following identifiers are defined: @@ -81,7 +81,7 @@ node: !central ``` ### Worker nodes -_source [`WorkerConfig`](/docs/brane_cfg/node/struct.WorkerConfig.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`WorkerConfig`]({{ brane_docs_root }}/brane_cfg/node/struct.WorkerConfig.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ The second variant of the `node`-map is the `!worker` variant, which defines a worker node. There are three fields in this map: - `name` _(or `location_id`)_: A string that contains the identifier used to recognize this worker node throughout the system. @@ -90,7 +90,7 @@ The second variant of the `node`-map is the `!worker` variant, which defines a w - `certs`: The path to the directory with certificate authority files for the worker nodes in the instance. See the [chapter on installing a control node](../../system-admins/installation/control-node.md#adding-certificates) for more information. - `packages`: The path to the directory where uploaded packages will be stored. This should be a persistent directory, or at the very least exactly as persistent as the storage of the instance's Scylla database. - `backend`: The path to the [`backend.yml`](./backend.md) configuration file. - - `policy_database` _(or `policy_db`)_: The path to the [`policies.db`] file that is the persistent storage for the policy's of the worker's `brane-chk` service. + - `policy_database` _(or `policy_db`)_: The path to the `policies.db` file that is the persistent storage for the policy's of the worker's `brane-chk` service. - `policy_deliberation_secret`: The path to a [JWK](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) that defines the secret used for `brane-chk`'s deliberation API. - `policy_expert_secret`: The path to a [JWK](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) that defines the secret used for `brane-chk`'s policy expert (management) API. - `policy_audit_log`: An **optional** path to a file to which the `brane-chk` service writes it audit log. If omitted, the audit log only exists within the `brane-chk` container. @@ -142,7 +142,7 @@ node: !worker ### Proxy nodes -_source [`ProxyConfig`](/docs/brane_cfg/node/struct.ProxyConfig.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`ProxyConfig`]({{ brane_docs_root }}/brane_cfg/node/struct.ProxyConfig.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ The third variant of the `node`-map is the `!proxy` variant, which defines a proxy node. There are two fields in this map: - `paths`: A map that defines all paths relevant to the proxy node. Specifically, it maps a string identifier to a string path. The following identifiers are defined: @@ -174,7 +174,7 @@ node: !worker Through the various `node` variants, a few types of service maps appear. In this section, we will define their layouts. ### Private services -_source [`PrivateService`](/docs/brane_cfg/node/struct.PrivateService.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`PrivateService`]({{ brane_docs_root }}/brane_cfg/node/struct.PrivateService.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ A private service represents a service that is only accessible for other BRANE services, but not from outside of the Docker network. A few examples of such services are `aux-scylla` or `aux-kafka`. @@ -202,7 +202,7 @@ node: !central > warning Note that providing `127.0.0.1` as a bind address will not work, since the `127.0.0.1` refers to the _container_ and not the host. Thus, using that address will make the service inaccessible for everyone. ### Public services -_source [`PublicService`](/docs/brane_cfg/node/struct.PublicService.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`PublicService`]({{ brane_docs_root }}/brane_cfg/node/struct.PublicService.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ A public service represents a service that is accessible for other BRANE services and from outside of the Docker network. A few examples of such services are `brane-drv` or `brane-reg`. @@ -233,7 +233,7 @@ node: !central > warning Note that providing `127.0.0.1` as a bind address will not work, since the `127.0.0.1` refers to the _container_ and not the host. Thus, using that address will make the service inaccessible for everyone. ### Variable services -_source [`PrivateOrExternalService`](/docs/brane_cfg/node/enum.PrivateOrExternalService.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._ +_source [`PrivateOrExternalService`]({{ brane_docs_root }}/brane_cfg/node/enum.PrivateOrExternalService.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._ A variable service is one where a choice can be made between two different kinds of services. Specifically, one can choose to either host a [private service](#private-services), or something called an external service, which defines a service hosted on another node or machine. This is currently only used by the `brane-prx` service in `central` or `worker` nodes, to support optionally outsourcing the proxy service to a dedicated node. @@ -242,7 +242,7 @@ Subsequently, there are two variants of this type of service: - `!external`: Defines an externally running service. It has one field only: - `address`: A string with the address where all the other services on this node should send their traffic to. - (_source The external map variant is defined as [`ExternalService`](/docs/brane_cfg/node/struct.ExternalService.html) in [`brane_cfg/node.rs`](/docs/src/brane_cfg/node.rs.html)._) + (_source The external map variant is defined as [`ExternalService`]({{ brane_docs_root }}/brane_cfg/node/struct.ExternalService.html) in [`brane_cfg/node.rs`]({{ brane_docs_root }}/src/brane_cfg/node.rs.html)._) A few examples of variable services: ```yaml diff --git a/src/config/admins/proxy.md b/src/config/admins/proxy.md index 37e04cc..ad0e13f 100644 --- a/src/config/admins/proxy.md +++ b/src/config/admins/proxy.md @@ -1,7 +1,7 @@ # The proxy file -_source [`ProxyConfig`](/docs/brane_cfg/proxy/struct.ProxyConfig.html) in [`brane_cfg/proxy.rs`](/docs/src/brane_cfg/proxy.rs.html)._ +_source [`ProxyConfig`]({{ brane_docs_root }}/brane_cfg/proxy/struct.ProxyConfig.html) in [`brane_cfg/proxy.rs`]({{ brane_docs_root }}/src/brane_cfg/proxy.rs.html)._ -The proxy file, or more commonly referenced as the `proxy.yml` file, is a central-, worker- and proxy node configuration file that describes how to deal with outgoing connections out of the node. For more information, see the documentation for the [`brane-prx`](/docs/brane_prx/index.html) service. Its location is defined by the [`node.yml`](./node.md) file. +The proxy file, or more commonly referenced as the `proxy.yml` file, is a central-, worker- and proxy node configuration file that describes how to deal with outgoing connections out of the node. For more information, see the documentation for the [`brane-prx`]({{ brane_docs_root }}/brane_prx/index.html) service. Its location is defined by the [`node.yml`](./node.md) file. The [`branectl`](TODO) tool can generate this file for you, using the [`branectl generate proxy`](TODO) subcommand. See the [chapter on installing a control node](../../system-admins/installation/control-node.md) for a realistic example. diff --git a/src/config/users/container.md b/src/config/users/container.md index 83bfa28..319d698 100644 --- a/src/config/users/container.md +++ b/src/config/users/container.md @@ -1,5 +1,5 @@ # The container file -_source [`ContainerInfo`](/docs/specifications/container/struct.ContainerInfo.html) in [`specifications/data.rs`](/docs/src/specifications/container.rs.html)._ +_source [`ContainerInfo`]({{ brane_docs_root }}/specifications/container/struct.ContainerInfo.html) in [`specifications/data.rs`]({{ brane_docs_root }}/src/specifications/container.rs.html)._ The container file, or more commonly referenced as the `container.yml` file, is a user-facing configuration file that describes the metadata of a BRANE package. Most notably, it defines how the package's container may be built by stating which files to include, how to run the code, and which BRANE functions are contained within. Additionally, it can also carry data such as the owner of the package or any hardware requirements the package has. @@ -197,7 +197,7 @@ For examples, see the [Functions & Classes section](#functions--classes). ## Data types -_source [`DataType`](/docs/brane_ast/data_type/enum.DataType.html) in [`brane_ast/data_type.rs`](/docs/src/brane_ast/data_type.rs.html)._ +_source [`DataType`]({{ brane_docs_root }}/brane_ast/data_type/enum.DataType.html) in [`brane_ast/data_type.rs`]({{ brane_docs_root }}/src/brane_ast/data_type.rs.html)._ BRANE abstracts the various workflow languages it accepts as input to a common representation. This representation is what is referred to in the `container.yml` file when we are talking about data types, and so these data types are language-agnostic. diff --git a/src/config/users/data.md b/src/config/users/data.md index fb2fc4d..4c6cf51 100644 --- a/src/config/users/data.md +++ b/src/config/users/data.md @@ -1,5 +1,5 @@ # The data file -_source [`AssetInfo`](/docs/specifications/data/struct.AssetInfo.html) in [`specifications/data.rs`](/docs/src/specifications/data.rs.html)._ +_source [`AssetInfo`]({{ brane_docs_root }}/specifications/data/struct.AssetInfo.html) in [`specifications/data.rs`]({{ brane_docs_root }}/src/specifications/data.rs.html)._ The data file, or more commonly referenced as the `data.yml` file, is a user-facing configuration file that describes the metadata of a BRANE dataset. Most notably, it defines how the dataset can be referenced in BraneScript (i.e., its identifier) and describes which files or other resources actually make up the dataset. diff --git a/src/overview.md b/src/overview.md index 5deb60f..da48ef4 100644 --- a/src/overview.md +++ b/src/overview.md @@ -1,7 +1,7 @@ # Overview In this chapter, we will provide a brief overview of what the framework is, how it is build and what kind of features it supports. -It is not, however, a complete, technical description of its implementation; for that, we recommend you read our [other book](/specification). +It is not, however, a complete, technical description of its implementation; for that, we recommend you read our [other book]({{ specification_root }}). ## Brane: Programmable Orchestration of Applications and Networking diff --git a/src/packages/ecu.md b/src/packages/ecu.md new file mode 100644 index 0000000..a6c7081 --- /dev/null +++ b/src/packages/ecu.md @@ -0,0 +1,2 @@ +# Code execution unit packages +> drawing Documentation for code execution unit packages will be added soon. diff --git a/src/policy-experts/installation.md b/src/policy-experts/installation.md index 05c075e..fdc2f7f 100644 --- a/src/policy-experts/installation.md +++ b/src/policy-experts/installation.md @@ -3,7 +3,7 @@ As a policy expert, you will write policies and then manage them in the node's ` To do the former, you need a development environment for the reasoner backend you will be using. See the [Installing the eFLINT Interpreter](#installing-the-eflint-interpreter)-section to find out how to setup a local environment for eFLINT. -For the latter, you can choose between the [Policy Reasoner GUI](https://github.com/epi-project/policy-reasoner-gui), a visual interface, or `branectl`, a command-line interface. Installing either of these is explained in [Installing management tools](#installing-management-tools)-section. +For the latter, you can choose between the [Policy Reasoner GUI](https://github.com/braneframework/policy-reasoner-gui), a visual interface, or `branectl`, a command-line interface. Installing either of these is explained in [Installing management tools](#installing-management-tools)-section. ## Installing the eFLINT Interpreter @@ -34,22 +34,22 @@ eflint-repl Use `eflint-repl --help` to see more options, or type `:help` when you are in the REPL. -Also consider adding syntax highlighting for your favourite code editor. There are syntax highlighters for [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=Lut99.eflint-syntax-highlighting) and [Sublime](https://gitlab.com/eflint/haskell-implementation/-/blob/master/eflint.sublime-syntax?ref_type=heads). +Also consider adding syntax highlighting for your favourite code editor. There are syntax highlighters for [Visual Studio Code](https://github.com/Lut99/eflint-syntax-highlighting) and [Sublime](https://gitlab.com/eflint/haskell-implementation/-/blob/master/eflint.sublime-syntax?ref_type=heads). ## Installing management tools To manage the local Brane node, you need to use a tool that can interface with the reasoner and push/pull policies, change the active policy and test drive your changes. Currently, there are two tools available that can do this: -1. The official [Policy Reasoner GUI](https://github.com/epi-project/policy-reasoner-gui), which provides a visual interface; and +1. The official [Policy Reasoner GUI](https://github.com/braneframework/policy-reasoner-gui), which provides a visual interface; and 2. The Brane CTL management tool, which provides a terminal interface. Installing the first is recommended in most cases, except when you're in need of a quick way to manage them (e.g., in scenarios where the system administrator also takes the role of the policy expert) or are more comfortable with terminals in general. ### The Policy Reasoner GUI -The most up-to-date instructions for installing the policy reasoner GUI are described [here](https://github.com/epi-project/policy-reasoner-gui/blob/main/README.md). Below follows a summary for convenience. +The most up-to-date instructions for installing the policy reasoner GUI are described [here](https://github.com/braneframework/policy-reasoner-gui/blob/main/README.md). Below follows a summary for convenience. First, clone the repository to your machine using Git: ```bash -git clone https://github.com/epi-project/policy-reasoner-gui && cd ./policy-reasoner-gui +git clone https://github.com/braneframework/policy-reasoner-gui && cd ./policy-reasoner-gui ``` Then, you can either install the GUI natively or in a Docker container. @@ -73,13 +73,13 @@ to build & run both the client and the client's backend. ### The `branectl` management tool -To install the management tool, you can download the binary from the [repository](https://github.com/epi-project/brane) or compile it from scratch. +To install the management tool, you can download the binary from the [repository](https://github.com/BraneFramework/brane) or compile it from scratch. -To download, you simply go to the [release](https://github.com/epi-project/brane/releases/latest) and download the `branectl` binary of your choice. There are options to download it for Linux ([`branectl-linux-x86_64`](https://github.com/epi-project/brane/releases/latest/download/branectl-linux-x86_64)), Intel Macs ([`branectl-darwin-x86_64`](https://github.com/epi-project/brane/releases/latest/download/branectl-darwin-x86_64)) or M1/M2/M3 Macs ([`branectl-darwin-aarch64`](https://github.com/epi-project/brane/releases/latest/download/branectl-darwin-aarch64)). +To download, you simply go to the [release](https://github.com/BraneFramework/brane/releases/latest) and download the `branectl` binary of your choice. There are options to download it for Linux ([`branectl-linux-x86_64`](https://github.com/BraneFramework/brane/releases/latest/download/branectl-linux-x86_64)), Intel Macs ([`branectl-darwin-x86_64`](https://github.com/BraneFramework/brane/releases/latest/download/branectl-darwin-x86_64)) or M1/M2/M3 Macs ([`branectl-darwin-aarch64`](https://github.com/BraneFramework/brane/releases/latest/download/branectl-darwin-aarch64)). To compile the binary yourself, install [GCC's `gcc` and `g++`](https://gcc.gnu.org/), [CMake](https://cmake.org/) and [Rust](https://rust-lang.org) ([rustup](https://rustup.rs) is usually the easiest) first if you haven't already. Then, clone the repository and run the `make.py` script: ``` -git clone https://github.com/epi-project/brane && cd ./brane +git clone https://github.com/BraneFramework/brane && cd ./brane ./make.py ctl ``` The resulting binary can be found under `target/release/branectl`. diff --git a/src/policy-experts/policy-file.md b/src/policy-experts/policy-file.md index d64f70a..f8fbe17 100644 --- a/src/policy-experts/policy-file.md +++ b/src/policy-experts/policy-file.md @@ -1,6 +1,6 @@ # The Policy File -> warning This page is for the deprecated method of entering policies into the system using a `policies.yml` file. A better method (involving eFLINT) is implemented through the [`policy-reasoner`](https://github.com/epi-project/policy-reasoner) project. +> warning This page is for the deprecated method of entering policies into the system using a `policies.yml` file. A better method (involving eFLINT) is implemented through the [`policy-reasoner`](https://github.com/BraneFramework/policy-reasoner) project. Brane used to read its policies from a so-called _policy file_ (also known as `policies.yml`) which defines a very simplistic set of access-control policies. diff --git a/src/scientists/bscript/introduction.md b/src/scientists/bscript/introduction.md index c535d79..a40d2b5 100644 --- a/src/scientists/bscript/introduction.md +++ b/src/scientists/bscript/introduction.md @@ -5,4 +5,4 @@ In the [first chapter](./highlevel.md), we will discuss what it is that we exact In the [second chapter](./calling-functions.md), we will discuss calling the external functions in BraneScript, which is arguably the most elementary yet useful operation that can be done. Then, in the [third chapter](./variables.md), we will discuss variables, after which we will treat control flows statements in the [fourth chapter](./control-flow.md). Finally, we will discuss the notion of Data in Brane, after which you will have completed you brief BraneScript bootcamp. -Note that this tutorial is not meant to give you a complete overview of BraneScript. Instead, it will teach you the most important concepts for writing most workflows. If you are eager to learn about all of its features, consider checking the [extended tutorial](../../branescript/introduction.md) in the chapters on BraneScript itself, or even consult the [language specification](/specification/branescript/introduction.html) in the [Brane: A Specification](/specification) book. +Note that this tutorial is not meant to give you a complete overview of BraneScript. Instead, it will teach you the most important concepts for writing most workflows. If you are eager to learn about all of its features, consider checking the [extended tutorial]({{ specification_root }}/appendix/languages/bscript/introduction.html) in the chapters on BraneScript itself, or even consult the [language specification]({{ specification_root }}/appendix/languages/bscript/introduction.html) in the [Brane: A Specification]({{ specification_root }}) book. diff --git a/src/scientists/installation.md b/src/scientists/installation.md index 6296818..b7a3862 100644 --- a/src/scientists/installation.md +++ b/src/scientists/installation.md @@ -3,7 +3,7 @@ In this chapter, we will discuss how to install the Brane Command-Line Tool, or If you already have this executable available, you can [skip ahead](./packages.md) to the next chapter instead. If you do not, you should begin with the next chapter. -> info Aside from the `brane` executable, you may make your life easier by installing the Brane JupyterLab environment; check out its [repository](https://github.com/epi-project/brane-ide). +> info Aside from the `brane` executable, you may make your life easier by installing the Brane JupyterLab environment; check out its [repository](https://github.com/braneframework/brane-ide). ## Prerequisites @@ -26,7 +26,7 @@ Before you can write and test workflows on your machine, make sure that you inst ## Downloading the binaries The easiest way to install the `brane`-executable is by downloading it from the project's repository. -Head to https://github.com/epi-project/brane/releases/latest/ to find the latest release. From there, you can download the appropriate `brane` executable by clicking on the desired entry in the `Assets`-list: +Head to https://github.com/BraneFramework/brane/releases/latest/ to find the latest release. From there, you can download the appropriate `brane` executable by clicking on the desired entry in the `Assets`-list: Successfully built version 1.0.0 of container (ECU) package hello_world. @@ -71,7 +71,7 @@ If you see a version number, the installation was successful; but if you see an ## Compiling the binary Instead of downloading the binary and running it, you can also choose to compile the binary yourself. This is usually only necessary if you need a cutting-edge latest, unreleased version, you have an OS or processor architecture for which there is no `brane`-executable readily available or you are actively developing the framework. -To compile the binary, refer to the [compilation instructions](/specification/development/compilation.html) over at the [Brane: A Specification](/specification)-book for instructions. +To compile the binary, refer to the [compilation instructions]({{specification_root}}/development/compilation.html) over at the [Brane: A Specification]({{ specification_root }})-book for instructions. ## Next -If you are able to run the `brane version` command, you have installed your `brane` executable successfully! You can now move to the [next chapter](./instances.md), which contains information on how to connect to remote instances and manage your credentials. After that, continue with the chapter on [package management](./packages.md), or start by writing your first workflow in either [BraneScript](./bscript/introduction.md) or [Bakery](./bakery/introduction.md). +If you are able to run the `brane version` command, you have installed your `brane` executable successfully! You can now move to the [next chapter](./instances.md), which contains information on how to connect to remote instances and manage your credentials. After that, continue with the chapter on [package management](./packages.md), or start by writing your first workflow in [BraneScript](./bscript/introduction.md). diff --git a/src/scientists/packages.md b/src/scientists/packages.md index f0a43f6..232d9dc 100644 --- a/src/scientists/packages.md +++ b/src/scientists/packages.md @@ -23,16 +23,16 @@ The first method to download a package is by downloading it from GitHub using th > info Of course, you can easily download the packages manually from GitHub and then build them as if you wrote the package yourself. See the [chapters for software engineers](../software-engineers/introduction.md) on how to do that. This section focusses on using the more convenient method provided by `brane`. -As an example repository, we will use the [brane-std](https://github.com/epi-project/brane-std) repository. It provides a set of packages that are useful in general scenarios, and so can be thought of as a kind of standard library for Brane. +As an example repository, we will use the [brane-std](https://github.com/braneframework/brane-std) repository. It provides a set of packages that are useful in general scenarios, and so can be thought of as a kind of standard library for Brane. -Before we can install a package from a repository, first we have to find the identifier of the repository. This identifier is written as the GitHub user or organisation name, a slash, and then the name of the repository. Or, more precisely, the identifier is the part of the URL of a repository that comes after `https://github.com/`. For example, for the standard library, which can be found at https://github.com/epi-project/brane-std, the ID would be: +Before we can install a package from a repository, first we have to find the identifier of the repository. This identifier is written as the GitHub user or organisation name, a slash, and then the name of the repository. Or, more precisely, the identifier is the part of the URL of a repository that comes after `https://github.com/`. For example, for the standard library, which can be found at https://github.com/braneframework/brane-std, the ID would be: ``` -epi-project/brane-std +braneframework/brane-std ``` To download a package and install it locally, you can use the following command: ```bash -brane import +brane package import ``` where `` is the identifier of the repository, and `` is the path to the package to download in that repository. Note that you have to refer to the `container.yml` file (or similar) for that package; consult the documentation of the package to find which file to refer to specifically. @@ -40,7 +40,7 @@ where `` is the identifier of the repository, and `` is the path to So, for example, to download the `hello_world` package from the standard library: ```bash -brane import epi-project/brane-std hello_world/container.yml +brane package import braneframework/brane-std hello_world/container.yml ``` Brane will then download the package and install it, making it available for local use. @@ -63,7 +63,7 @@ where `
` is the URL where the instance may be reached. Once logged-in, you can fetch a list of available packages by using: ```bash -brane search +brane package search ``` Which should display something like: @@ -72,7 +72,7 @@ Which should display something like: Then you can use the `brane pull` command to pull one of the available packages: ```bash -brane pull +brane package pull ``` where `` is typically the name of the package. However, if you want to download a specific package version instead of just the latest version, you can also use `:`. @@ -82,9 +82,9 @@ For example, to download the `hello_world` package from an instance that is reac brane instance add some-domain.com --use # Pull the package -brane pull hello_world +brane package pull hello_world # Or, to pull version 1.0.0 specifically: -brane pull hello_world:1.0.0 +brane package pull hello_world:1.0.0 ``` > info Note that you only have to login once, which is then saved and remembered until you manually login to another instance later. @@ -103,7 +103,7 @@ where `
` is the URL where the instance may be reached. Consult the [pre Then, you can find a list of the packages installed locally by running: ```bash -brane list +brane package list ``` which should return something like: @@ -121,9 +121,9 @@ For example, to push the package `hello_world` to an instance that is reachable brane instance add some-domain.com --use # Push the package -brane push hello_world +brane package push hello_world # Or, to push version 1.0.0 specifically: -brane push hello_world:1.0.0 +brane package push hello_world:1.0.0 ``` @@ -139,9 +139,9 @@ where `` is the name of the package. If you want to delete a specific versio For example, to remove the `hello_world` package from the local repository: ```bash -brane remove hello_world +brane package remove hello_world # Or, a specific version: -brane remove hello_world:1.0.0 +brane package remove hello_world:1.0.0 ``` > info Don't worry - Brane will always ask you if you are sure before removing a package. Should you want to consciously skip that, however, you can use the `--force` flag to skip the check: @@ -152,20 +152,20 @@ brane remove hello_world:1.0.0 The same can be done for remote packages, except that you should use `brane unpublish` instead: ```bash -brane unpublish +brane package unpublish ``` ```bash # Don't forget to login first if you haven't already - you are interacting with an instance again brane instance add some-domain.com --use # For hello_world: -brane unpublish hello_world +brane package unpublish hello_world # Or a specific version: -brane unpublish hello_world:1.0.0 +brane package unpublish hello_world:1.0.0 ``` ## Next -Now that you can manage packages, it is finally time to move on to that which you are here to do: write workflows. You can go to the [next chapter](./bscript/workflow.md) for tutorials on doing so with Brane's own language, BraneScript. +Now that you can manage packages, it is finally time to move on to that which you are here to do: write workflows. You can go to the [next chapter](../branescript/hello-world.md) for tutorials on doing so with Brane's own language, BraneScript. However, if you already have a basic idea, you can also skip ahead to further chapters in each language to discuss increasingly advanced concepts. Alternatively, you can also just check the more extensive tutorials on [BraneScript](../branescript/introduction.md) in its own series of chapters. diff --git a/src/software-engineers/base64.md b/src/software-engineers/base64.md index 0e04247..4b7fa5d 100644 --- a/src/software-engineers/base64.md +++ b/src/software-engineers/base64.md @@ -1,9 +1,9 @@ # Package inputs & multiple functions In the [previous chapter](./hello-world.md), you created your first package, and learned how to build and run a function that take no inputs. - +c However, this makes for very boring workflows. Thus, in this chapter, we will extend upon this by creating a container with multiple functions, and where we can pass inputs to those functions. Concretely, we will describe how to implement a _base64_ package, which will contain a function to encode a string and decode a string to and from [Base64](https://en.wikipedia.org/wiki/Base64), respectively. -> info The code used in this tutorial can be found in `examples/doc/base64` of the [repository](https://github.com/epi-project/brane). +> info The code used in this tutorial can be found in `examples/doc/base64` of the [repository](https://github.com/BraneFramework/brane). ## 1. Writing code @@ -403,7 +403,7 @@ actions: type: string ``` -The complete `container.yml` may be found in the [project repository](https://github.com/epi-project/brane) (`examples/doc/base64/container.yml`). +The complete `container.yml` may be found in the [project repository](https://github.com/BraneFramework/brane) (`examples/doc/base64/container.yml`). # 3. Building & Publishing the package @@ -446,8 +446,8 @@ You can refer to the chapters on [writing workflows](TODO) or the documentation ## Next You should now be able to build most functions, congratulations! -In the [next chapter](./data.yml), we will consider a last-but-not-least aspect of building packages: datasets and intermediate results. If you plan to do any serious data processing with Brane, we highly recommend you to check that chapter out. +In the [next chapter](./data.md), we will consider a last-but-not-least aspect of building packages: datasets and intermediate results. If you plan to do any serious data processing with Brane, we highly recommend you to check that chapter out. Otherwise, check the in-depth documentation on the [package system](../packages/introduction.md). It will talk about the different types of packages, how they are implemented and the complete overview of the interface with code and the `container.yml` file. -You can also continue with the chapters for [scientists] to know more about how to write workflows, or check the documentation of [BraneScript](../branescript/introduction.md) and [Bakery](../bakery/introduction.md). +You can also continue with the chapters for scientists to know more about how to write workflows, or check the documentation of [BraneScript](../branescript/introduction.md) and [Bakery](../bakery/introduction.md). diff --git a/src/software-engineers/data.md b/src/software-engineers/data.md index a89a9a3..96706df 100644 --- a/src/software-engineers/data.md +++ b/src/software-engineers/data.md @@ -5,7 +5,7 @@ However, so far, your code will not be very usable to data scientists. That's be In this tutorial, we will cover exactly that: how you can define a (local) dataset and use it in your package. This is illustrated by creating a package that can compute the minimum or maximum of a given file. First, however, we will provide a little background on how datasets are represented, and what's the difference between Brane's concept of _data_ and Brane's concept of _intermediate results_. If you're eager and already know this stuff, you can skip ahead to the [section after the next one](#1-writing-code). -> info The code used in this tutorial can be found in `examples/doc/minmax` of the [repository](https://github.com/epi-project/brane). +> info The code used in this tutorial can be found in `examples/doc/minmax` of the [repository](https://github.com/braneframework/brane). ## 0. Background: Variables & Data @@ -31,7 +31,7 @@ For you, a software engineer, the important thing to know is that functions can ## 1. Creating a dataset This time, before we will write code, we first have to create the dataset that we will be using. -Note, though, that creating datasets is typically the role of the [system administrator](../system-admins/data.md) of a given domain that offers the dataset. In other words, you will typically only use datasets already available on the domains in a Brane instance. +Note, though, that creating datasets is typically the role of the [system administrator](TODO) of a given domain that offers the dataset. In other words, you will typically only use datasets already available on the domains in a Brane instance. However, it can still be useful to create a dataset that is _locally_ available only - typically for testing purposes. That's what we will do here. @@ -269,7 +269,7 @@ Similarly, calling your package from the terminal will require you to explicitly // TODO -You should also see that executing your package call will not be very exciting, since all it does is produce a new dataset. This is alright, since subsequent package calls in a workflows are still able to use it; however, for demonstration purposes, you can try to download the [cat package](https://github.com/epi-project/brane-std/cat) to inspect it: +You should also see that executing your package call will not be very exciting, since all it does is produce a new dataset. This is alright, since subsequent package calls in a workflows are still able to use it; however, for demonstration purposes, you can try to download the [cat package](https://github.com/braneframework/brane-std/tree/main/cat) to inspect it: // TODO diff --git a/src/software-engineers/filesystem.md b/src/software-engineers/filesystem.md index bb49b07..2c36929 100644 --- a/src/software-engineers/filesystem.md +++ b/src/software-engineers/filesystem.md @@ -191,6 +191,6 @@ You are now able to use the shared filesystem! A common use-case for such a filesystem is to download or extract data from within a package to it so that other packages may use it. For example, if I have a `data.csv` and embed that in a package (using the `files`-section in the `container.yml`), I can then copy it to the shared filesystem using some `extract()` package function. Then, other packages can easily use this dataset without having to re-download it again or having to pass it as huge strings in BraneScript. -Another common use-case is in combination with the [JupyterLab IDE](https://github.com/epi-project/brane-ide). Your Brane packages can write results or even plots to the shared `/data` folder, which the IDE has also mounted. That way, you can easily visualise the images produced by Brane in the notebook, by loading them from the filesystem. +Another common use-case is in combination with the [JupyterLab IDE](https://github.com/braneframework/brane-ide). Your Brane packages can write results or even plots to the shared `/data` folder, which the IDE has also mounted. That way, you can easily visualise the images produced by Brane in the notebook, by loading them from the filesystem. If you're interested in other types of Brane packages, you can follow the [next tutorial](./github.md). Otherwise, you can refer to the [Scientists](../scientists/introduction.md)-chapters to learn how to write workflows for Brane, or go to the [BraneScript](../branescript/introduction.md) documentation to learn more about Brane's DSL. diff --git a/src/software-engineers/hello-world.md b/src/software-engineers/hello-world.md index 188e914..2901c3d 100644 --- a/src/software-engineers/hello-world.md +++ b/src/software-engineers/hello-world.md @@ -3,7 +3,7 @@ In this chapter, we will guide you through creating the simplest and most basic This tutorial assumes that you have experience with programming. In particular, it's useful to known about [standard streams](https://en.wikipedia.org/wiki/Standard_streams) and [environment variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa). -> info The code used in this tutorial can be found in `examples/doc/hello-world` of the [repository](https://github.com/epi-project/brane). +> info The code used in this tutorial can be found in `examples/doc/hello-world` of the [repository](https://github.com/BraneFramework/brane). ## 1. Writing the code @@ -159,7 +159,7 @@ If everything went alright, you should see the `Hello, world!` message if you hi Hello, world! -This confirms that your package is working and Brane can interact with it! If it doesn't, you'll see an error that hopefully allows you to debug your package. You can check the [troubleshooting](./troubleshooting.md) chapter with some general tips on how to debug any such errors. +This confirms that your package is working and Brane can interact with it! If it doesn't, you'll see an error that hopefully allows you to debug your package. You can check the [troubleshooting](TODO) chapter with some general tips on how to debug any such errors. If everything checks out, you are now ready to push your package to a Brane instance. diff --git a/src/software-engineers/installation.md b/src/software-engineers/installation.md index 7d3faa7..dceb23a 100644 --- a/src/software-engineers/installation.md +++ b/src/software-engineers/installation.md @@ -39,13 +39,13 @@ You can either download the binary directly from the repository, or build the to To download the Brane CLI binary, use the following commands: ```bash # For Linux -sudo wget -O /usr/local/bin/brane https://github.com/epi-project/brane/releases/latest/download/brane-linux-x86_64 +sudo wget -O /usr/local/bin/brane https://github.com/BraneFramework/brane/releases/latest/download/brane-linux-x86_64 # For macOS (Intel) -sudo wget -O /usr/local/bin/brane https://github.com/epi-project/brane/releases/latest/download/brane-darwin-x86_64 +sudo wget -O /usr/local/bin/brane https://github.com/BraneFramework/brane/releases/latest/download/brane-darwin-x86_64 # For macOS (M1/M2) -sudo wget -O /usr/local/bin/brane https://github.com/epi-project/brane/releases/latest/download/brane-darwin-aarch64 +sudo wget -O /usr/local/bin/brane https://github.com/BraneFramework/brane/releases/latest/download/brane-darwin-aarch64 ``` These commands download the latest Brane CLI binary for your OS, and store them in `/usr/local/bin` (which is why the command requires `sudo`). You may install the binary anywhere you like, but don't forget to add the binary to your PATH if you choose a location that is not part of it already. @@ -53,7 +53,7 @@ These commands download the latest Brane CLI binary for your OS, and store them ### Compiling the binary You may also compile the binary from source if you need the cutting-edge latest version or are running a system that doesn't have any default binary available. -To compile the binary, refer to the [compilation instructions](/specification/development/compilation.html) over at the [Brane: A Specification](/specification)-book for instructions. +To compile the binary, refer to the [compilation instructions]({{ specification_root }}/development/compilation.html) over at the [Brane: A Specification]({{ specification_root }})-book for instructions. ## Next diff --git a/src/software-engineers/introduction.md b/src/software-engineers/introduction.md index f5ebb0b..139bb6d 100644 --- a/src/software-engineers/introduction.md +++ b/src/software-engineers/introduction.md @@ -13,7 +13,7 @@ That means that the bulk of the work will be done in these external function cal Technically, these packages are implemented as containers, which means that they might be written in any language (as long as they adhere to the protocol Brane uses to communicate with packages) and will ship together with all required dependencies. -As a consequence, this means that Brane package calls are, in principle, always completely self-contained. After execution, the container is destroyed, removing any work that the package has done. The only way to retrieve results is by either sending them back to the workflow-space directly as a return value (which can contain limited data), or by returning so-called _datasets_ or _intermediate results_ (see the [scientist chapters](../scientists/data.md) for more background information, or the software engineer's [data chapter](./data.md) for practical usage). +As a consequence, this means that Brane package calls are, in principle, always completely self-contained. After execution, the container is destroyed, removing any work that the package has done. The only way to retrieve results is by either sending them back to the workflow-space directly as a return value (which can contain limited data), or by returning so-called _datasets_ or _intermediate results_ (see the [scientist chapters](../scientists/bscript/datasets.md) for more background information, or the software engineer's [data chapter](./data.md) for practical usage). ## Next diff --git a/src/system-admins/backends/introduction.md b/src/system-admins/backends/introduction.md index e6001ad..1a90727 100644 --- a/src/system-admins/backends/introduction.md +++ b/src/system-admins/backends/introduction.md @@ -2,7 +2,7 @@ In principle, Brane is agnostic to the type of backend that actually runs the containers scheduled by Brane and accepted by domains. There are two obvious choices that are currently implemented: [Docker](https://docker.com), which runs containers on a single machine (usually the machine where the Brane worker is running); and [Kubernetes](https://kubernetes.io), which runs containers on a distributed cluster. -> warning Sadly, the Kubernetes backend has been broken since Brane version 1.0.0. A fix is being implemented, but needs some more fundamental changes to the framework to not need a hacky solution (e.g., [token transfers](/specification/future/introduction.html)). +> warning Sadly, the Kubernetes backend has been broken since Brane version 1.0.0. A fix is being implemented, but needs some more fundamental changes to the framework to not need a hacky solution (e.g., [token transfers]({{ specification_root }}/future/introduction.html)). The next chapters contain more details on each of the backends: 1. The [local](./local.md)-backend; and diff --git a/src/system-admins/installation/branectl.md b/src/system-admins/installation/branectl.md index 28f1344..d81510f 100644 --- a/src/system-admins/installation/branectl.md +++ b/src/system-admins/installation/branectl.md @@ -5,9 +5,9 @@ This chapter concerns itself with installing `branectl` itself. Make sure that y ## Precompiled binary -In most cases, it's the easiest to download the precompiled binary from the [GitHub repository](https://github.com/epi-project/brane). +In most cases, it's the easiest to download the precompiled binary from the [GitHub repository](https://github.com/BraneFramework/brane). -To download it, you can simply go to the repository () and navigate to 'tags'. From there, you can select your desired release and choose it from among the list. Alternatively, you can also go to the latest release by clicking this link: . +To download it, you can simply go to the repository () and navigate to 'tags'. From there, you can select your desired release and choose it from among the list. Alternatively, you can also go to the latest release by clicking this link: . > info Note that `branectl` was only introduced in version 1.0.0, so any version before that will not have a downloadable `branectl` executable (or any compatible one, for that matter). @@ -20,13 +20,13 @@ if you are in the folder where you downloaded the tool. Alternatively, you can also download the latest version using `curl` from the command-line: ```bash # For Linux (x86-64) -sudo curl -Lo /usr/local/bin/branectl https://github.com/epi-project/brane/releases/latest/download/branectl-linux-x86_64 +sudo curl -Lo /usr/local/bin/branectl https://github.com/BraneFramework/brane/releases/latest/download/branectl-linux-x86_64 # For macOS (Intel) -sudo curl -Lo /usr/local/bin/branectl https://github.com/epi-project/brane/releases/latest/download/branectl-darwin-x86_64 +sudo curl -Lo /usr/local/bin/branectl https://github.com/BraneFramework/brane/releases/latest/download/branectl-darwin-x86_64 # For macOS (M1/M2) -sudo curl -Lo /usr/local/bin/branectl https://github.com/epi-project/brane/releases/latest/download/branectl-darwin-aarch64 +sudo curl -Lo /usr/local/bin/branectl https://github.com/BraneFramework/brane/releases/latest/download/branectl-darwin-aarch64 ``` Don't forget to make the executable runnable: @@ -38,7 +38,7 @@ sudo chmod +x /usr/local/bin/branectl ## Compile it yourself Sometimes, though, the executable provided on the repository doesn't suit your needs. This is typically the case if you need a cutting-edge version that isn't released, you have an uncommon OS or processor architecture or an incompatible GLIBC version. -To compile the binary, refer to the [compilation instructions](/specification/development/compilation.html) over at the [Brane: A Specification](/specification)-book for instructions. +To compile the binary, refer to the [compilation instructions]({{ specification_root }}/development/compilation.html) over at the [Brane: A Specification]({{ specification_root }})-book for instructions. ## Next diff --git a/src/system-admins/installation/control-node.md b/src/system-admins/installation/control-node.md index 7038cdb..e456375 100644 --- a/src/system-admins/installation/control-node.md +++ b/src/system-admins/installation/control-node.md @@ -37,7 +37,7 @@ Once these complete successfully, you should have the images for the control nod ### Compiling the images -The other way to obtain the images is to compile them yourself. If you want to do so, refer to the [compilation instructions](/specification/development/compilation.html) over at the [Brane: A Specification](/specification)-book for instructions. +The other way to obtain the images is to compile them yourself. If you want to do so, refer to the [compilation instructions]({{ specification_root }}/development/compilation.html) over at the [Brane: A Specification]({{ specification_root }})-book for instructions. ## Generating configuration @@ -102,7 +102,7 @@ The `-f` flag will make sure that any of the missing directories (e.g., `config/ Once again, you can change many of the properties in the `node.yml` file by specifying additional command-line options (see the [`branectl` documentation](TODO) or the builtin `branectl generate node --help`) or by changing the file manually (see the [`node.yml` documentation](../../config/admins/node.md)). -> warning Due to a [bug](https://github.com/epi-project/brane/issues/27) in one of the framework's dependencies, it cannot handle certificates on IP addresses. To workaround this issue, the `-H` option is provided; it can be used to specify a certain hostname/IP mapping for this node only. Example: +> warning Due to a [bug](https://github.com/BraneFramework/brane/issues/27) in one of the framework's dependencies, it cannot handle certificates on IP addresses. To workaround this issue, the `-H` option is provided; it can be used to specify a certain hostname/IP mapping for this node only. Example: > ```bash > # We can address '192.0.2.2' with 'bob-domain' now > branectl generate node -f -H bob-domain:192.0.2.2 central central-domain.com diff --git a/src/system-admins/installation/proxy-node.md b/src/system-admins/installation/proxy-node.md index 051f87f..62cb31e 100644 --- a/src/system-admins/installation/proxy-node.md +++ b/src/system-admins/installation/proxy-node.md @@ -31,7 +31,7 @@ Once these complete successfully, you should have the images for the worker node ### Compiling the images -The other way to obtain the images is to compile them yourself. If you want to do so, refer to the [compilation instructions](/specification/development/compilation.html) over at the [Brane: A Specification](/specification)-book for instructions. +The other way to obtain the images is to compile them yourself. If you want to do so, refer to the [compilation instructions]({{ specification_root }}/development/compilation.html) over at the [Brane: A Specification]({{ specification_root }})-book for instructions. ## Generating configuration @@ -84,7 +84,7 @@ branectl generate node -f proxy 192.0.2.2 Once again, you can change many of the properties in the `node.yml` file by specifying additional command-line options (see the [`branectl` documentation](TODO) or the builtin `branectl generate node --help`) or by changing the file manually (see the [`node.yml` documentation](../../config/admins/node.md)). -> warning Due to a [bug](https://github.com/epi-project/brane/issues/27) in one of the framework's dependencies, it cannot handle certificates on IP addresses. To workaround this issue, the `-H` option is provided; it can be used to specify a certain hostname/IP mapping for this node only. Example: +> warning Due to a [bug](https://github.com/BraneFramework/brane/issues/27) in one of the framework's dependencies, it cannot handle certificates on IP addresses. To workaround this issue, the `-H` option is provided; it can be used to specify a certain hostname/IP mapping for this node only. Example: > ```bash > # We can address '192.0.2.2' with 'some-domain' now > branectl generate node -f -H some-domain:192.0.2.2 proxy bob-domain.com diff --git a/src/system-admins/installation/worker-node.md b/src/system-admins/installation/worker-node.md index d9c3e3f..65c7f5f 100644 --- a/src/system-admins/installation/worker-node.md +++ b/src/system-admins/installation/worker-node.md @@ -31,7 +31,7 @@ Once these complete successfully, you should have the images for the worker node ### Compiling the images -The other way to obtain the images is to compile them yourself. If you want to do so, refer to the [compilation instructions](/specification/development/compilation.html) over at the [Brane: A Specification](/specification)-book for instructions. +The other way to obtain the images is to compile them yourself. If you want to do so, refer to the [compilation instructions]({{ specification_root }}/development/compilation.html) over at the [Brane: A Specification]({{ specification_root }})-book for instructions. ## Generating configuration @@ -47,7 +47,7 @@ For a worker node, this means generating the following files: All of these can be generated with `branectl` for convenience. -We will first generate a `backend.yml` file. This will define how the worker node can connect to the infrastructure that will actually execute incoming containers. Multiple backend types are possible (see the [series of chapters on it](../backends/introduction.md)), but by default, the configuration assumes that work will be executed on the local machine's Docker daemon. +We will first generate a `backend.yml` file. This will define how the worker node can connect to the infrastructure that will actually execute incoming containers. Multiple backend types are theoretically possible, but by default, the configuration assumes that work will be executed on the local machine's Docker daemon. Thus, to generate such a `backend.yml` file, you can use the following command: ```bash @@ -123,7 +123,7 @@ branectl generate node -f worker 192.0.2.2 bob Once again, you can change many of the properties in the `node.yml` file by specifying additional command-line options (see the [`branectl` documentation](TODO) or the builtin `branectl generate node --help`) or by changing the file manually (see the [`node.yml` documentation](../../config/admins/node.md)). -> warning Due to a [bug](https://github.com/epi-project/brane/issues/27) in one of the framework's dependencies, it cannot handle certificates on IP addresses. To workaround this issue, the `-H` option is provided; it can be used to specify a certain hostname/IP mapping for this node only. Example: +> warning Due to a [bug](https://github.com/BraneFramework/brane/issues/27) in one of the framework's dependencies, it cannot handle certificates on IP addresses. To workaround this issue, the `-H` option is provided; it can be used to specify a certain hostname/IP mapping for this node only. Example: > ```bash > # We can address '192.0.2.2' with 'some-domain' now > branectl generate node -f -H some-domain:192.0.2.2 worker bob-domain.com bob @@ -195,7 +195,7 @@ At runtime, whenever your worker node will need to download a dataset from anoth ## Writing policies -Before you launch the instance, you may want to [change the node's policy](../../policy-experts/managing-policies.md). If not, then the default policy kicks in; which is deny all. +Before you launch the instance, you may want to [change the node's policy](../../policy-experts/management.md). If not, then the default policy kicks in; which is deny all. To change which policies are active, the policy experts needs access tokens to authorize themselves. You can generate these by running: ```bash diff --git a/src/system-admins/introduction.md b/src/system-admins/introduction.md index 0651e4a..3a14220 100644 --- a/src/system-admins/introduction.md +++ b/src/system-admins/introduction.md @@ -1,7 +1,7 @@ # Introduction In this series of chapters, we will discuss the role of system administrators and how they may prepare their system for Brane. The chapters will talk about what the requirements are on their system and what kind of information they are expected to share with the Brane instance. Finally, we will also discuss defining datasets. -To know more about the inner workings of Brane, we recommend you checkout the [Brane: A Specification](/specification) book. That details the framework's inner workings. +To know more about the inner workings of Brane, we recommend you checkout the [Brane: A Specification]({{ specification_root }}) book. That details the framework's inner workings. ## Background & Terminology @@ -19,7 +19,7 @@ The control node consists of the following few services: - The _registry service_ (sometimes called _central registry service_ or _API service_ for disambiguation) is the centralized version of the local registry services (see [below](#the-worker-node)). It acts as a centralized database for the framework, which provides information about which dataset is located where, which domains are participating and where to find them1, and in addition hosts a central package repository. - Finally, the _proxy service_ acts as a gateway between the other services and the outside world to _enable_ proxying (i.e., it does not accept proxied requests, but rather creates them). In addition, it is also the point that handles server certificates and parses client certificates for identifications. -For more details, check the [specification](/specification). +For more details, check the [specification]({{ specification_root }}). Note that, if you need any compute to happen on the central node, this cannot be done through the central node itself; instead, setup a [worker node](#the-worker-node) alongside the central node to emulate the same behaviour. @@ -27,24 +27,20 @@ Note that, if you need any compute to happen on the central node, this cannot be ## The Worker node As specified, a domain typically hosts a worker node. This worker node collectively describes both a local control part of the framework, referred to as the framework _delegate_, and some computing backend that actually executes the jobs. In this section, we provide a brief overview of both. -The _delegate_ itself consists of a few services. Their exact working is detailled in the [specification](/specification), but as a brief overview: +The _delegate_ itself consists of a few services. Their exact working is detailled in the [specification]({{ specification_root }}), but as a brief overview: - The _delegate service_ is the main service on the delegate, and takes incoming job requests and will attempt to schedule them. This is also the service that directly connects to the compute backend (see below). You can think of it as a local driver service. - The _registry service_ (sometimes called _local registry service_ for disambiguation) keeps track of the locally available datasets and intermediate results (see the [data tutorial](../software-engineers/data.md) for Software Engineers or the [data tutorial](../scientists/bscript/datasets.md) for Scientists for more information) and acts as a point from where the rest of the framework downloads them. -- The _checker service_ acts as the Policy Enforcement Point (PEP) for the framework. It hosts a [reasoner](https://github.com/epi-project/policy-reasoner), typically eFLINT, and is queried by both the delegate and registry services to see if operations are allowed. +- The _checker service_ acts as the Policy Enforcement Point (PEP) for the framework. It hosts a [reasoner](https://github.com/BraneFramework/policy-reasoner), typically eFLINT, and is queried by both the delegate and registry services to see if operations are allowed. - Finally, the local node also has _proxy service_, just like the [central node](#the-central-node). As for the compute backend, Brane is designed to connect to different types. An overview: {{#include ./backends/overview.md}} -More information on each backend and how to set it up is discussed in the [backends chapter(s)](./backends/introduction.md). - ## Next To start setting up your own worker node, we recommend checking out the [installation chapters](./installation/introduction.md). These will walk you through everything you need to setup a node, both control nodes and worker nodes. -For information on setting up different backends, check the [backend chapters](./backends/introduction.md). - -Alternatively, if you are looking for extensive documentation on the Brane configuration files relevant to a worker node, checkout the [documentation chapters](./docs/overview.md). +Alternatively, if you are looking for extensive documentation on the Brane configuration files relevant to a worker node, checkout the [documentation chapters]({{ brane_docs_root }}/overview/index.html). From 93b5337bb02aaa7d84d5270ed0447e8e6dbe8010 Mon Sep 17 00:00:00 2001 From: Daniel Voogsgerd Date: Wed, 5 Mar 2025 16:37:20 +0100 Subject: [PATCH 2/2] chore: Add linkcheck From now on we cannot build mdbooks if a link is broken. --- book.toml | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/book.toml b/book.toml index d11cb69..336559f 100644 --- a/book.toml +++ b/book.toml @@ -14,3 +14,58 @@ git-repository-icon = "fa-github" [preprocessor.variables.variables] specification_root = "https://braneframework.github.io/specification" brane_docs_root = "https://braneframework.github.io/brane/unstable" + + +[output.linkcheck] +# Should we check links on the internet? Enabling this option adds a +# non-negligible performance impact +follow-web-links = true + +# Are we allowed to link to files outside of the book's root directory? This +# may help prevent linking to sensitive files (e.g. "../../../../etc/shadow") +traverse-parent-directories = false + +# If necessary, you can exclude one or more links from being checked with a +# list of regular expressions. The regex will be applied to the link href (i.e. +# the `./index.html` in `[some page](./index.html)`) so it can be used to +# ignore both web and filesystem links. +# +# Hint: you can use TOML's raw strings (single quote) to avoid needing to +# escape things twice. +exclude = [ 'TODO', 'https://flaticon.com' ] + +# The User-Agent to use when sending web requests +user-agent = "mdbook-linkcheck-0.4.0" + +# The number of seconds a cached result is valid for (12 hrs by default) +cache-timeout = 43200 + +# How should warnings be treated? +# +# - "warn" will emit warning messages +# - "error" treats all warnings as errors, failing the linkcheck +# - "ignore" will ignore warnings, suppressing diagnostic messages and allowing +# the linkcheck to continuing +warning-policy = "warn" + +# Extra HTTP headers that must be send to certain web sites +# in order to link check to succeed. +# +# This is a dictionary (map), with keys being regexes +# matching a set of web sites, and values being an array of +# the headers. +[output.linkcheck.http-headers] +# Any hyperlink that contains this regexp will be sent +# the "Accept: text/html" header +# 'crates\.io' = ["Accept: text/html"] + +# mdbook-linkcheck will interpolate environment variables into your header via +# $IDENT. +# +# If this is not what you want you must escape the `$` symbol, like `\$TOKEN`. +# `\` itself can also be escaped via `\\`. +# +# Note: If interpolation fails, the header will be skipped and the failure will +# be logged. This can be useful if a particular header isn't always necessary, +# but may be helpful (e.g. when working with rate limiting). +# 'website\.com' = ["Authorization: Basic $TOKEN"]