To use this project, you need to:

• run the backend
• embed the frontend in your website

Backend

Prerequisites

Before running the backend, either with Docker Compose, or as an Helm Chart, you need to follow the steps below:

• Create a GitHub app to enable GitHub signin.

In GitHub, go to Settings -> developer settings -> OAuth Apps. Create an app with the parameters specified in the screenshot below.

Once the app is created, get the client ID and client secret.

• Create and IAM key with compute role in the Exoscale portal.

Note: this step is needed as the terminal connects to underlying VMs provisioned on the Exoscale cloud provider.

• Create a dedicated ssh key pair.

Note: this step is needed as the backend will use this key to connect to the VMs.

Once the key pair is created, add the public key in your Exoscale account. You'll use the private key below.

Running the backend locally

1. Run the following script to create a new folder, clone the repositories instances, auth, wss and stack inside it.

mkdir w3term && cd w3term
for repo in instances auth wss stack; do
  git clone git@github.com:w3term/$repo
done

Then, go into the stack folder.

2. Set the client ID and client secret in the github-apps.yaml file.

3. Copy the private key in ssh.key.

4. Run the backend part with Docker Compose.

cd stack
docker compose up -d

Note: you can remove the application using docker compose down.

Running the backend in Kubernetes

0. Prerequisites

Make sure cert-manager is installed in the cluster before deploying the application. Install Helmfile as this is a very convenient way to deploy Helm chart.

1. Clone the helm repository.

git clone https://github.com/w3term/helm.git
cd helm

2. Modify values.yaml according to your needs.

3. verify the templates are correctly rendered.

helmfile templates

4. Deploy the application.

helmfile apply

Note: you can remove the application using helmfile destroy.

Frontend

Once the backend is deployed, you can import the following script into your website, replacing the placeholders with the details of the GitHub application.

<script src="https://cdn.jsdelivr.net/npm/@w3term/terminal@latest/terminal.min.js"></script>
<script>
const terminal = new WebTerminalEmbed({
    githubAppName: 'your-app-name',
    githubClientId: 'your-client-id',
    backendDomain: 'your-domain.com'
});
</script>

Status

This is still a work in progress (even if this terminal is already functional).
More documentation and examples will be added soon.