github.com/Jeffail/benthos/v3@v3.65.0/website/docs/guides/getting_started.md (about)

     1  ---
     2  title: Getting Started
     3  description: Getting started with Benthos
     4  ---
     5  
     6  Woops! You fell for the marketing hype. Let's try and get through this together.
     7  
     8  <div style={{textAlign: 'center'}}><img style={{maxWidth: '300px'}} src="/img/teacher-blob.svg" /></div>
     9  
    10  ## Install
    11  
    12  The easiest way to install Benthos is with this handy script:
    13  
    14  import Tabs from '@theme/Tabs';
    15  import TabItem from '@theme/TabItem';
    16  
    17  <Tabs defaultValue="latest" values={[
    18    { label: 'Latest stable version', value: 'latest', },
    19    { label: 'Specific version', value: 'version', },
    20  ]}>
    21  <TabItem value="latest">
    22  
    23  ```sh
    24  curl -Lsf https://sh.benthos.dev | bash
    25  ```
    26  
    27  </TabItem>
    28  <TabItem value="version">
    29  
    30  ```sh
    31  curl -Lsf https://sh.benthos.dev | bash -s -- 3.56.0
    32  ```
    33  
    34  </TabItem>
    35  </Tabs>
    36  
    37  Or you can grab an archive containing Benthos from the [releases page][releases].
    38  
    39  ### Docker
    40  
    41  If you have docker installed you can pull the latest official Benthos image with:
    42  
    43  ```sh
    44  docker pull jeffail/benthos
    45  docker run --rm -v /path/to/your/config.yaml:/benthos.yaml jeffail/benthos
    46  ```
    47  
    48  ### Homebrew
    49  
    50  On macOS, Benthos can be installed via Homebrew:
    51  
    52  ```sh
    53  brew install benthos
    54  ```
    55  
    56  ### Serverless
    57  
    58  For information about serverless deployments of Benthos check out the serverless section [here][serverless].
    59  
    60  ## Run
    61  
    62  A Benthos stream pipeline is configured with a single [config file][configuration], you can generate a fresh one with:
    63  
    64  ```shell
    65  benthos create > config.yaml
    66  ```
    67  
    68  The main sections that make up a config are `input`, `pipeline` and `output`. When you generate a fresh config it'll simply pipe `stdin` to `stdout` like this:
    69  
    70  ```yaml
    71  input:
    72    stdin: {}
    73  
    74  pipeline:
    75    processors: []
    76  
    77  output:
    78    stdout: {}
    79  ```
    80  
    81  Eventually we'll want to configure a more useful [input][inputs] and [output][outputs], but for now this is useful for quickly testing processors. You can execute this config with:
    82  
    83  ```sh
    84  benthos -c ./config.yaml
    85  ```
    86  
    87  Anything you write to stdin will get written unchanged to stdout, cool! Resist the temptation to play with this for hours, there's more stuff to try out.
    88  
    89  Next, let's add some processing steps in order to mutate messages. The most powerful one is the [`bloblang` processor][processors.bloblang] which allows us to perform mappings, let's add a mapping to uppercase our messages:
    90  
    91  ```yaml
    92  input:
    93    stdin: {}
    94  
    95  pipeline:
    96    processors:
    97      - bloblang: root = content().uppercase()
    98  
    99  output:
   100    stdout: {}
   101  ```
   102  
   103  Now your messages should come out in all caps, how whacky! IT'S LIKE BENTHOS IS SHOUTING BACK AT YOU!
   104  
   105  You can add as many [processing steps][processors] as you like, and since processors are what make Benthos powerful they are worth experimenting with. Let's create a more advanced pipeline that works with JSON documents:
   106  
   107  ```yaml
   108  input:
   109    stdin: {}
   110  
   111  pipeline:
   112    processors:
   113      - sleep:
   114          duration: 500ms
   115      - bloblang: |
   116          root.doc = this
   117          root.first_name = this.names.index(0).uppercase()
   118          root.last_name = this.names.index(-1).hash("sha256").encode("base64")
   119  
   120  output:
   121    stdout: {}
   122  ```
   123  
   124  First, we sleep for 500 milliseconds just to keep the suspense going. Next, we restructure our input JSON document by nesting it within a field `doc`, we map the upper-cased first element of `names` to a new field `first_name`. Finally, we map the hashed and base64 encoded value of the last element of `names` to a new field `last_name`.
   125  
   126  Try running that config with some sample documents:
   127  
   128  ```sh
   129  echo '
   130  {"id":"1","names":["celine","dion"]}
   131  {"id":"2","names":["chad","robert","kroeger"]}' | benthos -c ./config.yaml
   132  ```
   133  
   134  You should see (amongst some logs):
   135  
   136  ```sh
   137  {"doc":{"id":"1","names":["celine","dion"]},"first_name":"CELINE","last_name":"1VvPgCW9sityz5XAMGdI2BTA7/44Wb3cANKxqhiCo50="}
   138  {"doc":{"id":"2","names":["chad","robert","kroeger"]},"first_name":"CHAD","last_name":"uXXg5wCKPjpyj/qbivPbD9H9CZ5DH/F0Q1Twytnt2hQ="}
   139  ```
   140  
   141  How exciting! I don't know about you but I'm going to need to lie down for a while. Now that you are a Benthos expert might I suggest you peruse these sections to see if anything tickles your fancy?
   142  
   143  - [Bloblang Walkthrough][bloblang.walkthrough]
   144  - [Inputs][inputs]
   145  - [Processors][processors]
   146  - [Outputs][outputs]
   147  - [Monitoring][monitoring]
   148  - [Cookbooks][cookbooks]
   149  - [More about configuration][configuration]
   150  
   151  [processors.bloblang]: /docs/components/processors/bloblang
   152  [proc_proc_field]: /docs/components/processors/process_field
   153  [proc_text]: /docs/components/processors/text
   154  [processors]: /docs/components/processors/about
   155  [inputs]: /docs/components/inputs/about
   156  [outputs]: /docs/components/outputs/about
   157  [jmespath]: http://jmespath.org/
   158  [releases]: https://github.com/Jeffail/benthos/releases
   159  [serverless]: /docs/guides/serverless/about
   160  [configuration]: /docs/configuration/about
   161  [monitoring]: /docs/guides/monitoring
   162  [cookbooks]: /cookbooks
   163  [bloblang.walkthrough]: /docs/guides/bloblang/walkthrough