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