From b8a824646f0caffbec24ee49a304cf703ff35732 Mon Sep 17 00:00:00 2001 From: kcleal Date: Thu, 19 Dec 2024 15:37:59 +0000 Subject: [PATCH] Updated main.yml remote docs --- .github/workflows/main.yml | 2 +- docs/docs/guide/Remote.md | 173 ++++++++++++++++++++++++++++++------- 2 files changed, 145 insertions(+), 30 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b11b35e..b64e9c5 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -42,7 +42,7 @@ jobs: matrix: os: [ macos-14 ] # macos-12, include: - - os: macos-12 + - os: macos-14 arch: intel - os: macos-14 arch: m1 diff --git a/docs/docs/guide/Remote.md b/docs/docs/guide/Remote.md index 0752be6..4be3610 100644 --- a/docs/docs/guide/Remote.md +++ b/docs/docs/guide/Remote.md @@ -1,53 +1,168 @@ --- -title: Remote +title: Remote Access layout: home parent: User guide nav_order: 11 --- -# Loading remote data +# Accessing GW Remotely -If your remote data is available via a http/https or ftp site then GW should be able to open them. -Just supply a suitable path starting with `http` or `ftp` and GW will attempt to load the file. +GW supports multiple methods for accessing and visualizing data over remote connections. This guide covers the available approaches and their recommended use cases. -If data access requires a login e.g. via ssh, then there are a few options: +## Direct Remote Data Access -## Mounting remote data using sshfs +GW can directly access remote data through HTTP/HTTPS or FTP protocols. Simply provide the full URL path (starting with `http://` or `ftp://`) to your data files, and GW will attempt to load them from your local machine. -Using sshfs, data on your remote server can be mounted to -your local file system. GW will then be able to load data directly from the mounted drive, in addition to -your local file system. +## Secure Access Methods -MacOS uses will want to use macFuse for this: https://macfuse.github.io. -An installation tutorial can be found here: https://phoenixnap.com/kb/sshfs-mac. +For data requiring secure access (e.g., SSH authentication), you have several options: -For Linux and Windows users, follow this guide: https://phoenixnap.com/kb/sshfs +### 1. SSHFS Mount Method -## X11 forwarding from the command line +SSHFS allows you to mount remote directories to your local filesystem, enabling GW to access remote files as if they were local. -GW can be used on remote servers by using `ssh -X` when logging on to the server, and a -GW window will show up on your local screen. This should work seamlessly with -linux server-client machines, although there are known issues with Mac-Linux server-client interfaces (although these -still work sometimes). +#### Platform-Specific Setup: +- **MacOS**: Install macFuse from [macFuse website](https://macfuse.github.io) +- **Linux/Windows**: Follow the [SSHFS setup guide](https://phoenixnap.com/kb/sshfs) -Also, an update delay (in miliseconds) should be added using `gw --delay 100` which can help prevent bandwidth/latency issues. +**Advantages:** +- Simple to use once configured +- Transparent access to remote and local files +- No modification to GW usage required +### 2. X11 Forwarding -## Xpra from the command line -The screen sharing tool Xpra can offer much better performance for rendering over a remote connection -compared to X11 forwarding. +Run GW on a remote server while displaying the interface on your local machine. -Xpra will need to be installed on local and remote machines. One way to use Xpra is to start GW on port 100 (on remote machine) using: +```bash +ssh -X username@remote-server +gw --delay 100 # Add delay to handle latency +``` + +**Important Notes:** +- Works best between Linux systems +- Mac-to-Linux connections mostly do not work (you may be lucky) +- Use the `--delay` parameter (in milliseconds) to handle latency issues + +### 3. Xpra + +Xpra offers superior performance compared to X11 forwarding, especially for graphical applications. + +#### Setup Instructions: + +1. Install Xpra on both local and remote machines +2. Start GW on the remote machine: + ```bash + xpra start :100 --start="gw ref.fa -b your.bam -r chr1:50000-60000" --sharing=yes --daemon=no + ``` +3. Connect from your local machine: + ```bash + xpra attach ssh:username@remote-server:100 + ``` + +For custom SSH configurations: +```bash +xpra attach ssh:username@remote-server:100 --ssh "ssh -o IdentitiesOnly=yes -i /path/to/key.pem" +``` + +**Key Features:** +- Better performance than X11 +- Supports multiple simultaneous users +- More resilient to network issues + +### 4. VNC Access -```shell -xpra start :100 --start="gw ref.fa -b your.bam -r chr1:50000-60000" --sharing=yes --daemon=no +For a full remote desktop experience, consider using VNC (e.g., TigerVNC). + +**Note:** This method requires administrator setup on the remote server. + +## Comparison of Methods + +| Method | Performance | Setup Complexity | Best For | +|--------|-------------|------------------|-----------| +| SSHFS | Good | Low | Direct file access | +| X11 | Fair | Low | Quick access, Linux-to-Linux | +| Xpra | Excellent | Medium | Regular remote usage | +| VNC | Good | High | Full desktop access | + + +### Graphics and Display Issues + +#### Testing OpenGL Support + +1. Check OpenGL capabilities using `glxinfo`: +```bash +glxinfo | grep "direct rendering" +glxinfo | grep "OpenGL version" ``` -You (or potentially multiple users) can view the GW window on your local machine using: +If these commands aren't available, install them: +- Ubuntu/Debian: `sudo apt-get install mesa-utils` +- RHEL/CentOS: `sudo yum install glx-utils` + +Expected output should show: +- "direct rendering: Yes" +- OpenGL version 2.0 or higher -```shell -xpra attach ssh:ubuntu@18.234.114.252:100 +#### Testing Graphics Performance + +Use `glxgears` to test basic 3D rendering: +```bash +glxgears -info ``` -The :100 indicates the port. If you need to supply more options to the ssh command use e.g. -`xpra attach ssh:ubuntu@18.234.114.252:102 --ssh "ssh -o IdentitiesOnly=yes -i .ssh/dysgu.pem"` +This will display rotating gears and report FPS (Frames Per Second). Low FPS (<30) may indicate: +- Graphics driver issues +- X11 forwarding bandwidth limitations +- Hardware acceleration problems + +### Common Issues and Solutions + +1. Blank or Black Window + - Check OpenGL support using methods above + - Try forcing software rendering: + ```bash + export LIBGL_ALWAYS_SOFTWARE=1 + ``` + +2. Slow Performance + - For X11: Increase delay value + ```bash + gw --delay 200 # Adjust value as needed + ``` + - For Xpra: Use compression options + ```bash + xpra start :100 --encoding=rgb --compress=0 + ``` + +3. Connection Refused + - Verify SSH access: + ```bash + ssh -v username@remote-server + ``` + - Check if X11 forwarding is enabled in `/etc/ssh/sshd_config`: + ``` + X11Forwarding yes + ``` + +4. Display Export Errors + - Ensure DISPLAY variable is set: + ```bash + echo $DISPLAY + ``` + - Set if missing: + ```bash + export DISPLAY=:0 + ``` + +### Getting Help + +If problems persist please raise an issue: + +1. Collect system information: +```bash +gw --version +GW_DEBUG=1 gw hg19 +glxinfo +echo $DISPLAY +```