E4S Remote Desktop
E4S remote desktop quickstart
E4S full-release container images include a browser-accessible Linux desktop powered by Apache Guacamole and VNC. This is useful for running graphical applications from an E4S container without installing a desktop client on your local system.
Availability: The remote desktop is available with E4S 26.11 and later and is included only in the full release images. It is not included in minimal images.
Start the container
Docker
Docker must use host networking so the services started in the container are reachable through the SSH tunnel described below.
$> docker run --network host --rm -it <full-e4s-image>
Add any other Docker options you normally need, such as GPU access or bind mounts. For example:
$> docker run --network host --gpus all -v "$HOME:$HOME" --rm -it <full-e4s-image>
Docker requirement:
--network hostis necessary. Without it, the Guacamole web service and VNC session will not be available through the connection instructions printed by the launcher.
Apptainer or Singularity
Enter the full E4S image as usual. For example:
$> apptainer shell <full-e4s-image>.sif
or:
$> singularity shell <full-e4s-image>.sif
Launch the desktop
From inside the container, run:
$> guacamole
On the first run, the launcher asks you to configure:
- The VNC port. In most cases, accept the suggested port.
- A Guacamole web username and password. You will need these to log in to the Guacamole session in your browser.
- A VNC password. This is separate from your Linux or institutional password. Use a dedicated password, or if you only intend use the VNC session with Guacamole press Enter when offered the option to generate one.
The launcher then starts the VNC desktop, Guacamole, and its local web service. At the end of startup it prints an SSH tunnel command and a local browser URL. Keep the container and the guacamole command running while using the desktop.
Connect from your local computer
Run the printed SSH command in a terminal on your local computer. It will resemble:
$> ssh -N -L <port>:127.0.0.1:<port> <user>@<remote-host>
If you are running the container on a system that requires access via a login node you can add ssh jump to tunnel from the login node to the host:
$> ssh -J <user>@<login-node> -N -L <port>:127.0.0.1:<port> <user>@<remote-host>
Leave that SSH command running. Then open the URL printed by guacamole in a browser on your local computer. It will resemble:
http://127.0.0.1:<port>/guacamole
Sign in with the Guacamole web username and password you selected during first-time setup.
The Guacamole web service listens only on the remote system’s loopback interface. The SSH tunnel makes it available to your local browser without exposing the service directly to the network.
Copy and paste with the Guacamole side panel
To open the Guacamole side panel while viewing the remote desktop, press:
- Windows or Linux:
Ctrl+Alt+Shift - macOS:
Control+Option+Shift
Press the same key combination again to close the panel.
To paste text into the E4S desktop:
- Open the Guacamole side panel.
- Copy the text on your local computer.
- Click the Clipboard text area and paste the text into it.
- Close the side panel.
- Paste normally into the remote terminal or application.
Text placed in the side panel’s Clipboard area is transferred to the remote desktop clipboard. Guacamole initially hides the clipboard contents for privacy; click the Clipboard area to view or edit them.
Copying text out of the E4S desktop normally works directly: select and copy the text in the remote application, then paste it into an application on your local computer. The side panel is generally needed only when pasting local text into the container.
End the session
Log out of the graphical desktop if desired, then return to the terminal running guacamole and press Ctrl+C. The launcher stops the services and VNC session that it started.
Display size
By default, the remote desktop uses a fixed 1920x1200 resolution. Guacamole scales that desktop for the browser window, avoiding extremely large remote desktops on high-resolution monitors.
To let Guacamole dynamically resize the remote desktop to match the browser viewport, start it with:
$> guacamole --dynamic-resize
Dynamic resizing depends on support from the VNC server in the image.
To choose a different fixed resolution, set VNC_GEOMETRY when launching Guacamole:
$> VNC_GEOMETRY=1600x900 guacamole
Useful runtime options
The normal quickstart requires only guacamole. These settings are available for less common situations:
| Setting | Purpose |
|---|---|
guacamole --dynamic-resize |
Allow Guacamole to request desktop resizing as the browser viewport changes. |
VNC_GEOMETRY=WIDTHxHEIGHT guacamole |
Select the initial fixed desktop resolution. The default is 1920x1200. |
SSH_HOST=<hostname> guacamole |
Override the hostname shown in the printed SSH tunnel command. |
SSH_USER=<username> guacamole |
Override the SSH username shown in the printed tunnel command. |
SSH_OPTS="<options>" guacamole |
Add SSH options to the printed command, such as -J bastion.example.org. |
guacamole --help |
Display the launcher help and available environment variables. |
Common issues
The browser cannot connect
Confirm that:
- the container and
guacamolecommand are still running; - the SSH tunnel is running on your local computer;
- you opened the exact local URL printed by the launcher; and
- Docker was started with
--network host.
The printed SSH hostname is not the one you use
Restart the launcher with the hostname you normally use for SSH:
$> SSH_HOST=login.example.org guacamole
If access requires a jump host, include it in the printed command with SSH_OPTS:
$> SSH_HOST=compute.example.org SSH_OPTS="-J bastion.example.org" guacamole
The desktop is too small or too large
The default fixed resolution is intended to work well across typical displays. Select another fixed size with VNC_GEOMETRY, or opt into browser-driven sizing with --dynamic-resize.