2016-05-21 05:20:16 +00:00
|
|
|
#Texttop
|
2016-05-22 15:10:23 +00:00
|
|
|
**A fully interactive X Linux desktop rendered to TTY and streamed over SSH**
|
2016-05-21 05:20:16 +00:00
|
|
|
|
2016-05-21 09:05:24 +00:00
|
|
|
or Firefox in your terminal 😲
|
2016-05-21 05:20:16 +00:00
|
|
|
|
2016-05-22 15:10:23 +00:00
|
|
|
![Alt Text](https://i.imgur.com/jX3vhO4.gif)
|
2016-05-21 08:10:01 +00:00
|
|
|
|
2016-05-22 15:13:31 +00:00
|
|
|
This [Youtube video](https://www.youtube.com/watch?v=TE_D_fx_ut8) gives a more faithful rendition of the experience.
|
|
|
|
|
2016-05-21 08:10:01 +00:00
|
|
|
##Why?
|
|
|
|
I'm travelling around the world and sometimes I don't have very good Internet. If all I have is a 3kbps connection
|
|
|
|
tethered from my phone then it's good to SSH into my server and browse the web through [elinks](http://www.xteddy.org/elinks/).
|
2016-05-21 13:18:06 +00:00
|
|
|
That way my _server_ downloads the web pages and uses the limited bandwidth of my SSH connection to display the result. But
|
2016-05-21 08:10:01 +00:00
|
|
|
it lacks JS support and all that other modern HTML5 goodness. Texttop is simply a way to have the power of a remote
|
|
|
|
server running a desktop, but interfaced through the simplicity of a terminal and very low bandwidth.
|
|
|
|
|
|
|
|
Why not VNC? Well VNC is certainly one solution but it doesn't quite have the same ability to deal with extremely bad
|
2016-05-21 13:18:06 +00:00
|
|
|
Internet. Texttop uses MoSH to further reduce the bandwidth and stability requirements of the connection. Mosh offers features like
|
2016-05-21 08:10:01 +00:00
|
|
|
automatic reconnection of dropped connections and diff-only screen updates. Also, other than SSH or MoSH, Texttop doesn't
|
|
|
|
require a client like VNC. But of course another big reason for Texttop is that it's just very cool geekery.
|
|
|
|
|
|
|
|
##Quickstart
|
|
|
|
If you just want to have a play on your local machine:
|
2016-05-22 03:31:57 +00:00
|
|
|
```
|
|
|
|
docker run --rm -it tombh/texttop sh
|
|
|
|
./run.sh
|
|
|
|
```
|
2016-05-21 08:10:01 +00:00
|
|
|
|
|
|
|
##Installation
|
|
|
|
You can either pull from the Docker Registry:
|
2016-05-21 10:38:36 +00:00
|
|
|
`docker pull tombh/texttop`
|
2016-05-21 08:10:01 +00:00
|
|
|
or, build yourself:
|
|
|
|
```
|
2016-05-22 02:55:54 +00:00
|
|
|
git clone https://github.com/tombh/texttop.git
|
2016-05-21 08:10:01 +00:00
|
|
|
cd texttop
|
|
|
|
docker build -t texttop .
|
|
|
|
```
|
2016-05-22 03:20:12 +00:00
|
|
|
The docker image is only ~275MB.
|
2016-05-21 08:10:01 +00:00
|
|
|
|
2016-05-21 05:20:16 +00:00
|
|
|
##Usage
|
2016-05-21 09:38:46 +00:00
|
|
|
On your remote server (this will pull the docker image the first time you issue it):
|
2016-05-21 08:10:01 +00:00
|
|
|
```
|
2016-05-22 09:29:58 +00:00
|
|
|
docker run -d \
|
2016-05-22 02:19:29 +00:00
|
|
|
-p 7777:7777 -p 60000-60020:60000-60020/udp \
|
2016-05-21 08:10:01 +00:00
|
|
|
-v ~/.ssh/authorized_keys:/root/.ssh/authorized_keys \
|
2016-05-22 09:29:58 +00:00
|
|
|
tombh/texttop
|
2016-05-21 08:10:01 +00:00
|
|
|
```
|
|
|
|
Note that this assumes you already have SSH setup on your server and that you have your public key there. Password
|
2016-05-22 02:19:29 +00:00
|
|
|
logins work fine too. The `60000-60020` port range is for MoSH.
|
2016-05-21 08:10:01 +00:00
|
|
|
|
|
|
|
Then on your local machine:
|
|
|
|
```
|
|
|
|
mosh user@yourserver:7777
|
|
|
|
./run.sh
|
|
|
|
```
|
|
|
|
MoSH is available through most system pacakge managers. SSH can be used exactly the same, just replace `mosh` with `ssh`.
|
|
|
|
`user@yourserver` is the normal URI you would use to connect via SSH.
|
|
|
|
|
2016-05-21 13:18:06 +00:00
|
|
|
**Exiting**
|
2016-05-21 09:38:46 +00:00
|
|
|
At the moment the only way to exit is with MoSH's `CTRL+^ .` or SSH's `ENTER ~ .`
|
|
|
|
|
2016-05-21 08:10:01 +00:00
|
|
|
##Interaction
|
2016-05-23 06:57:46 +00:00
|
|
|
* `CTRL + mousewheel` to zoom
|
|
|
|
* `CTRL + click/drag` to pan
|
|
|
|
|
2016-05-21 08:10:01 +00:00
|
|
|
Most mouse and keyboard input is exactly the same as a normal desktop. If your terminal is active then you can click,
|
|
|
|
type, scroll, use arrow keys and drag things around. However there are still some things not available, like copy and
|
2016-05-23 06:57:46 +00:00
|
|
|
paste. The main difference from a normal desktop is that you can zoom and pan the desktop by using `CTRL + mousewheel` and
|
|
|
|
`CTRL + drag`. This is very handy as it's hard to see what's what when you're zoomed right out.
|
2016-05-21 08:10:01 +00:00
|
|
|
|
|
|
|
Currently, only Firefox is installed on this extremely minimal Alpine Linux distro. However you can add new packages
|
|
|
|
with [apk](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management). Just remember that you will lose any
|
|
|
|
system changes once you restart the docker container. I'm thinking about ways to save state. You may experiment with
|
2016-05-23 06:57:46 +00:00
|
|
|
mounting certain system directories. Example;
|
|
|
|
```
|
|
|
|
# Login with a seperate session
|
|
|
|
apk --no-cache add xterm
|
|
|
|
export DISPLAY=:0
|
|
|
|
xterm &
|
|
|
|
```
|
2016-05-21 09:05:24 +00:00
|
|
|
|
2016-05-22 02:55:54 +00:00
|
|
|
##Known Issues
|
2016-05-22 03:03:06 +00:00
|
|
|
The Docker Hub version is built against Intel CPU architectures, this causes hiptext to fail on AMD chips. In which
|
|
|
|
case you will need to build texttop yourself:
|
2016-05-22 02:55:54 +00:00
|
|
|
```
|
|
|
|
git clone https://github.com/tombh/texttop.git
|
|
|
|
cd texttop
|
|
|
|
docker build -t texttop .
|
|
|
|
```
|
|
|
|
|
2016-05-23 06:57:46 +00:00
|
|
|
**Working terminals**
|
|
|
|
* [Tilda](https://github.com/lanoxx/tilda)
|
|
|
|
* [Terminal](https://launchpad.net/pantheon-terminal)
|
|
|
|
|
|
|
|
**Problematic terminals**
|
|
|
|
* konsole: neither `CTRL+click/drag` nor `CTRL+mousewheel` are forwarded (perhaps mouse reporting is disabled by default)
|
|
|
|
* xterm: `CTRL+click/drag` is intercepted by the GUI window
|
|
|
|
* rxvt: rendering issues
|
|
|
|
|
2016-05-21 09:05:24 +00:00
|
|
|
##Contributions
|
|
|
|
Yes please.
|
2016-05-21 09:38:46 +00:00
|
|
|
|
|
|
|
##License
|
|
|
|
GNU General Public License v3.0
|