Improving Distributed section

[deploy site]
SeleniumHQ · Aug 29, 2022 · e63c44e · e63c44e
1 parent 3f34162
commit e63c44e
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 88 deletions.
diff --git a/website_and_docs/content/documentation/grid/getting_started.en.md b/website_and_docs/content/documentation/grid/getting_started.en.md
@@ -103,12 +103,12 @@ java -jar selenium-server-<version>.jar node --port 6666
 
 ##### Node and Hub on different machines
 
-**Hub** and **Nodes** talk to each other via HTTP and the [**EventBus**]({{< ref "components.md#event-bus" >}})
-(the **EventBus** lives inside the **Hub**). A **Node** sends a message to the **Hub** via the **EventBus** to 
+**Hub** and **Nodes** talk to each other via HTTP and the [**Event Bus**]({{< ref "components.md#event-bus" >}})
+(the **Event Bus** lives inside the **Hub**). A **Node** sends a message to the **Hub** via the **Event Bus** to 
 start the registration process. When the **Hub** receives the message, reaches out to the **Node** via HTTP to 
 confirm its existence.
 
-To successfully register a **Node** to a **Hub** it is important to expose the **EventBus** ports (4442 and 4443 by 
+To successfully register a **Node** to a **Hub**, it is important to expose the **Event Bus** ports (4442 and 4443 by 
 default) on the **Hub** machine. This also applies for the **Node** port. With that, both **Hub** and **Node** will
 be able to communicate.
 
@@ -117,7 +117,7 @@ If the **Hub** is using the default ports, the `--hub` flag can be used to regis
 java -jar selenium-server-<version>.jar node --hub http://<hub-ip>:4444
 ```
 
-When the **Hub** is not using the default ports, the `--publish-events` and `--subscribe-events` are needed.
+When the **Hub** is not using the default ports, the `--publish-events` and `--subscribe-events` flags are needed.
 
 For example, if the **Hub** uses ports `8886`, `8887`, and `8888`
 ```shell
@@ -130,50 +130,53 @@ java -jar selenium-server-<version>.jar node --publish-events tcp://<hub-ip>:888
 
 ### Distributed 
 
-When using a distributed Grid, each component needs is started separately. This setup is more suitable
-for large Grids.
+When using a Distributed Grid, each component is started separately, and ideally on different machines.
 
 {{% alert color="primary" %}}
-The startup order of the components is not important, however, we recommend following these
-steps when starting a distributed Grid.
+It is important to expose all ports properly in order to allow fluent communication between all components.
 {{% /alert %}}
 
+1. **Event Bus**: enables internal communication between different Grid components.
 
-1. **Event Bus**: a communication path to other Grid components
-
+Default ports are: `4442`, `4443`, and `5557`.
 ```shell
-java -jar selenium-server-<version>.jar  event-bus
+java -jar selenium-server-<version>.jar event-bus --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --port 5557
 ```
 
-2. **Session Map**: maps session IDs to the **Node** where the session is running
+2. **New Session Queue**: adds new session requests to a queue, which will be queried by the Distributor
 
+Default port is `5559`.
 ```shell
-java -jar selenium-server-<version>.jar sessions
+java -jar selenium-server-<version>.jar sessionqueue --port 5559
 ```
 
-3. **New Session Queue**: adds the new session request to a queue for the distributor to processes
+3. **Session Map**: maps session IDs to the **Node** where the session is running
 
+Default **Session Map** port is `5556`. **Session Map** interacts with the **Event Bus**. 
 ```shell
-java -jar selenium-server-<version>.jar sessionqueue
+java -jar selenium-server-<version>.jar sessions --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --port 5556
 ```
 
-4. **Distributor**: assigns a **Node** for a session request. Other **Nodes** register to the **Distributor**
-the way they would have registered to the **Hub** in a non-distributed Grid
+4. **Distributor**: queries the **New Session Queue** for new session requests, and assigns them to a **Node** when the capabilities match. **Nodes** register to the **Distributor** the way they register to the **Hub** in a **Hub/Node** Grid.
+
+Default **Distributor** port is `5553`. **Distributor** interacts with **New Session Queue**, **Session Map**, **Event Bus**, and the **Node(s)**.
 
 ```shell
-java -jar selenium-server-<version>.jar distributor --sessions http://localhost:5556 --sessionqueue http://localhost:5559 --bind-bus false
+java -jar selenium-server-<version>.jar distributor --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --sessions http://<sessions-ip>:5556 --sessionqueue http://<new-session-queue-ip>:5559 --port 5553 --bind-bus false
 ```
 
-5. **Router**: Redirects requests to the right component
+5. **Router**: redirects new session requests to the queue, and redirects running sessions requests to the **Node** running that session.
 
+Default **Router** port is `4444`. **Router** interacts with **New Session Queue**, **Session Map**, and **Distributor**.
 ```shell
-java -jar selenium-server-<version>.jar router --sessions http://localhost:5556 --distributor http://localhost:5553 --sessionqueue http://localhost:5559
+java -jar selenium-server-<version>.jar router --sessions http://<sessions-ip>:5556 --distributor http://<distributor-ip>:5553 --sessionqueue http://<new-session-queue-ip>:5559 --port 4444
 ```
 
-6. Node(s)
+6. **Node(s)**
 
+Default **Node** port is `5555`.
 ```shell
-java -jar selenium-server-<version>.jar node 
+java -jar selenium-server-<version>.jar node --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443
 ```
 
 ## Metadata in tests

diff --git a/website_and_docs/content/documentation/grid/getting_started.ja.md b/website_and_docs/content/documentation/grid/getting_started.ja.md
@@ -113,12 +113,12 @@ java -jar selenium-server-<version>.jar node --port 6666
 
 ##### Node and Hub on different machines
 
-**Hub** and **Nodes** talk to each other via HTTP and the [**EventBus**]({{< ref "components.md#event-bus" >}})
-(the **EventBus** lives inside the **Hub**). A **Node** sends a message to the **Hub** via the **EventBus** to 
+**Hub** and **Nodes** talk to each other via HTTP and the [**Event Bus**]({{< ref "components.md#event-bus" >}})
+(the **Event Bus** lives inside the **Hub**). A **Node** sends a message to the **Hub** via the **Event Bus** to 
 start the registration process. When the **Hub** receives the message, reaches out to the **Node** via HTTP to 
 confirm its existence.
 
-To successfully register a **Node** to a **Hub** it is important to expose the **EventBus** ports (4442 and 4443 by 
+To successfully register a **Node** to a **Hub**, it is important to expose the **Event Bus** ports (4442 and 4443 by 
 default) on the **Hub** machine. This also applies for the **Node** port. With that, both **Hub** and **Node** will
 be able to communicate.
 
@@ -127,7 +127,7 @@ If the **Hub** is using the default ports, the `--hub` flag can be used to regis
 java -jar selenium-server-<version>.jar node --hub http://<hub-ip>:4444
 ```
 
-When the **Hub** is not using the default ports, the `--publish-events` and `--subscribe-events` are needed.
+When the **Hub** is not using the default ports, the `--publish-events` and `--subscribe-events` flags are needed.
 
 For example, if the **Hub** uses ports `8886`, `8887`, and `8888`
 ```shell
@@ -140,50 +140,53 @@ java -jar selenium-server-<version>.jar node --publish-events tcp://<hub-ip>:888
 
 ### Distributed 
 
-When using a distributed Grid, each component needs is started separately. This setup is more suitable
-for large Grids.
+When using a Distributed Grid, each component is started separately, and ideally on different machines.
 
 {{% alert color="primary" %}}
-The startup order of the components is not important, however, we recommend following these
-steps when starting a distributed Grid.
+It is important to expose all ports properly in order to allow fluent communication between all components.
 {{% /alert %}}
 
+1. **Event Bus**: enables internal communication between different Grid components.
 
-1. **Event Bus**: a communication path to other Grid components
-
+Default ports are: `4442`, `4443`, and `5557`.
 ```shell
-java -jar selenium-server-<version>.jar  event-bus
+java -jar selenium-server-<version>.jar event-bus --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --port 5557
 ```
 
-2. **Session Map**: maps session IDs to the **Node** where the session is running
+2. **New Session Queue**: adds new session requests to a queue, which will be queried by the Distributor
 
+Default port is `5559`.
 ```shell
-java -jar selenium-server-<version>.jar sessions
+java -jar selenium-server-<version>.jar sessionqueue --port 5559
 ```
 
-3. **New Session Queue**: adds the new session request to a queue for the distributor to processes
+3. **Session Map**: maps session IDs to the **Node** where the session is running
 
+Default **Session Map** port is `5556`. **Session Map** interacts with the **Event Bus**. 
 ```shell
-java -jar selenium-server-<version>.jar sessionqueue
+java -jar selenium-server-<version>.jar sessions --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --port 5556
 ```
 
-4. **Distributor**: assigns a **Node** for a session request. Other **Nodes** register to the **Distributor**
-the way they would have registered to the **Hub** in a non-distributed Grid
+4. **Distributor**: queries the **New Session Queue** for new session requests, and assigns them to a **Node** when the capabilities match. **Nodes** register to the **Distributor** the way they register to the **Hub** in a **Hub/Node** Grid.
+
+Default **Distributor** port is `5553`. **Distributor** interacts with **New Session Queue**, **Session Map**, **Event Bus**, and the **Node(s)**.
 
 ```shell
-java -jar selenium-server-<version>.jar distributor --sessions http://localhost:5556 --sessionqueue http://localhost:5559 --bind-bus false
+java -jar selenium-server-<version>.jar distributor --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --sessions http://<sessions-ip>:5556 --sessionqueue http://<new-session-queue-ip>:5559 --port 5553 --bind-bus false
 ```
 
-5. **Router**: Redirects requests to the right component
+5. **Router**: redirects new session requests to the queue, and redirects running sessions requests to the **Node** running that session.
 
+Default **Router** port is `4444`. **Router** interacts with **New Session Queue**, **Session Map**, and **Distributor**.
 ```shell
-java -jar selenium-server-<version>.jar router --sessions http://localhost:5556 --distributor http://localhost:5553 --sessionqueue http://localhost:5559
+java -jar selenium-server-<version>.jar router --sessions http://<sessions-ip>:5556 --distributor http://<distributor-ip>:5553 --sessionqueue http://<new-session-queue-ip>:5559 --port 4444
 ```
 
-6. Node(s)
+6. **Node(s)**
 
+Default **Node** port is `5555`.
 ```shell
-java -jar selenium-server-<version>.jar node 
+java -jar selenium-server-<version>.jar node --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443
 ```
 
 ## Metadata in tests

diff --git a/website_and_docs/content/documentation/grid/getting_started.pt-br.md b/website_and_docs/content/documentation/grid/getting_started.pt-br.md
@@ -113,12 +113,12 @@ java -jar selenium-server-<version>.jar node --port 6666
 
 ##### Node and Hub on different machines
 
-**Hub** and **Nodes** talk to each other via HTTP and the [**EventBus**]({{< ref "components.md#event-bus" >}})
-(the **EventBus** lives inside the **Hub**). A **Node** sends a message to the **Hub** via the **EventBus** to 
+**Hub** and **Nodes** talk to each other via HTTP and the [**Event Bus**]({{< ref "components.md#event-bus" >}})
+(the **Event Bus** lives inside the **Hub**). A **Node** sends a message to the **Hub** via the **Event Bus** to 
 start the registration process. When the **Hub** receives the message, reaches out to the **Node** via HTTP to 
 confirm its existence.
 
-To successfully register a **Node** to a **Hub** it is important to expose the **EventBus** ports (4442 and 4443 by 
+To successfully register a **Node** to a **Hub**, it is important to expose the **Event Bus** ports (4442 and 4443 by 
 default) on the **Hub** machine. This also applies for the **Node** port. With that, both **Hub** and **Node** will
 be able to communicate.
 
@@ -127,7 +127,7 @@ If the **Hub** is using the default ports, the `--hub` flag can be used to regis
 java -jar selenium-server-<version>.jar node --hub http://<hub-ip>:4444
 ```
 
-When the **Hub** is not using the default ports, the `--publish-events` and `--subscribe-events` are needed.
+When the **Hub** is not using the default ports, the `--publish-events` and `--subscribe-events` flags are needed.
 
 For example, if the **Hub** uses ports `8886`, `8887`, and `8888`
 ```shell
@@ -140,50 +140,53 @@ java -jar selenium-server-<version>.jar node --publish-events tcp://<hub-ip>:888
 
 ### Distributed 
 
-When using a distributed Grid, each component needs is started separately. This setup is more suitable
-for large Grids.
+When using a Distributed Grid, each component is started separately, and ideally on different machines.
 
 {{% alert color="primary" %}}
-The startup order of the components is not important, however, we recommend following these
-steps when starting a distributed Grid.
+It is important to expose all ports properly in order to allow fluent communication between all components.
 {{% /alert %}}
 
+1. **Event Bus**: enables internal communication between different Grid components.
 
-1. **Event Bus**: a communication path to other Grid components
-
+Default ports are: `4442`, `4443`, and `5557`.
 ```shell
-java -jar selenium-server-<version>.jar  event-bus
+java -jar selenium-server-<version>.jar event-bus --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --port 5557
 ```
 
-2. **Session Map**: maps session IDs to the **Node** where the session is running
+2. **New Session Queue**: adds new session requests to a queue, which will be queried by the Distributor
 
+Default port is `5559`.
 ```shell
-java -jar selenium-server-<version>.jar sessions
+java -jar selenium-server-<version>.jar sessionqueue --port 5559
 ```
 
-3. **New Session Queue**: adds the new session request to a queue for the distributor to processes
+3. **Session Map**: maps session IDs to the **Node** where the session is running
 
+Default **Session Map** port is `5556`. **Session Map** interacts with the **Event Bus**. 
 ```shell
-java -jar selenium-server-<version>.jar sessionqueue
+java -jar selenium-server-<version>.jar sessions --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --port 5556
 ```
 
-4. **Distributor**: assigns a **Node** for a session request. Other **Nodes** register to the **Distributor**
-the way they would have registered to the **Hub** in a non-distributed Grid
+4. **Distributor**: queries the **New Session Queue** for new session requests, and assigns them to a **Node** when the capabilities match. **Nodes** register to the **Distributor** the way they register to the **Hub** in a **Hub/Node** Grid.
+
+Default **Distributor** port is `5553`. **Distributor** interacts with **New Session Queue**, **Session Map**, **Event Bus**, and the **Node(s)**.
 
 ```shell
-java -jar selenium-server-<version>.jar distributor --sessions http://localhost:5556 --sessionqueue http://localhost:5559 --bind-bus false
+java -jar selenium-server-<version>.jar distributor --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443 --sessions http://<sessions-ip>:5556 --sessionqueue http://<new-session-queue-ip>:5559 --port 5553 --bind-bus false
 ```
 
-5. **Router**: Redirects requests to the right component
+5. **Router**: redirects new session requests to the queue, and redirects running sessions requests to the **Node** running that session.
 
+Default **Router** port is `4444`. **Router** interacts with **New Session Queue**, **Session Map**, and **Distributor**.
 ```shell
-java -jar selenium-server-<version>.jar router --sessions http://localhost:5556 --distributor http://localhost:5553 --sessionqueue http://localhost:5559
+java -jar selenium-server-<version>.jar router --sessions http://<sessions-ip>:5556 --distributor http://<distributor-ip>:5553 --sessionqueue http://<new-session-queue-ip>:5559 --port 4444
 ```
 
-6. Node(s)
+6. **Node(s)**
 
+Default **Node** port is `5555`.
 ```shell
-java -jar selenium-server-<version>.jar node 
+java -jar selenium-server-<version>.jar node --publish-events tcp://<event-bus-ip>:4442 --subscribe-events tcp://<event-bus-ip>:4443
 ```
 
 ## Metadata in tests