Run FreeEed over RDP on Ubuntu

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 installation instructions to install Java and any optional tools, then download and unzip the complete pack, cd freeeed_complete_pack, and run ./start_all.sh. Verify with the bundled sample project (see Quick start).

Install a web browser. The minimal XFCE desktop ships without one, and FreeEed opens the Review and AI Advisor as web pages — without a browser you'll get a Failed to execute child process "www-browser" error. Install Google Chrome and make it the default:

cd /tmp
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install -y ./google-chrome-stable_current_amd64.deb

# point the www-browser alternative at Chrome (the handler XFCE looks for)
sudo update-alternatives --install /usr/bin/www-browser www-browser /usr/bin/google-chrome-stable 200
sudo update-alternatives --set www-browser /usr/bin/google-chrome-stable
xdg-settings set default-web-browser google-chrome.desktop

Test it with xdg-open https://example.com.

Prefer not to install a browser on the VM? The Review is just a local web app at http://localhost:8080/freeeedui. Forward that port over SSH and open it in the browser on your own laptop instead:

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

If you used the Linux .run installer instead, launch FreeEed Control Panel from the Applications menu (under Accessories / Office), or run it directly: ~/.local/share/FreeEed/ControlPanel.sh.

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.
• Failed to execute child process "www-browser": no web browser is installed (the minimal desktop has none), so the Review/AI pages can't open. Install Chrome and set it as the default (see step 6) — or open the Review from your laptop via the SSH port-forward in step 6.

See also: Quick start, Prerequisites.