added a picture to the about page.

integrationtest/integration_test.go

@@ -157,6 +157,9 @@ func (s *IntegrationTestSuite) defineContainer(net *testcontainers.DockerNetwork
 			WaitingFor:     wait.ForLog(waitForLog).WithStartupTimeout(10 * time.Second),
 			LogConsumerCfg: createLogConsumerConfig(hostname),
 			Networks:       []string{net.Name},
+			//NetworkAliases: map[string][]string{
+			//	net.Name: []string{hostname},
+			//},
 		},
 		Started: false,
 	}

pkg/server/ui/about.templ

@@ -24,42 +24,39 @@ templ About() {
 
       <h2>how it works</h2>
 
-      <p>
+      The basic principle of converge is described below. Access to a running remote continous integration
-          The steps involved are as follows:
+      job is usually not possible without a lot of access to the backend environment where jobs are running.
-          <ul>
+      However, the job can connect to a server as well as the client. The connection between
-          <li>The agent connects to converge server and specifies an id, the so-called rendez-vous id,
+      client and agent is established as follows:
-              identifying the agent.
-              The agent outputs an example command that can be used to connect to this agent.
-          </li>
-          <li>The agent sets up multiplexing of connections together with converge server
-              which allows it to listen on incoming connections.
-          </li>
-          <li>This is used by the agent for running an embedded SSH server that is listening for
-              incoming connection requests from clients.
-          </li>
-          <li>The client/user connects to the converge server using the command specified by the agent.
-              This uses the same id as that used by the agent. The converge server can now match these
-              ids an set up an end-to-end connection from client to agent. The role of converge server
-              is simply in matching these ids and connecting the two websocket connections (from agent
-              and from client) together by copying data between them as it arrives.
-          </li>
-          <li>The embedded SSH server now performs authentication, after successful login,
-              a shell is spawned and the session is established. The shell can be any linux
-              shell but also command prompt and powershell are possible.
-              The connection is practically identical to a regular terminal connection. To
-              achieve this, the shell is made to beiieve that it is connected to a
-              terminal.
-          </li>
-          </ul>
-      </p>
-
-      <p>With regards to the rendez-vous id there are the following remarks:
       <ul>
-        <li> If no id is specified than an id is generated. </li>
+          <li>(1): the agent, started by the continuous integration job, connects to converge server through a websocket, this establishes a connection that
-        <li> If the agent uses an id already in use by another agent, then converge server will
+          is  similar to a TCP connection to converge server. In connecting, the agent specifies a
-             generate a new id. </li>
+          rendez-vous id. After connecting, the agenta and ocnverge server using multiplexing of connections
+          over a single connection, allowing the agent to run an embedded SSH server and listen for incoming
+          connections, just like normally is done with a TCP listener. </li>
+          <li>(2): the client connects to converge server through SSH and also specifies the same rendez-vous id.
+          The connection from client to converge server is done through a helper program <code>wsproxy</code>
+          that is used as a proxy command for SSH allowing SSH to connect to the websocket. Using wsproxy, the
+          rendez-vous id is passed to the server. </li>
+          <li>(3): converge server connects the two connections after matching them based on the rendez-vous id.
+          The role of converge server is imply in forwarding data. </li>
+          <li>(4): the agent runs an embedded SSH server and incoming connections to the agent are handed over to
+             that server. That server in turn spawns a shell (bash, cmd.exe, powershell.exe) and connects it to the
+             SSH session. At that momenmt an end-to-end SSH session is established and the user can perform interactive
+             commands. </li>
       </ul>
-      The agent will always print the id and command required to connect to it to standard output.
+
+      <div>
+      <img src="../static/images/converge.svg"/>
+      </div>
+
+      <p>There are a few special situations:
+      <ul>
+        <li> If no id is specified than a rendez-vous id is generated. </li>
+        <li> If the agent uses an id already in use by another agent, then converge server will
+             generate a new rendez-vous id. </li>
+      </ul>
+      The agent will always print the rendez-vous id and command required to connect to it.
       </p>
 
       <h2>security</h2>