Skip to content

Run FreeEed over RDP on Ubuntu

Jump to bottom
Mark Kerzner edited this page Jun 28, 2026 · 5 revisions

Run FreeEed over RDP on Ubuntu

FreeEed is a desktop (Swing) application, so to use it on a remote Ubuntu machine — for example an AWS EC2 instance or an office workstation — you run a graphical desktop on that machine and connect to it with a Remote Desktop client. This page sets up xrdp (an open-source RDP server) on Ubuntu.

Shortcut: if you'd rather not set this up yourself, we can hand you a ready-made VM with everything installed — write to mark@scaia.ai.

1. Install a desktop environment

Ubuntu Server has no GUI, and the full GNOME desktop is unreliable over xrdp. Install the lightweight XFCE desktop, which works well with RDP:

sudo apt update
sudo apt install -y xfce4 xfce4-goodies

(On Ubuntu Desktop a GUI is already present, but installing XFCE for the RDP session still avoids the GNOME/xrdp session conflicts described below.)

2. Install and enable xrdp

sudo apt install -y xrdp
sudo adduser xrdp ssl-cert          # let xrdp read the TLS cert
sudo systemctl enable --now xrdp

Tell the RDP session to start XFCE:

echo "xfce4-session" > ~/.xsession
sudo systemctl restart xrdp

Confirm it is listening on port 3389:

sudo systemctl status xrdp
sudo ss -ltnp | grep 3389

3. Give your user a password

RDP authenticates with the Linux account password. Cloud images (e.g. AWS) often have no password set for the ubuntu user, so set one:

sudo passwd ubuntu          # use a strong password

4. Open the RDP port (3389)

Local firewall (UFW), if enabled:

sudo ufw allow 3389/tcp

On AWS: add an inbound rule to the instance's Security Group — TCP port 3389.

Security: restrict the source to your own IP, never 0.0.0.0/0. Exposing RDP to the whole internet invites brute-force attacks. Safer still, keep 3389 closed and tunnel over SSH (see below) or put the host behind a VPN.

5. Connect from your computer

Point your RDP client at your_server_ip:3389 and log in with the Linux username and the password from step 3.

  • Windows: Remote Desktop Connection (mstsc)
  • macOS: Windows App / Microsoft Remote Desktop (App Store)
  • Linux: Remmina (sudo apt install remmina)

SSH-tunnel alternative (recommended, keeps 3389 closed):

ssh -i yourkey.pem -L 3389:localhost:3389 ubuntu@your_server_ip

…then connect your RDP client to localhost:3389.

6. Install and run FreeEed in the RDP session

Once you're on the remote desktop, follow the full installation instructions. In short:

  1. Install the prerequisites — Java (Amazon Corretto) plus a few packages: 
    sudo apt update
sudo apt install -y pst-utils wkhtmltopdf tesseract-ocr nautilus
  2. Download the complete pack from the Download page and unzip it.
  3. cd freeeed_complete_pack and run ./start_all.sh.
  4. Verify the install with the bundled sample project (see Quick start).

Document conversion (LibreOffice/soffice) and OCR run inside this session just as they do locally — no extra display configuration is needed.

Troubleshooting

  • Black screen / immediate disconnect: the session manager (often GNOME) is conflicting with xrdp. Make sure ~/.xsession contains xfce4-session and that you are not also logged into the same user at the physical console — xrdp and a local GNOME session can't share one login.
  • "Connection refused": xrdp isn't running (sudo systemctl restart xrdp) or port 3389 is blocked (recheck UFW and, on AWS, the Security Group).
  • Login fails: the account has no/!wrong password — rerun sudo passwd <user>.
  • Authentication popups inside the desktop (color profile / system prompts): harmless on a server; click Cancel, or install sudo apt install -y policykit-1-gnome to dismiss them.

See also: Quick start, Prerequisites.

Clone this wiki locally