erik/converge
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs page now working again.

Browse Source
This commit is contained in:
Erik Brakkee 2024-07-29 19:49:47 +02:00
parent fb8ed0622b
commit f5135aecdc
6 changed files with 51 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Dockerfile
View File

@ -18,7 +18,7 @@ COPY --from=builder /opt/converge/bin/agent \
/opt/converge/bin/agent.exe \ /opt/converge/bin/agent.exe \
/opt/converge/bin/tcptows.exe \ /opt/converge/bin/tcptows.exe \
/opt/converge/bin/wsproxy.exe \ /opt/converge/bin/wsproxy.exe \
/opt/converge/docs/ /opt/converge/static/
COPY --from=builder /opt/converge/static/ /opt/converge/docs/ COPY --from=builder /opt/converge/static/ /opt/converge/static/
ENTRYPOINT ["/opt/converge/bin/converge", "-d", "/opt/converge/docs" ] ENTRYPOINT ["/opt/converge/bin/converge", "-d", "/opt/converge/static" ]

5
cmd/converge/converge.go
View File

@ -132,8 +132,9 @@ func main() {
http.HandleFunc("/client/", clientService.Handle) http.HandleFunc("/client/", clientService.Handle)
// create filehandler with templating for html files. // create filehandler with templating for html files.
fileHandler := NewFileHandler(downloadDir) http.Handle("/docs/", http.StripPrefix("/docs/", http.HandlerFunc(pageHandler)))
http.Handle("/docs/", http.StripPrefix("/docs/", fileHandler)) http.Handle("/static/", http.StripPrefix("/static/",
http.FileServer(http.Dir(downloadDir))))
http.HandleFunc("/", catchAllHandler) http.HandleFunc("/", catchAllHandler)
// Start HTTP server // Start HTTP server

37
cmd/converge/pagehandler.go Normal file
View File

@ -0,0 +1,37 @@
package main
import (
"converge/pkg/templates"
"net/http"
"os"
"strings"
)
func pageHandler(w http.ResponseWriter, r *http.Request) {
secure := ""
if r.TLS == nil {
secure = ""
} else {
secure = "s"
}
for _, header := range []string{"X-Forwarded-Proto", "X-Scheme", "X-Forwarded-Scheme"} {
values := r.Header.Values(header)
for _, value := range values {
if strings.ToLower(value) == "https" {
secure = "s"
}
}
}
username, _ := os.LookupEnv("CONVERGE_USERNAME")
switch r.URL.Path {
case "":
fallthrough
case "/":
fallthrough
case "/index.html":
templates.Index(secure, r.Host, username).Render(r.Context(), w)
default:
http.NotFound(w, r)
}
}

4
pkg/templates/basepage.templ
View File

@ -6,14 +6,14 @@ templ BasePage() {
<html lang="en"> <html lang="en">
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<link rel="stylesheet" href="../css/bootstrap.min.css" <link rel="stylesheet" href="../static/css/bootstrap.min.css"
crossorigin="anonymous"> crossorigin="anonymous">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>Converge</title> <title>Converge</title>
</head> </head>
<body> <body>
<script src="../js/bootstrap.bundle.min.js" <script src="../static/js/bootstrap.bundle.min.js"
crossorigin="anonymous"></script> crossorigin="anonymous"></script>
<div class="container-fluid"> <div class="container-fluid">

12
pkg/templates/downloads.templ
View File

@ -18,21 +18,21 @@ templ Downloads() {
<tr> <tr>
<td>agent</td> <td>agent</td>
<td>The agent to run inside aa CI job</td> <td>The agent to run inside aa CI job</td>
<td><a href="downloads/agent">agent</a></td> <td><a href="../static/agent">agent</a></td>
<td><a href="docs/agent.exe">agent.exe</a></td> <td><a href="../static/agent.exe">agent.exe</a></td>
</tr> </tr>
<tr> <tr>
<td>wsproxy</td> <td>wsproxy</td>
<td>SSH proxy command that can be directly used by ssh</td> <td>SSH proxy command that can be directly used by ssh</td>
<td><a href="docs/wsproxy">wsproxy</a></td> <td><a href="../static/wsproxy">wsproxy</a></td>
<td><a href="docs/wsproxy.exe">wsproxy.exe</a></td> <td><a href="../static/wsproxy.exe">wsproxy.exe</a></td>
</tr> </tr>
<tr> <tr>
<td>tcptows</td> <td>tcptows</td>
<td>TCP to WS tunnel for allowing regular <td>TCP to WS tunnel for allowing regular
SSH and SFTP clients to connect to converge</td> SSH and SFTP clients to connect to converge</td>
<td><a href="docs/tcptows">tcptows</a></td> <td><a href="../static/tcptows">tcptows</a></td>
<td><a href="docs/tcptows.exe">tcptows.exe</a></td> <td><a href="../static/tcptows.exe">tcptows.exe</a></td>
</tr> </tr>
</table> </table>
</div> </div>

211
static/index.html
View File

@ -1,211 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="css/bootstrap.min.css"
crossorigin="anonymous">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>Converge</title>
</head>
<body>
<script src="js/bootstrap.bundle.min.js"
crossorigin="anonymous"></script>
<div class="container-fluid">
<div class="row">
<div class="col">
<div class="container">
<h1>About</h1>
<p>
Converge is a utility for troubleshooting builds on continuous integration servers.
It solves a common problem where the cause of job failure is difficult to determine.
This is complicated further by the fact that build jobs are usually run on a build
farm where there is no access to the build agents or in more modern envrionments when
jobs are run in ephemeral containers.
</p>
<p>
With Converge it is possible to get remote shell access to such jobs. This works
by configuring the build job to connect to a Converge server using an agent program.
The agent program can be downloaded from within the CI job using curl or wget.
Next, an end-user can connect to the Converge server, a rendez-vous server, that connects
the client and server together.
</p>
<p>
The setup is such that the connection from client (end-user) to server (agent on CI job)
is end-to-end encrypted. The Converge server itself is no more than a bitpipe which pumps
data between client and agent.
</p>
<p>
Both ssh and sftp are supported. Multiple shells are also allowed.
</p>
<p>
There is a timeout mechanism in the agent such that jobs do not hang indefinitely waiting
for a connection. This mechanism is useful to make sure build agents do not keep
build agents occupied for a long time. By default, the agent exits with status 0 when
the first client exits after logging in. This behavior as well as general expiry can be
controlled from within a shell session by touching a .hold file. After logging in, the
user can control expiry of the session as instructed by messages in the ssh session.
When the timeout of a session is near the user is informed about this with messages
in the shell.
</p>
<h1>Usage</h1>
<h2>Continous integration jobs</h2>
<p>
In a continous integration job, download the agent, chmod it and run it.
</p>
<pre>
# linux
curl http{{.secure}}://{{.host}}/docs/agent > agent
chmod 755 agent
./agent --id ID ws{{.secure}}://{{.host}}
# windows
curl http{{.secure}}://{{.host}}/docs/agent.exe > agent.exe
agent --id ID ws{{.secure}}://{{.host}}
</pre>
<p>
Above, ID is a unique id for the job, the so-called rendez-cous ID. This should not conflict with IDs
used by other agents. The ID is used for a rendez-vous between the end-user on a local system and
the continuous integration job running on a build agent. If you don't specify an id, a random
id will be generated.
The agent to the converge server and tells it the ID. Clients can now connect to the Converge
server to establish a connection to the CI job through converge by also specifying the same
ID.
Communication between
end-user and agent is encrypted using SSH and the rendez-vous server is unable to
read the contents. The rendez-vous server is nothing more then a glorified bit pipe,
simply transferring data between end-user SSH client and the agent which runs an
embedded SSH server.
</p>
<p>
NOTE: When running the agent on windows, an exit of the remote session using
exit in powershell or command prompt does not terminate the shell completely.
To terminate the client ssh session must be killed by closing the terminal.
Cleanup of remote processes on the agent appears to work properly despite this
problem. It is just that exit of the windows shell (powershell or command prompt)
is not detected properly.
</p>
<p>
The agent has more options, download the agent and run it without arguments to
see all options.
</p>
<h2>Local clients: using ssh with a proxy command </h2>
<p><code>wsproxy</code> is a command that can be used as a proxy command for SSH which performs the connection to the
remote server. This command needs to be downloaded only once (see <a href="#downloads">downloads</a> below). It does not depend on
the converge implementation but only on the websocket standards. Other tools that
provide a mapping of stdio to a websocket can also be used instead of wsproxy.
</p>
<p>
Next step is to run a local SSH or SFTP client:
</p>
<pre>
ssh -oServerAliveInterval=10 -oProxyCommand="wsproxy ws{{.secure}}://{{.host}}/client/ID" {{ .username }}@@localhost
sftp -oServerAliveInterval=10 -oProxyCommand="wsproxy ws{{.secure}}://{{.host}}/client/ID" {{ .username }}@@localhost
</pre>
<h2>Local clients: using SSH with a local TCP forwarding proxy</h2>
<p>
This option is less convenient than the proxy command because it requires two separate
commands to execute.
</p>
<p>
Local clients can connect using regular ssh and sftp commands through a tunnel that
translates a local TCP port to a websocket connection in converge. See
the <a href="#downloads">downloads</a> section.
This runs a local client that allows SSH to port 10000 and connects to converge using
a websocket connection.
</p>
<p>
Next step is to run a local SSH of SFTP client:
</p>
<pre>
ssh -oServerAliveInterval=10 -p 10000 {{ .username }}@@localhost
sftp -oServerAliveInterval=10 -oPort=10000 {{ .username }}@@localhost
</pre>
<h2>Authentication</h2>
<p>
The <code>{{ .username }}</code> user above the Converge server and
communicated to the agent when the agent is started. This is the
username that must be used when setting up an ssh connection.
Another way to authenticate is through an .authorized_keys file in the
same directory as where the agent is started.
This can be setup as follows before starting the agent:
</p>
<pre>
# linux
echo "ssh-rsa dkddkdkkk a@b.c" > .authorized_keys
echo "ssh-rsa adfadjfdf d@e.f" >> .authorized_keys
# windows
echo ssh-rsa dkddkdkkk a@b.c > .authorized_keys
echo ssh-rsa adfadjfdf d@e.f >> .authorized_keys
</pre>
<p>
Note that on windows you should not used quotes.
</p>
<h1 id="downloads">Downloads</h1>
<table class="table">
<thead>
<tr>
<th>Component</th>
<th>Purpose</th>
<th>Linux</th>
<th>Windows</th>
</tr>
</thead>
<tr>
<td>agent</td>
<td>The agent to run inside aa CI job</td>
<td><a href="/docs/agent">agent</a></td>
<td><a href="/docs/agent.exe">agent.exe</a></td>
</tr>
<tr>
<td>wsproxy</td>
<td>SSH proxy command that can be directly used by ssh</td>
<td><a href="/docs/wsproxy">wsproxy</a></td>
<td><a href="/docs/wsproxy.exe">wsproxy.exe</a></td>
</tr>
<tr>
<td>tcptows</td>
<td>TCP to WS tunnel for allowing regular
SSH and SFTP clients to connect to converge</td>
<td><a href="/docs/tcptows">tcptows</a></td>
<td><a href="/docs/tcptows.exe">tcptows.exe</a></td>
</tr>
</table>
</div>
</div>
</div>
</div>
</body>
</html>