{"id":17355218,"url":"https://github.com/zephinzer/cloudshell","last_synced_at":"2025-08-22T05:32:22.881Z","repository":{"id":37665875,"uuid":"365217029","full_name":"zephinzer/cloudshell","owner":"zephinzer","description":"Xterm.js with a Go backend meant for use in containers","archived":false,"fork":false,"pushed_at":"2023-05-29T13:34:57.000Z","size":1771,"stargazers_count":134,"open_issues_count":8,"forks_count":40,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-28T05:32:28.524Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zephinzer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-07T11:51:01.000Z","updated_at":"2024-11-21T03:11:09.000Z","dependencies_parsed_at":"2022-09-15T08:50:29.775Z","dependency_job_id":null,"html_url":"https://github.com/zephinzer/cloudshell","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fcloudshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fcloudshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fcloudshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fcloudshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zephinzer","download_url":"https://codeload.github.com/zephinzer/cloudshell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230561014,"owners_count":18245324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T17:42:39.211Z","updated_at":"2024-12-20T09:07:27.008Z","avatar_url":"https://github.com/zephinzer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloudshell\n\n[![License](https://img.shields.io/github/license/zephinzer/cloudshell)](https://github.com/zephinzer/cloudshell/blob/master/LICENSE)\n[![Docker Image Version (latest by date)](https://img.shields.io/docker/v/zephinzer/cloudshell)](https://hub.docker.com/r/zephinzer/cloudshell)\n[![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/zephinzer/cloudshell)](https://github.com/zephinzer/cloudshell)\n[![pipeline status](https://gitlab.com/zephinzer/cloudshell/badges/master/pipeline.svg)](https://gitlab.com/zephinzer/cloudshell/-/commits/master)\n\nThis project contains an Xterm.js frontend that connets to a Go backend to provide a shell to the host system. Basically, access your shell from a browser.\n\n![Screengrab of demo](./docs/demo.gif)\n\nSome use cases I had:\n\n1. Deploy to a compute instance in your networks and expose it when needed to gain shell access to your network over the browser\n2. Deploy to a Kubernetes cluster with appropriate (Cluster)Role and (Cluster)RoleBinding resources to allow some level of access to developers\n3. Exposing a CLI tool (see [`./examples/k9s`](./examples/k9s) for an example) over the browser. Think CLI-as-a-frontend\n4. Doing a demo for a CLI tool over the browser\n\n**Table of Contents**\n\n- [Cloudshell](#cloudshell)\n- [Development](#development)\n  - [Install dependencies](#install-dependencies)\n  - [Test run it](#test-run-it)\n- [Build/Release](#buildrelease)\n  - [Building the project](#building-the-project)\n  - [Creating the Docker image](#creating-the-docker-image)\n  - [Publishing the Docker image](#publishing-the-docker-image)\n  - [Publishing example Docker images](#publishing-example-docker-images)\n- [Usage/Configuration](#usageconfiguration)\n  - [Cloudshell CLI tool](#cloudshell-cli-tool)\n- [Deploy](#deploy)\n  - [Running the Docker image](#running-the-docker-image)\n  - [Deploying via Helm](#deploying-via-helm)\n- [CI/CD](#cicd)\n- [License](#license)\n\n# Development\n\n## Install dependencies\n\nRun `make init` to install both Node.js and Golang dependencies.\n\n## Test run it\n\nRun `make start` to start the Go backend which will also serve the static files for the website.\n\nOpen your browser at http://localhost:8376 to view your shell in the browser.\n\n# Build/Release\n\n## Building the project\n\nTo build this project, run `make build` to build the binary\n\n## Creating the Docker image\n\nRun `make package` to create the Docker image. To customise the package process:\n\n1. Create a file named `Makefile.properties` (this will be `-include`d by the Makefile)\n2. Set `image_namespace` to your desired namespace (defaults to `zephinzer`)\n3. Set `image_name` to your desired image name (defaults to `cloudshell`)\n4. Set `image_tag` to your desired tag (defaults to the first 8 characters of the Git commit hash)\n\n## Publishing the Docker image\n\nRun `make publish` to publish the Docker image. Same customisations as above apply.\n\n## Publishing example Docker images\n\nRun `make publish-example id=${id}` to publish the example Docker images where `${id}` is the directory name of the directory in the [`./examples` directory](./examples).\n\n# Usage/Configuration\n\n## Cloudshell CLI tool\n\nConfigurations can be set via flags or environment variables. To view available configurations in your binary instance, run `cloudshell --help`. Otherwise, flags and environment variables follow a rule of `kebab-lower-case` for flags and `SNAKE_UPPER_CASE` for environment variables.\n\n| Configuration | Flag | Environment Variable | Default Value | Description |\n| --- | --- | --- | --- | --- |\n| Allowed hostnames | `--allowed-hostnames` | `ALLOWED_HOSTNAMES` | `\"localhost\"` | Comma delimited list of hostnames that are allowed to connect to the websocket |\n| Arguments | `--arguments` | `ARGUMENTS` | `\"-l\"` | Comma delimited list of arguments that should be passed to the target binary |\n| Command | `--command` | `COMMAND` | `\"/bin/bash\"` | Absolute path to the binary to run |\n| Connection error limit | `--connection-error-limit` | `CONNECTION_ERROR_LIMIT` | `10` | Number of times a connection should be re-attempted by the server to the XTerm.js frontend before the connection is considered dead and shut down |\n| Keepalive ping timeout | `--keepalive-ping-timeout` | `KEEPALIVE_PING_TIMEOUT` | `20` | Maximum duration in seconds between a ping and pong message to tolerate |\n| Maximum buffer size in bytes | `--max-buffer-size-bytes` | `MAX_BUFFER_SIZE_BYTES` | `512` | Maximum length of input from the browser terminal |\n| Log format | `--log-format` | `LOG_FORMAT` | `\"text\"` | Format with which to output logs, one of `\"json\"` or `\"text\"` |\n| Log level | `--log-level` | `LOG_LEVEL` | `\"debug\"` | Minimum level of logs to output, one of `\"trace\"`, `\"debug\"`, `\"info\"`, `\"warn\"`, `\"error\"` |\n| Liveness probe path | `--path-liveness` | `PATH_LIVENESS` | `\"/healthz\"` | Path to liveness probe handler endpoint |\n| Metrics probe path | `--path-metrics` | `PATH_METRICS` | `\"/metrics\"` | Path to metrics endpoint |\n| Readiness probe path | `--path-readiness` | `PATH_READINESS` | `\"/readiness\"` | Path to readiness probe handler endpoint |\n| Xterm.js path | `--path-xtermjs` | `PATH_XTERMJS` | `\"/xterm.js\"` | Path to xterm.js websocket endpoint |\n| Server address | `--server-address` | `SERVER_ADDRESS` | `\"0.0.0.0\"` | IP interface the server should listen on |\n| Server port | `--server-port` | `SERVER_PORT` | `8376` | Port the server should listen on |\n| Working directory | `--workdir` | `WORKDIR` | `\".\"` | Path to the working directory that Cloudshell should use |\n\n# Deploy\n\n## Running the Docker image\n\nRun `make run` to run the Docker image locally\n\n## Deploying via Helm\n\nGo to [`./deploy/cloudshell`](./deploy/cloudshell) and run `helm install --values ./values.yaml --set-url url=cloudshell.yourdomainname.com cloudshell .`. Replace `cloudshell.yourdomainname.com` with your own domain name. You could also set the `url` property inside the `./values.yaml` file.\n\n# CI/CD\n\nThe following environment variables should be set in the CI pipeline:\n\n| Key | Example | Description |\n| --- | --- | --- |\n| `DOCKER_REGISTRY_URL` | `\"docker.io\"` | URL of the Docker registry to push the image to |\n| `DOCKER_REGISTRY_USER` | `\"zephinzer\"` | User to identify with for the registry at `DOCKER_REGISTRY_URL` |\n| `DOCKER_REGISTRY_PASSWORD` | `\"p@ssw0rd\"` | Password for the user identified in `DOCKER_REGISTRY_USER` for the registry at `DOCKER_REGISTRY_URL` |\n\n# License\n\nThis project is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fcloudshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzephinzer%2Fcloudshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fcloudshell/lists"}