How do I install a GUI on my Amazon EC2 instance that's running Amazon Linux 2?

Short description

To run graphical applications on Linux, you need a desktop environment. Standard Amazon Machine Images (AMIs) for AL2 don't come with a desktop environment installed by default. Use the AL2 Extras Library to install the MATE Desktop Environment. For more information, see MATE Desktop Environment on the MATE website.

Or, launch the instance from an AL2 AMI that comes with MATE preinstalled. For more information, see Configure the AL2 MATE desktop connection. You can also use virtual desktops on Amazon WorkSpaces to run AL2, Ubuntu Linux, Rocky Linux, Red Hat Enterprise Linux (RHEL), or Microsoft Windows.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

The following resolution is for AL2 only. To check your Linux distribution name and version, run the following command:

grep PRETTY_NAME /etc/os-release

You can't use the following resolution steps for environments that use a bastion (jump) instance to connect to other EC2 instances in a non-public subnet. To securely connect to EC2 instances that don't have direct internet connectivity, use EC2 Instance Connect Endpoint or Session Manager, a capability of AWS Systems Manager. Or, use AWS Site-to-Site VPN or AWS Direct Connect to establish secure connectivity between your network and AWS.

Update your instance

It's a best practice to update and reboot your instance before you install the GUI to avoid issues.

To update your instance, complete the following steps:

1. Connect to your Amazon EC2 instance.

2. Run the following command to update your instance:

   sudo yum update

3. Reboot your instance.

Install the MATE desktop environment

To install the MATE desktop environment, complete the following steps:

1. To install MATE packages, run the following command:

   sudo amazon-linux-extras install mate-desktop1.x

2. To define MATE as your default desktop environment for all users, run the following command:

   sudo bash -c 'echo PREFERRED=/usr/bin/mate-session > /etc/sysconfig/desktop'

Install a VNC server

Install a Virtual Network Computing (VNC) server, such as TigerVNC, to access remote graphical desktop services. For more information about TigerVNC, see TigerVNC on the TigerVNC website.

For security reasons, the following configuration doesn't allow direct connectivity through TigerVNC. Instead, you must use an encrypted SSH tunnel to access the GUI. It's a best practice to not open VNC ports in your security groups.

To install TigerVNC, complete the following steps:

1. To install the TigerVNC server, run the following command:

   sudo yum install tigervnc-server

2. To configure a VNC-specific password for your user, run the following command:

   vncpasswd

   Note: When the terminal asks whether you want to enter a view-only password, press n. The unencrypted password is recorded to a file in your home directory. Only your user and the root user can access the file. A challenge-response mechanism protects the passwords transmitted over the network. For more information, see vncpasswd on the TigerVNC website. The SSH tunnel that you use further protects connections with stronger encryption.

3. To create the tigervnc systemwide configuration directory, run the following command:

   sudo mkdir /etc/tigervnc

4. To block direct connectivity to the VNC, run the following command:

   sudo bash -c 'echo localhost > /etc/tigervnc/vncserver-config-mandatory'

5. To create a new systemd unit for TigerVNC, run the following command:

   sudo cp /lib/systemd/system/vncserver@.service /etc/systemd/system/vncserver@.service

6. To replace all occurrences of <USER> in the new unit with your username, run the following command:

   sudo sed -i 's/<USER>/'${USER}'/' /etc/systemd/system/vncserver@.service

7. To reload the systemd manager configuration, run the following command:

   sudo systemctl daemon-reload

8. To activate the TigerVNC service at boot, run the following command:

   sudo systemctl enable vncserver@:1

9. To start the TigerVNC service, run the following command:

   sudo systemctl start vncserver@:1

10. To confirm that the TigerVNC service runs, run the following command:

    sudo systemctl status vncserver@:1

11. To confirm that the TigerVNC is listening on TCP port 5901, run the following command:

    ss -lnp '( sport = :5901 )'

Install TigerVNC Viewer on your local computer

TigerVNC Viewer is available for Windows, macOS, and Linux. To download the tool, see Releases on GitHub.

Based on your operating system (OS), download the following TigerVNC Viewer version:

• For Windows, install tigervnc64-x.y.z.exe (64-bit) or tigervnc-x.y.z.exe (32-bit).
• For macOS, install TigerVNC-x.y.z.dmg.
  Note: Replace x.y.z with the latest version number.
• For Linux, you can find the TigerVNC package in the repositories of many distributions. Check your distribution instructions for information about how to install packages. Or, download and install the relevant binary from GitHub.

Access the GUI

To access the GUI, you must first connect to your instance from your local computer with port forwarding activated for TCP port 5901. This configuration creates an encrypted SSH tunnel for VNC traffic. Then, use the VNC Viewer to connect to the GUI.

Create an encrypted SSH tunnel

Important: Make sure that your local computer's firewall allows TCP connections to port 5901.

If you use PuTTY to connect to your instance, then complete the following steps before you open the connection:

1. In the Category navigation pane, expand Connection, and then choose SSH.
2. Expand SSH, and then choose Tunnels.
3. For Source Port, enter 5901.
4. For Destination, enter localhost:5901.
5. Choose Add.

If you use an SSH client to connect to your instance, then run the following command to activate port forwarding:

ssh -L 5901:localhost:5901 -i /path/key-pair-name.pem user@instance-dns-name

Note: Replace path with your key path and key-pair-name with the name of the private key file. Replace user with the username and instance-dns-name with your instance's DNS name or IP address. The default username for AL2 is ec2-user.

If you use EC2 Instance Connect to connect to your instance, then you must run the following ec2-instance-connect AWS CLI command to activate port forwarding:

aws ec2-instance-connect ssh --instance-id i-1234567890example --connection-type direct --local-forwarding 5901:localhost:5901

Note: Replace i-1234567890example with your instance ID. If you use EC2 Instance Connect Endpoint, then replace direct with eice.

If you use Session Manager to connect to your instance, then you must start a Session Manager port forwarding session. For both the local and remote ports, enter 5901.

Use VNC Viewer to connect to the GUI

Complete the following steps:

1. Open TigerVNC Viewer on your local computer.
2. For VNC server, enter localhost:1, and then choose Connect.
3. Enter your VNC password.
   Note: If you receive an alert that the connection isn't secure, then disregard it. You're accessing the VNC server through the encrypted SSH tunnel that you created.

(Optional) Deactivate password authentication for VNC

Important: It's a best practice to deactivate password authentication for only single-user instances. When VNC password authentication is off, any user that can log on to your instance can create an SSH tunnel and access your VNC desktop.

To deactivate password authentication for VNC, complete the following steps:

1. Run the following command to change the VNC server's Security Types setting to None:

   echo SecurityTypes=None >> ~/.vnc/config

2. To restart the VNC server, run the following command:

   sudo systemctl restart vncserver@:1

(Optional) Install a web browser

AWS doesn't provide web browsers in AL2 repositories. However, you can install web browsers such as Chromium on the Chromium Projects website or Firefox browsers on the Mozilla website.

Note: AWS doesn't provide support for software that you installed from third-party sources.

The following installation steps are only for instances based on the x86_64 architecture (Intel and AMD processors). You can't use the following resolution for instances based on the aarch64 architecture (AWS Graviton processors). To check your instance's architecture, run the following command:

uname -m

Install Chromium

Complete the following steps:

1. To activate the Extra Packages for Enterprise Linux (EPEL) repository, run the following command:

   sudo amazon-linux-extras install epel

   Note: For more information, see the Extra Packages for Enterprise Linux (EPEL) on the Fedora Project website.

2. To install Chromium packages, run the following command:

   sudo yum install chromium

3. On the MATE desktop, choose Applications, and then choose Internet. You can find Chromium listed as Chromium Web Browser.

Install Firefox

Note: You can install Firefox for the current user only.

To install Firefox for the current user on your AL2 instance, complete the following steps:

1. To download the latest version of Firefox for Linux 64-bit, run the following command:

   curl -L -o ~/firefox.tar.xz 'https://download.mozilla.org/?product=firefox-latest-ssl&os=linux64&lang=en-US'

2. To extract the downloaded file contents, run the following command:

   tar Jxf ~/firefox.tar.xz -C ~/

3. To create a Firefox shortcut in your desktop, run the following command:

   echo '[Desktop Entry]
   Version=1.0
   Type=Application
   Terminal=false
   Icon=/home/ec2-user/firefox/browser/chrome/icons/default/default128.png
   Exec=/home/ec2-user/firefox/firefox
   Name=Firefox
   Comment=Firefox web browser
   GenericName=Firefox web browser
   Categories=Network;WebBrowser;' > ~/Desktop/Firefox.desktop

4. Use the desktop shortcut to launch Firefox.
   Note: If you receive a message that the application launcher isn't trusted, then choose Mark as Trusted.

Related information

How can I access my Amazon EC2 macOS instance through a GUI?