Quick Start

This page shows you how to start Vanus in minutes.

Prerequisites

You can skip the step if you already have those.

Have Docker, how to install

Installation

Vanus

Create Docker network for Quick Start.

docker network create --driver bridge vanus-quickstart

Start Vanus all-in-one container.

docker run -d --rm \
    --network vanus-quickstart \
    --pull always \
    -p 8080:8080 \
    -p 8081:8081 \
    --name vanus-all-in-one public.ecr.aws/vanus/all-in-one:latest

Command Line Tool

Download vsctl, the command line tool for Vanus.

Linux
macOS M Chip
macOS Intel

curl -O https://dl.vanus.ai/vsctl/latest/linux-amd64/vsctl
chmod ug+x vsctl
sudo mv vsctl /usr/local/bin

curl -O https://dl.vanus.ai/vsctl/latest/darwin-arm64/vsctl
chmod ug+x vsctl
sudo mv vsctl /usr/local/bin

curl -O https://dl.vanus.ai/vsctl/latest/darwin-amd64/vsctl
chmod ug+x vsctl
sudo mv vsctl /usr/local/bin

Verify the installation

vsctl version

+-----------+----------------------------------+
|  Version  | v0.8.0                           |
|  Platform | darwin/arm64                     |
| GitCommit | d35053c3                         |
| BuildDate | 2023-04-18_17:05:53+0800         |
| GoVersion | go version go1.20.3 darwin/arm64 |
+-----------+----------------------------------+

Set Vanus Endpoint

use env variable to tell the endpoint to vsctl

export VANUS_GATEWAY=127.0.0.1:8080

Use-cases

There are some examples below that demonstrate vanus can do.

Put/Get Event

create an eventbus

vsctl eventbus create --namespace default --name quick-start

To check if the default namespace exists

vsctl namespace list

send an event to the eventbus

vsctl event put quick-start \
  --data-format plain \
  --data "Hello Vanus" \
  --id "1" \
  --source "quick-start" \
  --type "examples"

get an event from eventbus

vsctl event get quick-start --offset 0 --number 1

the result should look like

+-----+----------------------------------------+
| NO. |                  EVENT                 |
+-----+----------------------------------------+
|     | Context Attributes,                    |
|     |   specversion: 1.0                     |
|     |   type: examples                       |
|     |   source: quick-start                  |
|     |   id: 1                                |
|  0  |   time: 2023-08-18T07:42:07.80423Z     |
|     |   datacontenttype: text/plain          |
|     | Extensions,                            |
|     |   xvanuseventbus: quick-start          |
|     | Data,                                  |
|     |   Hello Vanus                          |
|     |                                        |
+-----+----------------------------------------+

Filter

start a display server to verify filter

docker run -d --rm \
  --network vanus-quickstart \
  --pull always \
  --name display public.ecr.aws/vanus/connector/sink-display:latest

tip

make sure the container is properly started

docker ps

output should like below

CONTAINER ID   IMAGE                                                COMMAND                  CREATED         STATUS         PORTS                              NAMES
5b87170c039a   public.ecr.aws/vanus/connector/sink-display:latest   "/vanus-connect/run.…"   5 seconds ago   Up 3 seconds   8080/tcp                           display
1beac3127c0c   public.ecr.aws/vanus/all-in-one:latest               "/vanus/run.sh"          2 minutes ago   Up 2 minutes   0.0.0.0:8080-8081->8080-8081/tcp   vanus-all-in-one

create a subscription

vsctl subscription create \
  --name quick-start-filter \
  --namespace default \
  --eventbus quick-start \
  --sink 'http://display:8080' \
  --filters '[
    {
      "exact": {
          "source":"quick-start-filter-section"
      }
    }
  ]'  

output should like below

+------------------+-------------------+---------+-------------+-------------------------+-------------+----------+----------------+--------+---------+--------+-------------+----------------------+----------------------+
|        ID        |        NAME       | DISABLE |   EVENTBUS  |           SINK          | DESCRIPTION | PROTOCOL | SINKCREDENTIAL | CONFIG | OFFSETS | FILTER | TRANSFORMER |      CREATED_AT      |      UPDATED_AT      |
+------------------+-------------------+---------+-------------+-------------------------+-------------+----------+----------------+--------+---------+--------+-------------+----------------------+----------------------+
| 0000004644000010 | quick-start-filter |  false  | quick-start | http://quick-display:8080 |             |   http   |      null      |   {}   |   null  | ...    | null        | 2023-08-18T15:48:08+08:00 | 2023-08-18T15:48:08+08:00 |
+------------------+-------------------+---------+-------------+-------------------------+-------------+----------+----------------+--------+---------+--------+-------------+----------------------+----------------------+

the subscription will subscribe all events from --source in --eventbus. and only events matched with --filter can be emitted to --sink.

send events to quick-start just created

sending 3 events in here

vsctl event put quick-start \
  --data '{"msg":"1st event, DISPLAY: YES"}' \
  --id "1st" \
  --source "quick-start-filter-section"
  
vsctl event put quick-start \
  --data '{"msg":"2nd event, DISPLAY: NO"}' \
  --id "2nd" \
  --source "quick-start"
  
vsctl event put quick-start \
  --data '{"msg":"3rd event, DISPLAY: YES"}' \
  --id "3rd" \
  --source "quick-start-filter-section"

back to display server for validation, the first and third event we just sent should be displayed.

docker logs display

the output should look like below, the two events whose source are matched are displayed.

2023-08-18T08:55:27Z INF go/pkg/mod/github.com/vanus-labs/cdk-go@v0.7.5/runtime/sink/worker.go:98 > add a connector connector_id=
2023-08-18T08:55:27Z INF go/pkg/mod/github.com/vanus-labs/cdk-go@v0.7.5/runtime/sink/worker.go:108 > connector start connector_id=
2023-08-18T08:55:27Z INF go/pkg/mod/github.com/vanus-labs/cdk-go@v0.7.5/runtime/util/http_receiver.go:44 > http server is ready to start port=8080
2023-08-18T09:07:26Z INF build/vanus-connect/connectors/sink-display/internal/server.go:65 > receive a new event total=1
{
  "specversion": "1.0",
  "id": "1st",
  "source": "quick-start-filter-section",
  "type": "cmd",
  "datacontenttype": "application/json",
  "time": "2023-08-18T09:07:26.186771Z",
  "data": {
    "msg": "1st event, DISPLAY: YES"
  },
  "xvanuseventbus": "0000002961000010",
  "xvanusstime": "2023-08-18T09:07:26.192Z"
}

{
  "specversion": "1.0",
  "id": "3rd",
  "source": "quick-start-filter-section",
  "type": "cmd",
  "datacontenttype": "application/json",
  "time": "2023-08-18T09:07:26.304917Z",
  "data": {
    "msg": "3rd event, DISPLAY: YES"
  },
  "xvanuseventbus": "0000002961000010",
  "xvanusstime": "2023-08-18T09:07:26.308Z"
}

2023-08-18T09:07:26Z INF build/vanus-connect/connectors/sink-display/internal/server.go:65 > receive a new event total=2

for more about filter, you can find in how to manage subscription

Transformer

create a subscription with transformer

vsctl subscription create \
  --name quick-start-transformer \
  --namespace default \
  --eventbus quick-start \
  --sink 'http://display:8080' \
  --transformer '{
      "define": {
        "dataMsg": "$.data.msg",
        "dataSource": "$.source"
      },
      "template": "{\"transKey\": \"<dataMsg>\",\"transSource\":\"<dataSource>\"}"
    }'  

output looks like:

+------------------+-------------------------+---------+------------------+------------------+---------------------+-------------+----------+----------------+--------+---------+--------+-------------+---------------------------+---------------------------+
|        ID        |           NAME          | DISABLE |     EVENTBUS     |     NAMESPACE    |         SINK        | DESCRIPTION | PROTOCOL | SINKCREDENTIAL | CONFIG | OFFSETS | FILTER | TRANSFORMER |         CREATED_AT        |         UPDATED_AT        |
+------------------+-------------------------+---------+------------------+------------------+---------------------+-------------+----------+----------------+--------+---------+--------+-------------+---------------------------+---------------------------+
| 000001BCC2000010 | quick-start-transformer |  false  | 0000002961000010 | 000000006E000010 | http://display:8080 |             |   http   |      null      |   {}   |   null  | null   | ...         | 2023-08-18T17:11:56+08:00 | 2023-08-18T17:11:56+08:00 |
+------------------+-------------------------+---------+------------------+------------------+---------------------+-------------+----------+----------------+--------+---------+--------+-------------+---------------------------+---------------------------+

send events to quick-start

vsctl event put quick-start \
  --data '{"msg":"1st event, DISPLAY: YES"}' \
  --id "1st" \
  --source "quick-start-filter-section"

back to display server for validation

docker logs display

the transformed event has been displayed.

...
2023-08-18T09:13:05Z INF build/vanus-connect/connectors/sink-display/internal/server.go:65 > receive a new event total=...
{
  "specversion": "1.0",
  "id": "1st",
  "source": "quick-start-filter-section",
  "type": "cmd",
  "datacontenttype": "application/json",
  "time": "2023-08-18T09:13:05.236907Z",
  "data": {
    "transKey": "1st event, DISPLAY: YES",
    "transSource": "quick-start-filter-section"
  },
  "xvanuseventbus": "0000002961000010",
  "xvanusstime": "2023-08-18T09:13:05.242Z"
}

2023-08-18T09:13:05Z INF build/vanus-connect/connectors/sink-display/internal/server.go:65 > receive a new event total=...
...

Clean

docker stop vanus-all-in-one display && docker network rm vanus-quickstart

You can go forward to How to use Vanus for learning more about Vanus.

Quick Start

Prerequisites​

Installation​

Vanus​

Command Line Tool​

Set Vanus Endpoint​

Use-cases​

Put/Get Event​

Filter​

Transformer​

Clean​

Next​