Package: runthis-server
runthis-serverRunThis Server is a tool for serving up unique, interactive terminal sessions over HTTP.
This enables interactive demonstration pages and documentation for a variety of
command-line applications.InstallationRunThis-server may be installed with either conda or pip:# use the conda-forge channel$condainstall-cconda-forgerunthis-server# Or you can use Pip, if you must.$pipinstallrunthis-serverTest UsageYou can start up the server with therunthis-servercommand line utility.$runthis-server--help
usage:runthis-server[-h][--configCONFIG]optionalarguments:-h,--helpshowthishelpmessageandexit--configCONFIGPathtoconfigfileProduction UsageFor production, we recomment usinghypercorn, as the server here is
a Quart application. To use RunThis Server + hypercorn together, run the
following command:$hypercornrunthis.server.hypercorn:appOr if you need to run with HTTPS certificates:$hypercornrunthis.server.hypercorn:app\--certfile/pat/to/certs/fullchain.pem\--keyfile/path/to/certs/privkey.pem\--bind0.0.0.0:80Note:Currently there is no way to pass a path to a config file into the
runthis server when running under hypercorn. The server will just look for
arunthis-server.ymlfile in the current working directory and use that.
If such a file does not exist, the default values will be used! Please
change directory into the location of therunthis-server.ymlfile before
running hypercorn.ConfigurationBy default, the server is configured to run by looking for arunthis-server.ymlfile
in the current working directory. You can pass in a specific configuration file with
the--configflag.All configuration variables are optional. The following lists there meaning and
default values. Usually, these appear as top-level keys in the YAML file:# The path to the public certificate file. This is currently only# used by the hypercorn interface, and is passed directly though# to hypercorn's configuration.certfile:None# The command variable is a string that lists ths command, or path# to run whenever a new instance is requested. Nominally, this is# a command that starts a REPL, but doesn't have to be.command:"python3"# The docker variable is a boolean that determines whether or not# the command should be run in its own single-use docker container.# Docker, of course, must be available on the host.docker:true# The docker_image varible specifies which docker image should be# started up if the command is being run in a docker container.docker_image:"ubuntu:latest"# The host variable is the URL or IP address that the server is# running on. By default, this is "127.0.0.1". Other valid options are# "0.0.0.0", which will expose the server to the outside world, as well# as any valid CNAME or IP address. RunThis Server works by taking in# a request and then redirecting to a new port on this server. The selection# of the host determines the redirection address. Here is the mapping:##  host        -> TTY redirect_base#  127.0.0.1   -> 0.0.0.0#  0.0.0.0     -> IP address of server as seen by https://api.ipify.org#  IP or CNAME -> Same IP or CNAMEhost:"127.0.0.1"# The path to the private certificate file. This is currently only# used by the hypercorn interface, and is passed directly though# to hypercorn's configuration.certfile:None# The port variable is an int that specifies the port number that the# the RunThis Server itself operates on. The TTY redirects go to# separate ports. Therefore you would access the RunThis Server as f"http://{host}:{port}"port:5000# The tty_server variable is a string flag that represents the TTY server software that# will be executed each time a request is made. Currently, the valid options are:##  gotty: go-based TTY server https://github.com/yudai/gotty#  ttyd: C++ TTY server https://tsl0922.github.io/ttyd/tty_server:"gotty"# The gotty_path is the path to the gotty executablegotty_path:"gotty"# The ttyd_path is the path to the ttyd executablettyd_path:"ttyd"# The tty_server_port_start variable is an integer at which the TTY servers# will start serving their terminals. Each successive request increases this# value by one, so that each session recieves its own unique value.tty_server_port_start:8080The above values may also be embedded into a top-levelrunthiskey,
if needed for compatibily with other files. For exmaple,runthis:host:0.0.0.0port:80Request ParametersRequests of the server are be made to the URLf"http://{host}:{port}".
However, this URL accepts either GET or POST requests and takes
the following parameters as options.presetup:This is code that the new interpreter session is initialized.
It is executed without any notification to the user.setup:This is code that is executed right when the interpreter starts
up, after the presetup code is executed. Additionally, this code is echoed
(printed in its source form) to the user prior to being execute. This is
good for running examples.For example, the following GET request would runimport syssilently, and then
executeprint(sys.executable)after printing literally"print(sys.executable)".http://127.0.0.1:5000/?presetup=import+sys&setup=print%28sys.executable%29Usually, you should have a URL encoding library generate these URLs from
source code for you.