diff --git a/.github/actions/build_and_publish_image/action.yaml b/.github/actions/build_and_publish_image/action.yaml index 7f158fa7..4bade508 100644 --- a/.github/actions/build_and_publish_image/action.yaml +++ b/.github/actions/build_and_publish_image/action.yaml @@ -2,7 +2,7 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. -name: Build & publish image +name: Build and publish image inputs: build_args: diff --git a/.github/workflows/build_and_publish_all_images.yaml b/.github/workflows/build_and_publish_all_images.yaml index a93138f6..990592f2 100644 --- a/.github/workflows/build_and_publish_all_images.yaml +++ b/.github/workflows/build_and_publish_all_images.yaml @@ -2,7 +2,7 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. -name: Build & publish all images +name: Build and publish all images on: workflow_dispatch: diff --git a/.github/workflows/build_and_publish_changed_images.yaml b/.github/workflows/build_and_publish_changed_images.yaml index 8fbc02ed..8dbcb8d0 100644 --- a/.github/workflows/build_and_publish_changed_images.yaml +++ b/.github/workflows/build_and_publish_changed_images.yaml @@ -2,7 +2,7 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. -name: Build & publish changed images +name: Build and publish changed images on: workflow_dispatch: diff --git a/.github/workflows/build_and_publish_documentation.yaml b/.github/workflows/build_and_publish_documentation.yaml new file mode 100644 index 00000000..374d2340 --- /dev/null +++ b/.github/workflows/build_and_publish_documentation.yaml @@ -0,0 +1,45 @@ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, You can obtain one at https://mozilla.org/MPL/2.0/. + +name: Build and publish documentation + +on: + workflow_dispatch: + push: + branches: [ main ] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + path: docs + - name: Setup python for mkdocs + uses: actions/setup-python@v5 + with: + python-version: 3.x + - name: Generate MkDocs static files + run: | + pip install --no-cache-dir --force-reinstall mkdocs-material + mkdir -pm755 /opt/mkdocs + mkdocs build --strict --verbose --site-dir /opt/mkdocs + - uses: actions/upload-pages-artifact@v3 + with: + path: /opt/mkdocs/ + retention-days: 1 + + publish: + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/build_and_publish_release.yaml b/.github/workflows/build_and_publish_release.yaml index 01c36db0..de536226 100644 --- a/.github/workflows/build_and_publish_release.yaml +++ b/.github/workflows/build_and_publish_release.yaml @@ -2,7 +2,7 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. -name: Publish release +name: Build and publish release on: workflow_dispatch: diff --git a/.github/workflows/devcontainer_feature_release.yaml b/.github/workflows/devcontainer_feature_release.yaml index 7b66d900..17c8ce3f 100644 --- a/.github/workflows/devcontainer_feature_release.yaml +++ b/.github/workflows/devcontainer_feature_release.yaml @@ -2,7 +2,7 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. -name: "Release devcontainer features & Generate documentation" +name: Release devcontainer features on: workflow_dispatch: diff --git a/.github/workflows/devcontainer_feature_validate.yaml b/.github/workflows/devcontainer_feature_validate.yaml index aa27818e..50587fbb 100644 --- a/.github/workflows/devcontainer_feature_validate.yaml +++ b/.github/workflows/devcontainer_feature_validate.yaml @@ -2,7 +2,7 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. -name: "Validate devcontainer-feature.json files" +name: Validate devcontainer-feature.json files on: pull_request: diff --git a/README.md b/README.md index 8069cd69..f38a9bc9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Selkies WebRTC](/logo/horizontal-480.png) +![Selkies WebRTC](/docs/assets/logo/horizontal-480.png) [![Build](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml/badge.svg)](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml) @@ -15,26 +15,3 @@ Selkies-GStreamer is designed for researchers, including people in the graphical While designed for clustered or unprivileged containerized environments, Selkies-GStreamer can also be deployed in desktop computers, and any performance issue that would be problematic in cloud gaming platforms is also considered a bug. **[Read the Documentation](/docs/README.md) to get started.** - -## Citations in Academic Publications - -> **NOTE: This section is also applicable for developers applying, embedding, forking, deriving, or taking influence from this project.** - -**Citations are the currency of scientific research. Citing in your publications is the main driver of keeping this project alive.** - -Remote desktop software projects have always been primarily proprietary. It is difficult to maintain such a project without consistent full-time compensation or financial upkeep. - -Therefore, citations in academic publications are crucial for keeping this project under academic community governance, as well as to track and report the demographics of our users. - -Therefore, we kindly, but strongly ask all software projects which are applying into, embedding in, forking from, deriving from, or taking influence from this project to retain the below sections in a clearly visible location of your project and/or documentation. - -**Users of this open-source software project should cite the following publications when publishing in academic form to keep this project and original upstream projects sustainable:** - -(Please note that this is currently a placeholder, an upcoming publication will be available after article review.) - -`Kim, S., Isla, D., Hejtmánek, L., et al., Selkies-GStreamer, (2024), GitHub repository, https://github.com/selkies-project/selkies-gstreamer` - -**Maintainers of derivative open-source projects should also place this text in a clearly visible location of your project.** - ---- -This project has been developed and is supported in part by the National Research Platform (NRP) and the Cognitive Hardware and Software Ecosystem Community Infrastructure (CHASE-CI) at the University of California, San Diego, by funding from the National Science Foundation (NSF), with awards #1730158, #1540112, #1541349, #1826967, #2138811, #2112167, #2100237, and #2120019, as well as additional funding from community partners, infrastructure utilization from the Open Science Grid Consortium, supported by the National Science Foundation (NSF) awards #1836650 and #2030508, and infrastructure utilization from the Chameleon testbed, supported by the National Science Foundation (NSF) awards #1419152, #1743354, and #2027170. This project has also been funded by the Seok-San Yonsei Medical Scientist Training Program (MSTP) Song Yong-Sang Scholarship, College of Medicine, Yonsei University, the MD-PhD/Medical Scientist Training Program (MSTP) through the Korea Health Industry Development Institute (KHIDI), funded by the Ministry of Health & Welfare, Republic of Korea, and the Student Research Bursary of Song-dang Institute for Cancer Research, College of Medicine, Yonsei University. diff --git a/docs/README.md b/docs/README.md index b289d016..135d167e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,24 @@ -![Selkies WebRTC](/logo/horizontal-480.png) +--- +hide: + - navigation + - toc +--- +![Selkies WebRTC](assets/logo/horizontal-480.png) [![Build](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml/badge.svg)](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml) [![Discord](https://img.shields.io/badge/dynamic/json?logo=discord&label=Discord%20Members&query=approximate_member_count&url=https%3A%2F%2Fdiscordapp.com%2Fapi%2Finvites%2FwDNGDeSW5F%3Fwith_counts%3Dtrue)](https://discord.gg/wDNGDeSW5F) +**Moonlight, Google Stadia, or GeForce NOW in noVNC form factor for Linux X11, in any HTML5 web interface you wish to embed inside, with at least 60 frames per second on Full HD resolution.** + +**We are in need of maintainers and community contributors. Please consider stepping up, as we can never have too much help!** + +Selkies-GStreamer is an open-source low-latency high-performance Linux-native GPU/CPU-accelerated WebRTC HTML5 remote desktop streaming platform, for self-hosting, containers, Kubernetes, or Cloud/HPC platforms, [started out first by Google engineers](https://web.archive.org/web/20210310083658/https://cloud.google.com/solutions/gpu-accelerated-streaming-using-webrtc), then expanded by academic researchers. + +Selkies-GStreamer is designed for researchers, including people in the graphical AI/robotics/autonomous driving/drug discovery fields, SLURM supercomputer/HPC system administrators, Jupyter/Kubernetes/Docker®/Coder infrastructure administrators, and Linux cloud gaming enthusiasts. + +While designed for clustered or unprivileged containerized environments, Selkies-GStreamer can also be deployed in desktop computers, and any performance issue that would be problematic in cloud gaming platforms is also considered a bug. + **Please read [Troubleshooting](usage.md#troubleshooting-and-faqs) first, then use [Discord](https://discord.gg/wDNGDeSW5F) or [GitHub Discussions](https://github.com/selkies-project/selkies-gstreamer/discussions) for support questions. Please only use [Issues](https://github.com/selkies-project/selkies-gstreamer/issues) for technical inquiries or bug reports.** **NOTE: this project is licensed under the [Mozilla Public License, version 2.0](https://www.mozilla.org/en-US/MPL/2.0/FAQ/), which obliges to share modified code files licensed by MPL-2.0 when distributed externally, but does not apply for any larger work outside this project, which might be open-source or proprietary under any license of choice. Externally originated components outside this project may contain works licensed over more restrictive copyleft/proprietary licenses, as well as other terms of intellectual property, including but not limited to patents, which users or developers are obliged to adhere to.** @@ -22,4 +37,27 @@ [**Development and Contributions**](development.md) +## Citations in Academic Publications + +> **NOTE: This section is also applicable for developers applying, embedding, forking, deriving, or taking influence from this project.** + +**Citations are the currency of scientific research. Citing in your publications is the main driver of keeping this project alive.** + +Remote desktop software projects have always been primarily proprietary. It is difficult to maintain such a project without consistent full-time compensation or financial upkeep. + +Therefore, citations in academic publications are crucial for keeping this project under academic community governance, as well as to track and report the demographics of our users. + +Therefore, we kindly, but strongly ask all software projects which are applying into, embedding in, forking from, deriving from, or taking influence from this project to retain the below sections in a clearly visible location of your project and/or documentation. + +**Users of this open-source software project should cite the following publications when publishing in academic form to keep this project and original upstream projects sustainable:** + +(Please note that this is currently a placeholder, an upcoming publication will be available after article review.) + +`Kim, S., Isla, D., Hejtmánek, L., et al., Selkies-GStreamer, (2024), GitHub repository, https://github.com/selkies-project/selkies-gstreamer` + +**Maintainers of derivative open-source projects should also place this text in a clearly visible location of your project.** + +--- +This project has been developed and is supported in part by the National Research Platform (NRP) and the Cognitive Hardware and Software Ecosystem Community Infrastructure (CHASE-CI) at the University of California, San Diego, by funding from the National Science Foundation (NSF), with awards #1730158, #1540112, #1541349, #1826967, #2138811, #2112167, #2100237, and #2120019, as well as additional funding from community partners, infrastructure utilization from the Open Science Grid Consortium, supported by the National Science Foundation (NSF) awards #1836650 and #2030508, and infrastructure utilization from the Chameleon testbed, supported by the National Science Foundation (NSF) awards #1419152, #1743354, and #2027170. This project has also been funded by the Seok-San Yonsei Medical Scientist Training Program (MSTP) Song Yong-Sang Scholarship, College of Medicine, Yonsei University, the MD-PhD/Medical Scientist Training Program (MSTP) through the Korea Health Industry Development Institute (KHIDI), funded by the Ministry of Health & Welfare, Republic of Korea, and the Student Research Bursary of Song-dang Institute for Cancer Research, College of Medicine, Yonsei University. + \* Funding agencies including, but not limited to the National Science Foundation, remain neutral with regard to jurisdictional claims in published articles and software code of this Code Repository. The Selkies Project logo and name have been created and are utilized or distributed with authorization by Dan Isla. In the context including, but not limited to this Code Repository, as well as in the context including, but not limited to any and all derivative works based on this Code Repository, all trademarks, trade names, logos, patents, or any and all other forms of external intellectual property, that are mentioned or used, unless otherwise stated, are the property of their respective owners, including but not limited to, The Linux Foundation®, Linus Torvalds, The Apache Software Foundation, Canonical Ltd., Google LLC, Alphabet Inc., NumFOCUS Foundation, Anaconda Inc., conda-forge, Project Jupyter, Coder Technologies, Inc., Docker®, Inc., SchedMD LLC, NVIDIA Corporation, Intel Corporation, Advanced Micro Devices, Inc., Valve Corporation, Epic Games, Inc., Unity Software Inc., Cendio AB, RealVNC® Limited, Amazon.com, Inc., Amazon Web Services, Inc., or its affiliates including but not limited to NICE s.r.l. or NICE USA LLC, Microsoft Corporation, Oracle Corporation, StarNet Communications Corporation, TeamViewer SE, GStreamer Foundation, Fabrice Bellard, Moonlight Project, and LizardByte. Every best effort has been undertaken to properly identify and attribute trademarks, trade names, logos, patents, or any and all other forms of external intellectual property to their respective owners, unless otherwise stated, wherever possible and practical. The inclusion of such trademarks, trade names, logos, patents, or any and all other forms of external intellectual property in association with this project, unless otherwise stated, serves solely for the purpose of description and must never be construed as an indication of affiliation, competition, endorsement, or a challenge to any and all legal standings of the trademarks, trade names, logos, patents, or any and all other forms of external intellectual property. All project contributors, maintainers, owners, or organizations agree to not willfully breach or infringe legal regulations, in any and all global law, regarding trademarks, trade names, logos, patents, or any and all other forms of external intellectual property. Therefore, all project contributors, maintainers, owners, or organizations, are immune to, and are not to be in any and all cases held legally liable for, any and all jurisdictional claims on trademarks, trade names, logos, patents, or any and all other forms of external intellectual property. No component of this Code Repository is an official product of Google LLC or Alphabet Inc. diff --git a/logo/favicon.ico b/docs/assets/logo/favicon.ico similarity index 100% rename from logo/favicon.ico rename to docs/assets/logo/favicon.ico diff --git a/logo/horizontal-480.png b/docs/assets/logo/horizontal-480.png similarity index 100% rename from logo/horizontal-480.png rename to docs/assets/logo/horizontal-480.png diff --git a/logo/horizontal.png b/docs/assets/logo/horizontal.png similarity index 100% rename from logo/horizontal.png rename to docs/assets/logo/horizontal.png diff --git a/logo/icon-192x192.png b/docs/assets/logo/icon-192x192.png similarity index 100% rename from logo/icon-192x192.png rename to docs/assets/logo/icon-192x192.png diff --git a/logo/icon-512x512.png b/docs/assets/logo/icon-512x512.png similarity index 100% rename from logo/icon-512x512.png rename to docs/assets/logo/icon-512x512.png diff --git a/logo/vertical.png b/docs/assets/logo/vertical.png similarity index 100% rename from logo/vertical.png rename to docs/assets/logo/vertical.png diff --git a/docs/component.md b/docs/component.md index 3a2f7c19..7abfcce9 100644 --- a/docs/component.md +++ b/docs/component.md @@ -28,9 +28,9 @@ All mandatory components are available for download from the [Releases](https:// For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` Build Artifacts (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch. Build Artifacts can also be downloaded using the [GitHub CLI](https://cli.github.com) command [`gh run download`](https://cli.github.com/manual/gh_run_download). -#### Conda Toolchain: +#### Conda Toolchain -Our [reference portable distribution toolchain](/addons/conda) is compiled with the distribution-neutral [Conda](https://conda-forge.org) build toolchain, distributing all three mandatory components as well as portable versions of most dependencies in a tarball. +Our [reference portable distribution toolchain](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/conda) is compiled with the distribution-neutral [Conda](https://conda-forge.org) build toolchain, distributing all three mandatory components as well as portable versions of most dependencies in a tarball. Pre-built `x86_64` portable distributions for **any Linux distribution with `glibc ≥ 2.17`** (CentOS 7 or newer) are available with the name **`selkies-gstreamer-portable-v${SELKIES_VERSION}_amd64.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version. @@ -51,11 +51,11 @@ cd ~ && tar -xzf /tmp/selkies-gstreamer-conda.tar.gz && rm -f /tmp/selkies-gstre Otherwise (for different system architectures), you can build your own portable distribution (currently tested with `aarch64` and `ppc64le`). -#### Python Application: +#### Python Application -The term `host` or `server` refers to the [Python Components](/src/selkies_gstreamer) across this documentation. +The term `host` or `server` refers to the [Python Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer) across this documentation. -The [Python Components](/src/selkies_gstreamer) are responsible for the host server backend, capturing and encoding the host screen and audio, receiving input signals and communicating other data (including the clipboard) between the client and the host, and establishing the WebRTC (with RTP underneath) connection to the client. +The [Python Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer) are responsible for the host server backend, capturing and encoding the host screen and audio, receiving input signals and communicating other data (including the clipboard) between the client and the host, and establishing the WebRTC (with RTP underneath) connection to the client. Host screen video and audio are transported using the WebRTC `MediaStream` interface, and other data are transported using the WebRTC `DataChannel` interface. @@ -87,11 +87,11 @@ sudo PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --no-cache-dir --force-reinstall . selkies-gstreamer --addr=0.0.0.0 --port=8080 --enable_https=false --https_cert=/etc/ssl/certs/ssl-cert-snakeoil.pem --https_key=/etc/ssl/private/ssl-cert-snakeoil.key --basic_auth_user=user --basic_auth_password=mypasswd --encoder=x264enc --enable_resize=false ``` -#### Web Application: +#### Web Application -The term `client` refers to the [Web Components](/addons/gst-web) across this documentation. +The term `client` refers to the [Web Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gst-web) across this documentation. -The [Web Components](/addons/gst-web) are responsible the web browser interface that you see when you use Selkies-GStreamer. +The [Web Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gst-web) are responsible the web browser interface that you see when you use Selkies-GStreamer. They receive and display the received screen and audio within the web browser, detect input signal and other data (including the clipboard) from the user, then send them to the host server backend. @@ -121,11 +121,11 @@ cd selkies-gstreamer/addons/gst-web sudo INSTALL_DIR=/opt/gst-web ./install.sh ``` -#### GStreamer: +#### GStreamer [GStreamer](https://gstreamer.freedesktop.org) "is a library for constructing graphs of media-handling components. The applications it supports range from simple Ogg/Vorbis playback, audio/video streaming to complex audio (mixing) and video (non-linear editing) processing." GStreamer is likely inside your smart TV, car infotainment system, or the digital street signage or surveillance camera near you, as well as many media players and video editing software. -GStreamer is responsible for the actual heavy lifting of Selkies-GStreamer, starting from capturing and encoding the host screen and audio to transporting the stream and other data between the host and the client web browser using WebRTC. GStreamer can be installed from your Linux distribution (but the required newest version may not be available), be [built for your distribution](/addons/gstreamer), or be compiled and distributed in portable form with [Conda](/addons/conda). +GStreamer is responsible for the actual heavy lifting of Selkies-GStreamer, starting from capturing and encoding the host screen and audio to transporting the stream and other data between the host and the client web browser using WebRTC. GStreamer can be installed from your Linux distribution (but the required newest version may not be available), be [built for your distribution](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer), or be compiled and distributed in portable form with [Conda](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/conda). Check [GStreamer Components](#gstreamer-components) for more details. @@ -151,9 +151,9 @@ Otherwise (for different operating system distributions or system architectures) These components are not required for Selkies-GStreamer, but may be required in specific cases of deployments or preferences. These sections are recommended to be nonetheless, read carefully. -#### Joystick Interposer: +#### Joystick Interposer -The [Joystick Interposer](/addons/js-interposer) is a special library that allows the usage of joysticks or gamepads inside unprivileged containers (most of the occasions with shared Kubernetes clusters or HPC clusters), where host kernel devices required for creating a joystick interface are not available. It uses a `LD_PRELOAD` hack to intercept `uinput` input commands from joysticks or gamepads into Selkies-GStreamer (much like how [VirtualGL](https://github.com/VirtualGL/virtualgl) intercepts OpenGL commands). +The [Joystick Interposer](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/js-interposer) is a special library that allows the usage of joysticks or gamepads inside unprivileged containers (most of the occasions with shared Kubernetes clusters or HPC clusters), where host kernel devices required for creating a joystick interface are not available. It uses a `LD_PRELOAD` hack to intercept `uinput` input commands from joysticks or gamepads into Selkies-GStreamer (much like how [VirtualGL](https://github.com/VirtualGL/virtualgl) intercepts OpenGL commands). Pre-built `x86_64` and `aarch64` joystick interposer components for Ubuntu are available with the name (fill in the OS version `DISTRIB_RELEASE` such as `24.04`, `22.04`, Ubuntu-style architecture `ARCH` such as `amd64` and `arm64`) **`selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.tar.gz`** or **`selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.deb`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version. @@ -199,7 +199,7 @@ export SDL_JOYSTICK_DEVICE=/dev/input/js0 You can replace `/usr/$LIB/selkies_joystick_interposer.so` with any non-root path of your choice if using the `.tar.gz` tarball. -Check the [Joystick Interposer README.md](/addons/js-interposer/README.md) documentation for usage instruction and compiling information on other platforms. +Check the [Joystick Interposer README.md](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/js-interposer/README.md) documentation for usage instruction and compiling information on other platforms. Check the following links for explanations of similar, but different attempts, for reference: @@ -213,13 +213,13 @@ Check the following links for explanations of similar, but different attempts, f -#### Example Container: +#### Example Container -The [Example Container](/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal. +The [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal. Read the [Development](development.md) section for customizing this container for your own usage. -Run the Docker®/Podman container built from the [`Example Dockerfile`](/addons/example/Dockerfile), then connect to port **8080** of your Docker®/Podman host to access the web interface (Username: **`ubuntu`**, Password: **`mypasswd`**, **change `DISTRIB_RELEASE` to `24.04`, `22.04`, or `20.04`, and replace `main` to `latest` for the latest stable release**): +Run the Docker®/Podman container built from the [`Example Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example/Dockerfile), then connect to port **8080** of your Docker®/Podman host to access the web interface (Username: **`ubuntu`**, Password: **`mypasswd`**, **change `DISTRIB_RELEASE` to `24.04`, `22.04`, or `20.04`, and replace `main` to `latest` for the latest stable release**): ```bash docker run --name selkies -it -d --rm -e SELKIES_TURN_PROTOCOL=udp -e SELKIES_TURN_PORT=3478 -e TURN_MIN_PORT=65534 -e TURN_MAX_PORT=65535 -p 8080:8080 -p 3478:3478 -p 3478:3478/udp -p 65534-65535:65534-65535 -p 65534-65535:65534-65535/udp ghcr.io/selkies-project/selkies-gstreamer/gst-py-example:main-ubuntu${DISTRIB_RELEASE} @@ -237,15 +237,15 @@ If you are behind a reverse proxy or can only expose one HTTP port, you will nee **Follow the instructions from [coTURN](#coturn) and [WebRTC and Firewall Issues](firewall.md) in order to make the container work using an external TURN server.** -#### coTURN: +#### coTURN > Check the [WebRTC and Firewall Issues: coTURN](firewall.md#coturn) section for installing and running coTURN on self-hosted standalone machines, cloud instances, or virtual machines. > > [Pion TURN](https://github.com/pion/turn)'s `turn-server-simple` executable or [eturnal](https://eturnal.net) are recommended alternative TURN server implementations that support Windows as well as Linux or MacOS. [STUNner](https://github.com/l7mp/stunner) is a Kubernetes native STUN and TURN deployment if Helm is possible to be used. -The [coTURN Container](/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=` (at least `49152`), and `-e TURN_MAX_PORT=` (at most `65535`), add more command-line options in `-e TURN_EXTRA_ARGS=`. +The [coTURN Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=` (at least `49152`), and `-e TURN_MAX_PORT=` (at most `65535`), add more command-line options in `-e TURN_EXTRA_ARGS=`. -Run the Docker®/Podman container built from the [`coTURN Dockerfile`](/addons/coturn/Dockerfile) (**replace `main` to `latest` for the latest stable release**): +Run the Docker®/Podman container built from the [`coTURN Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn/Dockerfile) (**replace `main` to `latest` for the latest stable release**): ```bash docker run --name coturn -it -d --rm -e TURN_SHARED_SECRET=n0TaRealCoTURNAuthSecretThatIsSixtyFourLengthsLongPlaceholdPlace -e TURN_REALM=example.com -e TURN_PORT=3478 -e TURN_MIN_PORT=65500 -e TURN_MAX_PORT=65535 -p 3478:3478 -p 3478:3478/udp -p 65500-65535:65500-65535 -p 65500-65535:65500-65535/udp ghcr.io/selkies-project/selkies-gstreamer/coturn:main @@ -261,7 +261,7 @@ In addition, use the option `-e TURN_EXTRA_ARGS="--no-udp-relay"` if you cannot Consult the [WebRTC and Firewall Issues: TURN Server Authentication Methods](firewall.md#turn-server-authentication-methods) and [TURN-REST](#turn-rest) sections for the difference between static auth secret/TURN REST API authentication and traditional long-term credential authentication. -#### TURN-REST: +#### TURN-REST **The below is an advanced concept likely required for multi-user environments.** @@ -273,19 +273,19 @@ In easier words, if both the host and client are behind restrictive firewalls, t The recommended multi-user TURN server authentication mechanism is the [time-limited short-term credential/TURN REST API mechanism](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00), where there is a single [shared secret](https://github.com/coturn/coturn/blob/master/README.turnserver) that is never exposed externally (only the TURN-REST Container and the coTURN TURN server know), but instead authenticates WebRTC clients (which are Selkies-GStreamer hosts and clients) based on generated credentials which are valid for only a short time (typically 24 hours). -The [TURN-REST Container](/addons/turn-rest) is an easy way to distribute short-term TURN server authentication credentials and the information of the TURN server based on the REST API to many Selkies-GStreamer host instances, particularly when behind a local area network (LAN), which may or may not have restricted firewalls. +The [TURN-REST Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest) is an easy way to distribute short-term TURN server authentication credentials and the information of the TURN server based on the REST API to many Selkies-GStreamer host instances, particularly when behind a local area network (LAN), which may or may not have restricted firewalls. Using the `selkies-gstreamer --turn_rest_uri=` option or `SELKIES_TURN_REST_URI` environment variable, the Selkies-GStreamer host periodically queries a URI such as `https://turn-rest.myinfrastructure.io/myturnrest` or `http://192.168.0.10/myturnrest`. This URI is ideally behind a local area network (LAN) inaccessible from the outside and only accessible to the Python hosts inside the LAN, or alternatively behind authentication using any web server or reverse proxy, if accessible from the outside. This information is periodically sent to the web client (that is also preferably behind authentication with HTTP Basic Authentication or a web server/reverse proxy) through HTTP(S), thus the TURN server information and credentials being propagated to both the Python host and the web client without exposing the TURN server information outside. -Because the time-limited TURN credentials automatically expire after some time, they are not useful even if they are leaked outside, as long as the pathway to the air-gapped or authenticated TURN-REST Container REST HTTP endpoint is not exposed plainly to the internet. [app.py](/addons/turn-rest/app.py) may also be hosted standalone without a container using the same startup command in the [Dockerfile](/addons/turn-rest/Dockerfile). +Because the time-limited TURN credentials automatically expire after some time, they are not useful even if they are leaked outside, as long as the pathway to the air-gapped or authenticated TURN-REST Container REST HTTP endpoint is not exposed plainly to the internet. [app.py](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest/app.py) may also be hosted standalone without a container using the same startup command in the [Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest/Dockerfile). Other authentication methods such as TURN-REST over various types of REST API authentication (but adding support for TURN-REST behind Basic Authentication is trivial, so reach out with some funding) or TURN oAuth authentication are not supported as of now, and likely requires funding. The TURN-REST Container (or similarly, Kubernetes Pod) should be triggered with the Docker®/Podman options `-e TURN_SHARED_SECRET=`, `-e TURN_HOST=`, `-e TURN_PORT=`, `-e TURN_PROTOCOL=`, `-e TURN_TLS=`, `-e STUN_HOST=`, `-e STUN_PORT=`, where the options are dependent on the TURN server configuration of [coTURN](#coturn) or other TURN server implementations. -Run the Docker®/Podman container built from the [`TURN-REST Dockerfile`](/addons/turn-rest/Dockerfile) (replace `main` to `latest` for the latest stable release**): +Run the Docker®/Podman container built from the [`TURN-REST Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest/Dockerfile) (replace `main` to `latest` for the latest stable release**): ```bash docker run --name turn-rest -it -d --rm -e TURN_SHARED_SECRET=n0TaRealCoTURNAuthSecretThatIsSixtyFourLengthsLongPlaceholdPlace -e TURN_HOST=turn.myinfrastructure.io -e TURN_PORT=3478 -e TURN_PROTOCOL=udp -e TURN_TLS=false -p 8008:8008 ghcr.io/selkies-project/selkies-gstreamer/turn-rest:main @@ -295,9 +295,9 @@ From Selkies-GStreamer, it is sufficient to use the `selkies-gstreamer --turn_re Consult the [WebRTC and Firewall Issues: TURN Server Authentication Methods](firewall.md#turn-server-authentication-methods) section for more information on TURN authentication methods. -#### coTURN-Web: +#### coTURN-Web -The [coTURN-Web Container](/addons/coturn-web) is a legacy component meant to provide similar capabilities to the [TURN-REST Container](/addons/turn-rest) for the Google Kubernetes Engine, mostly old remnants from the Google era. This component may be phased out as well as the [`infra/gce`](/infra/gce) and [`infra/gke`](/infra/gke) components and `cloudbuild.yml` configurations in favor of platform-agnostic Kubernetes configurations. Contributions are welcome. +The [coTURN-Web Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn-web) is a legacy component meant to provide similar capabilities to the [TURN-REST Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest) for the Google Kubernetes Engine, mostly old remnants from the Google era. This component may be phased out as well as the [`infra/gce`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gce) and [`infra/gke`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gke) components and `cloudbuild.yml` configurations in favor of platform-agnostic Kubernetes configurations. Contributions are welcome. ## GStreamer Components diff --git a/docs/development.md b/docs/development.md index e4ad29e4..70d14109 100644 --- a/docs/development.md +++ b/docs/development.md @@ -20,7 +20,7 @@ As the relatively permissive license compared to similar projects is for the ben Please join our [Discord](https://discord.gg/wDNGDeSW5F) server, then start out with the [Issues](https://github.com/selkies-project/selkies-gstreamer/issues) to see if new enhancements that you can make or things that you want solved have been already raised. -**No programming experience:** You can still be a tester or a community helper/moderator at [Discord](https://discord.gg/wDNGDeSW5F)! Do you see anything that feels uncomfortable compared to other projects? Raise an issue and suggest various improvements including to the documentation. Have you used OBS, FFmpeg, or any other live streaming/video editing software before? You can suggest optimized parameters for the video encoders from your experiences. You can experiment with various encoder parameters which are exposed in a very accessible way under [gstwebrtc_app.py](/src/selkies_gstreamer/gstwebrtc_app.py). You can add or modify properties exposed under the comment `ADD_ENCODER:` for each encoder, improving streaming performance. +**No programming experience:** You can still be a tester or a community helper/moderator at [Discord](https://discord.gg/wDNGDeSW5F)! Do you see anything that feels uncomfortable compared to other projects? Raise an issue and suggest various improvements including to the documentation. Have you used OBS, FFmpeg, or any other live streaming/video editing software before? You can suggest optimized parameters for the video encoders from your experiences. You can experiment with various encoder parameters which are exposed in a very accessible way under [gstwebrtc_app.py](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/gstwebrtc_app.py). You can add or modify properties exposed under the comment `ADD_ENCODER:` for each encoder, improving streaming performance. **Some Python or HTML/JavaScript frontend experience:** Our codebase and web interface always has room for improvement. Consider helping out on various issues or cleaning up the code otherwise. @@ -90,7 +90,7 @@ This section is a knowledge base for code contributions and development. ## Resources -- **Our [Documentation](/docs/README.md) and [Issues](https://github.com/selkies-project/selkies-gstreamer/issues)/[Pull Requests](https://github.com/selkies-project/selkies-gstreamer/pulls)** (including closed Issues/Pull Requests) and +- **Our [Documentation](README.md) and [Issues](https://github.com/selkies-project/selkies-gstreamer/issues)/[Pull Requests](https://github.com/selkies-project/selkies-gstreamer/pulls)** (including closed Issues/Pull Requests) and - GStreamer Repository (sources of truth are below, other repositories such as `gst-plugins-base` have been relocated to the below): @@ -163,13 +163,13 @@ ENTRYPOINT ["/usr/bin/supervisord"] ## Container Guide -The [`docker-nvidia-glx-desktop`](https://github.com/selkies-project/docker-nvidia-glx-desktop)/[`docker-nvidia-egl-desktop`](https://github.com/selkies-project/docker-nvidia-egl-desktop) desktop container repositories (referenced as Desktop Containers here), and the [Example Container](/addons/example) share various components between each other: +The [`docker-nvidia-glx-desktop`](https://github.com/selkies-project/docker-nvidia-glx-desktop)/[`docker-nvidia-egl-desktop`](https://github.com/selkies-project/docker-nvidia-egl-desktop) desktop container repositories (referenced as Desktop Containers here), and the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) share various components between each other: -`LICENSE`, `supervisord.conf`, `kasmvnc-entrypoint.sh`, and `selkies-gstreamer-entrypoint.sh` are always identical in both Desktop Containers (copy and paste between each container). As these components are also very similar to the [Example Container](/addons/example), **you need to do three Pull Requests including the [Example Container](/addons/example) if relevant lines changed in the [Example Container](/addons/example), and at least two Pull Requests for both Desktop Containers.** +`LICENSE`, `supervisord.conf`, `kasmvnc-entrypoint.sh`, and `selkies-gstreamer-entrypoint.sh` are always identical in both Desktop Containers (copy and paste between each container). As these components are also very similar to the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) if relevant lines changed in the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), and at least two Pull Requests for both Desktop Containers.** -The `Dockerfile` is always identical below and above the lines that say `Anything above/below this line should always be kept the same...` in both Desktop Containers. This component is not shared with the [Example Container](/addons/example), and installation procedures for Selkies-GStreamer should be updated to the desktop containers on every release, so **you need to do three Pull Requests including the [Example Container](/addons/example) if relevant lines changed in the [Example Container](/addons/example), and at least two Pull Requests for both Desktop Containers.** +The `Dockerfile` is always identical below and above the lines that say `Anything above/below this line should always be kept the same...` in both Desktop Containers. This component is not shared with the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), and installation procedures for Selkies-GStreamer should be updated to the desktop containers on every release, so **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) if relevant lines changed in the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), and at least two Pull Requests for both Desktop Containers.** -The `entrypoint.sh` components are always identical from the start until the line containing `export PULSE_SERVER=..."` in both Desktop Containers. The script for installing NVIDIA userspace driver components are always identical except for the outermost `if` condition. Other script sections require manual assessment when updating, so **you need to do three Pull Requests including the [Example Container](/addons/example) if relevant lines changed in both Desktop Containers and the [Example Container](/addons/example).** +The `entrypoint.sh` components are always identical from the start until the line containing `export PULSE_SERVER=..."` in both Desktop Containers. The script for installing NVIDIA userspace driver components are always identical except for the outermost `if` condition. Other script sections require manual assessment when updating, so **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) if relevant lines changed in both Desktop Containers and the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example).** `README.md` and `egl.yml`/`xgl.yml` files in both Desktop Containers are similar but have different components, thus requiring manual assessment for both Desktop Containers when updating. @@ -191,7 +191,7 @@ The `entrypoint.sh` components are always identical from the start until the lin - **Write or edit code in relevant files and reference them so that the code style is kept consistent.** For instance, many handler methods that start with `on_` are initially unset, then set and referenced in other components or classes during initialization. If you are implementing a new capability on certain methods or handlers that use methods starting with `on_` frequently, you have to create new `on_` methods as well to handle your capability. This assists with keeping the code highly readable, and putting methods or functions in the wrong files will harm the consistency of the code style. **If you are starting to feel that the location you are writing code in does not blend properly into adjacent code, you are probably writing it in the wrong place!** -- For example, assume that we are writing a new component that receives WebRTC Metrics from the web interface and writes them into multiple CSV files in the host ([#141](https://github.com/selkies-project/selkies-gstreamer/pull/141)). Because the WebRTC RTCDataChannel interface is used, receiving the metrics will be handled in [`webrtc_input.py`](/src/selkies_gstreamer/webrtc_input.py). But this does not mean that everything should be implemented in this file. Instead, they should be [implemented in the `Metrics` class](https://github.com/selkies-project/selkies-gstreamer/pull/141/commits/abae13645fdf0082f27041c59a14e1c030cf3763) of [`metrics.py`](/src/selkies_gstreamer/metrics.py), and be initialized in [`__main__.py`](/src/selkies_gstreamer/__main__.py). This way, relevant code stays in appropriate files and is initialized only when the capabilities are needed. +- For example, assume that we are writing a new component that receives WebRTC Metrics from the web interface and writes them into multiple CSV files in the host ([#141](https://github.com/selkies-project/selkies-gstreamer/pull/141)). Because the WebRTC RTCDataChannel interface is used, receiving the metrics will be handled in [`webrtc_input.py`](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/webrtc_input.py). But this does not mean that everything should be implemented in this file. Instead, they should be [implemented in the `Metrics` class](https://github.com/selkies-project/selkies-gstreamer/pull/141/commits/abae13645fdf0082f27041c59a14e1c030cf3763) of [`metrics.py`](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/metrics.py), and be initialized in [`__main__.py`](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/__main__.py). This way, relevant code stays in appropriate files and is initialized only when the capabilities are needed. - Some code components have `CAPITALIZED_COMMENT:` comment sections such as `ADD_ENCODER:` or `OPUS_FRAME:`. These sections indicate that locations with the `CAPITALIZED_COMMENT:` must be edited or added simultaneously. diff --git a/docs/firewall.md b/docs/firewall.md index bbd771c5..9c9856ed 100644 --- a/docs/firewall.md +++ b/docs/firewall.md @@ -181,7 +181,7 @@ Consult the [coTURN Documentation](https://github.com/coturn/coturn/blob/master/ ### Deploy coTURN with Docker® -The [coTURN Container](/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=`, and `-e TURN_MAX_PORT=`, add more command-line options in `-e TURN_EXTRA_ARGS=`. +The [coTURN Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=`, and `-e TURN_MAX_PORT=`, add more command-line options in `-e TURN_EXTRA_ARGS=`. **Read the [coTURN](component.md#coturn) section to get started.** @@ -213,7 +213,7 @@ Consult the [coTURN Documentation](https://github.com/coturn/coturn/blob/master/ In both types of containers, the `--cert=` and `--pkey=` options are required for using TURN over TLS/DTLS, but are otherwise optional. They should lead to the certificate and the private key from a legitimate certificate authority such as [ZeroSSL](https://zerossl.com/features/acme/) or [Let's Encrypt](https://letsencrypt.org/getting-started/) with a valid hostname which resolves to the TURN server. -Provide the certificate and private files to the coTURN container with `-v /my_local_path/coturncert.crt:/etc/coturn_tls.crt -v /my_local_path/coturnkey.key:/etc/coturn_tls.key` (specified paths are an example), then add the options `-e TURN_EXTRA_ARGS="--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key"` for the Selkies [coTURN Container](/addons/coturn) and use the options `--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key` for the official coTURN container. +Provide the certificate and private files to the coTURN container with `-v /my_local_path/coturncert.crt:/etc/coturn_tls.crt -v /my_local_path/coturnkey.key:/etc/coturn_tls.key` (specified paths are an example), then add the options `-e TURN_EXTRA_ARGS="--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key"` for the Selkies [coTURN Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn) and use the options `--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key` for the official coTURN container. ### Deploy coTURN With Kubernetes diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 00000000..23dbebc8 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,120 @@ +site_name: Selkies-GStreamer +site_url: https://selkies-project.github.io/selkies-gstreamer +site_description: >- + Open-Source Low-Latency Accelerated Linux WebRTC HTML5 Remote Desktop Streaming Platform for Self-Hosting, Containers, Kubernetes, or Cloud/HPC +docs_dir: ./ +theme: + name: material + +# Repository +repo_name: selkies-gstreamer +repo_url: https://github.com/selkies-project/selkies-gstreamer + +# Copyright +copyright: Copyright © 2024 Selkies Project, Selkies-GStreamer + +# Configuration +theme: + name: material + # custom_dir: overrides + features: + # - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + # - content.footnote.tooltips + # - content.tabs.link + - content.tooltips + # - header.autohide + - navigation.expand + - navigation.footer + - navigation.indexes + # - navigation.instant + # - navigation.instant.prefetch + # - navigation.instant.progress + # - navigation.prune + # - navigation.path + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + - toc.integrate + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/link + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/toggle-switch + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: indigo + toggle: + icon: material/toggle-switch-off + name: Switch to system preference + font: + text: Roboto + code: Roboto Mono + favicon: assets/logo/favicon.ico + logo: assets/logo/icon-512x512.png + icon: + admonition: + quote: octicons/quote-16 + +# Plugins +plugins: +- search: + separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' + +# Additional configuration +extra: + generator: false + social: + - icon: fontawesome/brands/github + link: https://github.com/selkies-project/selkies-gstreamer + - icon: fontawesome/brands/discord + link: https://discord.gg/wDNGDeSW5F + +# Extensions +markdown_extensions: +- abbr +- admonition +- attr_list +- def_list +- footnotes +- md_in_html +- tables +- toc: + permalink: true +# - pymdownx.details +- pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- pymdownx.inlinehilite +- pymdownx.snippets +- pymdownx.superfences + +# Navigation +nav: +- Home: README.md +- 'What is Selkies-GStreamer?': design.md +- 'Getting Started': start.md +- 'Troubleshooting and FAQs': usage.md#troubleshooting-and-faqs +- 'WebRTC and Firewall Issues': firewall.md +- Usage: usage.md#usage +- Components: component.md +- 'Development and Contributions': development.md diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..898468cb --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs-material \ No newline at end of file diff --git a/docs/start.md b/docs/start.md index 78f2aa73..e64dfcdc 100644 --- a/docs/start.md +++ b/docs/start.md @@ -78,7 +78,7 @@ The [`selkies-vdi`](https://github.com/selkies-project/selkies-vdi) or [`selkies ## Minimal Container -The [Example Container](/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal. +The [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal. Instructions are available in the [Example Container](component.md#example-container) section. @@ -96,7 +96,7 @@ This distribution is slightly more complicated to deploy, yet is the recommended Selkies-GStreamer has a highly modularized architecture, composed of multiple components. -Three mandatory components are required to run Selkies-GStreamer: the [standalone or distribution-provided build of GStreamer](/addons/gstreamer) with the most recent version (currently ≥ 1.22), the [Python component wheel package](/src/selkies_gstreamer) including the signaling server, and the [HTML5 web interface components](/addons/gst-web). Currently, Ubuntu 24.04 (Mint 22), 22.04 (Mint 21), 20.04 (Mint 20) are supported, but other operating systems should also work if using your own GStreamer build of the newest version (contributions for build workflows of more operating systems are welcome). +Three mandatory components are required to run Selkies-GStreamer: the [standalone or distribution-provided build of GStreamer](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer) with the most recent version (currently ≥ 1.22), the [Python component wheel package](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer) including the signaling server, and the [HTML5 web interface components](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gst-web). Currently, Ubuntu 24.04 (Mint 22), 22.04 (Mint 21), 20.04 (Mint 20) are supported, but other operating systems should also work if using your own GStreamer build of the newest version (contributions for build workflows of more operating systems are welcome). All three of the components are built and packaged every [Release](https://github.com/selkies-project/selkies-gstreamer/releases). In addition, every latest commit gets built and is made available in container forms [`ghcr.io/selkies-project/selkies-gstreamer/gstreamer`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fgstreamer), [`ghcr.io/selkies-project/selkies-gstreamer/py-build`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fpy-build), and [`ghcr.io/selkies-project/selkies-gstreamer/gst-web`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fgst-web). @@ -104,7 +104,7 @@ For more information, check the [Components](component.md#components) section. The [All-In-One Desktop Containers](#desktop-container) support unprivileged self-hosted Kubernetes clusters and Docker®/Podman. -Example Google Compute Engine/Google Kubernetes Engine deployment configurations of all components are available in the [`infra/gce`](/infra/gce) and [`infra/gke`](/infra/gke) directories, but may be deprecated in favor of vendor-agnostic Kubernetes configurations. +Example Google Compute Engine/Google Kubernetes Engine deployment configurations of all components are available in the [`infra/gce`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gce) and [`infra/gke`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gke) directories, but may be deprecated in favor of vendor-agnostic Kubernetes configurations. ### Install the packaged version on self-hosted standalone machines, cloud instances, or virtual machines @@ -124,7 +124,7 @@ Install additional dependencies if using Ubuntu ≥ 22.04 (Mint 21) or a higher sudo apt-get update && sudo apt-get install --no-install-recommends -y xcvt libopenh264-dev svt-av1 aom-tools ``` -If using supported NVIDIA GPUs, install NVENC (bundled with the GPU driver) and NVRTC (bundled with pre-built GStreamer component, check the [GStreamer Dockerfile](/addons/gstreamer/Dockerfile) for manual installation instructions). +If using supported NVIDIA GPUs, install NVENC (bundled with the GPU driver) and NVRTC (bundled with pre-built GStreamer component, check the [GStreamer Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer/Dockerfile) for manual installation instructions). If using AMD or Intel GPUs, install its graphics and VA-API drivers, as well as `libva2`. The bundled VA-API driver in the AMDGPU Pro graphics driver is recommended for AMD GPUs and the `i965-va-driver-shaders` or `intel-media-va-driver-non-free` packages are recommended depending on your Intel GPU generation. Optionally install `vainfo`, `intel-gpu-tools`, `radeontop`, or `nvtop` for GPU monitoring. @@ -144,7 +144,7 @@ Read [GStreamer](component.md#gstreamer) for more details of this step and proce cd /opt && curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/gstreamer-selkies_gpl_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_amd64.tar.gz" | sudo tar -xzf - ``` -This will install the GStreamer components to the default directory of `/opt/gstreamer`. If you are unpacking to a different directory, make sure to set the the environment variable `GSTREAMER_PATH` to the directory. GStreamer builds for `aarch64` are not provided but can be built following procedures in the [GStreamer Dockerfile](/addons/gstreamer/Dockerfile) or [Conda Dockerfile](/addons/conda/Dockerfile). +This will install the GStreamer components to the default directory of `/opt/gstreamer`. If you are unpacking to a different directory, make sure to set the the environment variable `GSTREAMER_PATH` to the directory. GStreamer builds for `aarch64` are not provided but can be built following procedures in the [GStreamer Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer/Dockerfile) or [Conda Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/conda/Dockerfile). **3. Install the Selkies-GStreamer Python components** (this component is pure Python and any operating system is compatible, fill in `SELKIES_VERSION`)**:** diff --git a/docs/usage.md b/docs/usage.md index 5630df5b..0ef50d5c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -26,13 +26,13 @@ Environment variables for command-line options are available as capitalizations ## CI/CD Build -We use Docker® containers for building every commit. The root directory [`Dockerfile`](/Dockerfile) and Dockerfiles within the [`addons`](/addons) directory provide directions for building each component, so that you may replicate the procedures in your own setup even without Docker® by copying the commands to your own shell. +We use Docker® containers for building every commit. The root directory [`Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/Dockerfile) and Dockerfiles within the [`addons`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons) directory provide directions for building each component, so that you may replicate the procedures in your own setup even without Docker® by copying the commands to your own shell. # Troubleshooting and FAQs ## The HTML5 web interface loads and the signaling connection works, but the WebRTC connection fails or the remote desktop does not start. -
+
Open Answer First of all, ensure that there is a running PulseAudio or PipeWire-Pulse session as the interface does not establish without an audio server. @@ -53,7 +53,7 @@ Make sure to also check that you enabled automatic login with your display manag ## The HTML5 web interface is slow, lagging, or stuttering. -
+
Open Answer **First, check if the TURN server is shown as `staticauth.openrelay.metered.ca` with a `relay` connection, and if so, please read [WebRTC and Firewall Issues](firewall.md).** @@ -80,7 +80,7 @@ However, it might be that the parameters for the WebRTC interface, video encoder ## The clipboard does not work. -
+
Open Answer This is very likely a web browser constraint that is applied because you are using HTTP for an address to the web interface that is not localhost. The clipboard only works when you use HTTPS (with a valid or self-signed certificate), or when accessing localhost (some browsers do not support this as well). You could use port forwarding to access through localhost or obtain an HTTPS certificate. @@ -89,7 +89,7 @@ This is very likely a web browser constraint that is applied because you are usi ## The web interface refuses to start up in the terminal after rebooting my computer or restarting my desktop in a standalone instance. -
+
Open Answer This is because the desktop session starts as `root` when the user is not logged in. Next time, set up automatic login in the settings with the user you want to use. @@ -100,7 +100,7 @@ In order to use the web interface when this is not possible (or when you are usi ## My touchpad does not move while pressing a key with the keyboard. -
+
Open Answer This is a setting from the client operating system and will show the same behavior with any other application. In Windows, go to `Settings > Bluetooth & devices > Touchpad > Taps` to increase your touchpad sensitivity. In Linux or Mac, turn off the setting `Touchpad > Disable while typing`. @@ -109,7 +109,7 @@ This is a setting from the client operating system and will show the same behavi ## I want to pass multiple screens within a server to another client using the WebRTC HTML5 web interface. -
+
Open Answer You can start a new instance of Selkies-GStreamer by changing the `DISPLAY` environment variable (or even use the same one for multiple instances) and setting a different web interface port in a different terminal to pass a different screen simultaneously to your current screen. Reverse proxy server/web servers supporting WebSocket such as `nginx` can be utilized to expose the interfaces to multiple users in different paths. @@ -118,7 +118,7 @@ You can start a new instance of Selkies-GStreamer by changing the `DISPLAY` envi ## I want to test a shared secret TURN server by manually generating a TURN credential from a shared secret. -
+
Open Answer Try the [TURN-REST Container](component.md#turn-rest) or its underlying turn-rest `app.py` Flask web application. This will output TURN credentials automatically when the Docker®/Podman options `-e TURN_SHARED_SECRET=`, `-e TURN_HOST=`, `-e TURN_PORT=`, `-e TURN_PROTOCOL=`, `-e TURN_TLS=` or environment variables `export TURN_SHARED_SECRET=`, `export TURN_HOST=`, `export TURN_PORT=`, `export TURN_PROTOCOL=`, `export TURN_TLS=` are set.