From 6d95aec28cd9ebfd203094b99160c5ffce405194 Mon Sep 17 00:00:00 2001 From: Craig Date: Wed, 29 Jan 2020 01:28:27 +0000 Subject: [PATCH] basic documentation --- README.md | 41 +++++++++++++++++++++++------------- client/ABOUT.md | 9 ++++---- client/README.md | 15 ++++++++++++- server/README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 98 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 88021b5f..dde18f7f 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,17 @@ # **n**.eko - This app uses Web RTC to stream a desktop inside of a docker container, I made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and my internet can't handle streaming and discord keeps crashing. I just want to watch anime with my friends ლ(ಠ益ಠლ) so I started digging throughout the net and found a few *kinda* clones, but non of them had the virtual browser, then I found [Turtus](https://github.com/Khauri/Turtus) and I was able to figure out the rest. This is by no means a fully featured clone of rabbit, it hs only *one* room. Its stateless, so no saved user names or passwords. + This app uses Web RTC to stream a desktop inside of a docker container, I made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and my internet can't handle streaming and discord keeps crashing when my friend attempts to. I just want to watch anime with my friends ლ(ಠ益ಠლ) so I started digging throughout the internet and found a few *kinda* clones, but none of them had the virtual browser, then I found [Turtus](https://github.com/Khauri/Turtus) and I was able to figure out the rest. This is by no means a fully featured clone of rabbit, it hs only *one* room. It's stateless, so no saved user names or passwords. -### Why n.eko? -I like cats (Neko is the Japanese word for cat), I'm a weeb/nerd +### Why **n**.eko? +I like cats 🐱 (`Neko` is the Japanese word for cat), I'm a weeb/nerd -### Why the cat butt? -Because cats are *assholes*, but you love them anyways... +***But why the cat butt?*** Because cats are *assholes*, but you love them anyways. ### Super easy mode setup -1. Deploy a Server/VPS +1. Deploy a server or VPS - *Recommended Specs:* (Note: these may not be correct, I did a small round testing, 4c/4gb worked fine with small hickups here and there) + *Recommended Specs:* | Resolution | Cores | Ram | Recommendation | |------------|-------|-------|------------------| @@ -26,8 +25,10 @@ Because cats are *assholes*, but you love them anyways... | **720p** | 4 | 4gb | Good Performance | | **720p** | 6 | 4-6gb | Recommended | | **720p+** | 8 | 8gb+ | Best Performance | + + ***Why are the specs so high?*** : If you think about it, you have to run a full desktop, a browser (a resource hog on its own) *and* encode/transmit the desktop, there's a lot going on and so it demands some power. -2. [SSH into your box](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/) +2. [Login via SSH](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/) 3. Install Docker ``` @@ -41,16 +42,16 @@ Because cats are *assholes*, but you love them anyways... ``` 5. Visit the IP address of the droplet in your browser and login, the default password is `neko` -> *Protip*: Run `nano docker-compose.yaml` to edit the settings, then press *ctrl+x* to exit and save the file. +> 💡 **Protip**: Run `nano docker-compose.yaml` to edit the settings, then press *ctrl+x* to exit and save the file. ### Running the container: ``` sudo docker run -p 8080:8080 -e NEKO_PASSWORD='secret' -e NEKO_ADMIN='secret' --shm-size=1gb nurdism/neko:latest ``` -*Note:* `--shm-size=1gb` is required, firefox-esr tabs will crash +*Note:* `--shm-size=1gb` is required, firefox tabs will crash, not sure what it does to be honest 😅 -### Config +### Docker Basic Configuration ``` SCREEN_WIDTH=1280 // Display width SCREEN_HEIGHT=720 // Display height @@ -63,11 +64,21 @@ NEKO_BIND=0.0.0.0:8080 // Bind NEKO_KEY= // (SSL)Key, needed for clipboard sync NEKO_CERT= // (SSL)Cert, needed for clipboard sync ``` +for full documentation on configuring the server [go here](./server/README.md) ### Development -*Highly* recommend you use a [dev container](https://code.visualstudio.com/docs/remote/containers) for [vscode](https://code.visualstudio.com/), I've included the `.devcontainer` I've used to develop this app. To build neko run: -`cd .docker && ./build` +*Highly* recommend you use a [dev container](https://code.visualstudio.com/docs/remote/containers) for [vscode](https://code.visualstudio.com/), I've included the `.devcontainer` I've used to develop this app. To build **n**.eko docker container run: +``` +cd .docker && ./build +``` +the `.docker` folder also contains `./test` bash script which will launch a desktop with a browser for testing out any changes with the server. + +To run the client with hot loading (for development of new client features) +``` +cd ./client && npm run serve +``` ### Non Goals - * Turning n.eko into a service that serves multiple rooms and browsers/desktops. - * Voice chat, use [Discord](https://discordapp.com/)) \ No newline at end of file +* Turning n.eko into a service that serves multiple rooms and browsers/desktops. +* Supporting multiple platforms +* Voice chat, use [Discord](https://discordapp.com/) \ No newline at end of file diff --git a/client/ABOUT.md b/client/ABOUT.md index 8e335359..0b635e2e 100644 --- a/client/ABOUT.md +++ b/client/ABOUT.md @@ -3,11 +3,10 @@ # **n**.eko - This app uses Web RTC to stream a desktop inside of a docker container, I made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and my internet can't handle streaming and discord keeps crashing. I just want to watch anime with my friends ლ(ಠ益ಠლ) so I started digging throughout the net and found a few *kinda* clones, but non of them had the virtual browser, then I found [Turtus](https://github.com/Khauri/Turtus) and I was able to figure out the rest. This is by no means a fully featured clone of rabbit, it hs only *one* room. Its stateless, so no saved user names or passwords. + This app uses Web RTC to stream a desktop inside of a docker container, I made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and my internet can't handle streaming and discord keeps crashing when my friend attempts to. I just want to watch anime with my friends ლ(ಠ益ಠლ) so I started digging throughout the internet and found a few *kinda* clones, but none of them had the virtual browser, then I found [Turtus](https://github.com/Khauri/Turtus) and I was able to figure out the rest. This is by no means a fully featured clone of rabbit, it hs only *one* room. It's stateless, so no saved user names or passwords. -### Why n.eko? -I like cats (Neko is the Japanese word for cat), I'm a weeb/nerd +### Why **n**.eko? +I like cats 🐱 (`Neko` is the Japanese word for cat), I'm a weeb/nerd -### Why the cat butt? -Because cats are *assholes*, but you love them anyways... +***But why the cat butt?*** Because cats are *assholes*, but you love them anyways. diff --git a/client/README.md b/client/README.md index 04b4fc21..58f99497 100644 --- a/client/README.md +++ b/client/README.md @@ -1 +1,14 @@ -# n.eko Client +# **n**.eko client +Web client for n.eko + +### Environment +------ +``` +VUE_APP_SERVER_PORT // development server port +``` + +### Building +------ +``` +npm install && npm run build +``` diff --git a/server/README.md b/server/README.md index d314c981..1e9ccfdf 100644 --- a/server/README.md +++ b/server/README.md @@ -1 +1,54 @@ -# n.eko Server +# **n**.eko server +Server for n.eko, as of right now this will *only* work on Linux systems, only tested on Debian based distros. + +### Configuration +------ +``` +--debug // (bool) enable debug mode +--logs // (bool) save logs to file +--config "" // (string) configuration file path +--bind "127.0.0.1:8080" // (string) address/port/socket to serve neko +--cert "" // (string) path to the SSL cert used to secure the neko server +--key "" // (string) path to the SSL key used to secure the neko server +--static "./www" // (string) path to neko client files to serve +--device "auto_null.monitor" // (string) audio device to capture +--display ":99.0" // (string) XDisplay to capture +--aduio "" // (string) audio codec parameters to use for streaming (unused) +--video "" // (string) video codec parameters to use for streaming (unused) +--epr "59000-59100" // (string) limits the pool of ephemeral ports that ICE UDP connections can allocate from +--vp8 // (bool) use VP8 video codec +--vp9 // (bool) use VP9 video codec +--h264 // (bool) use H264 video codec +--opus // (bool) use Opus audio codec +--g722 // (bool) use G722 audio codec +--pcmu // (bool) use PCMU audio codec +--pcma // (bool) use PCMA audio codec +--password "neko" // (string) password for connecting to stream +--admin "admin" // (string) admin password for connecting to stream +``` + +Config can be set via environment variables with the prefix `NEKO_` (I.E. NEKO_BIND="127.0.0.1:8080") + +### Requirements +------ +Runtime: +``` +gstreamer1.0-plugins-base // opus plugin +gstreamer1.0-plugins-good // pulseaudio, ximagesrc & vpx plugins +gstreamer1.0-plugins-bad // openh264 plugin (build from source) +gstreamer1.0-plugins-ugly // x264 plugin +gstreamer1.0-pulseaudio // pulseaudio plugin +xclip // clipboard sync +libxtst6 // keyboard and mouse input +``` + +Development: +``` +libxtst-dev +``` + +### Building +------ +``` +./build +```