arch-desktop

An Arch Linux container running XFCE4, accessible over RDP. Built for use as a persistent, self-contained virtual work environment.

---

Requirements

• Docker 20.10+
• An RDP client:
  • Windows — built-in Remote Desktop Connection (mstsc)
  • macOS — Microsoft Remote Desktop (free, App Store)
  • Linux — remmina, freerdp, or xfreerdp

---

Building

docker build -t arch-desktop .

Build takes several minutes — xrdp and xorgxrdp compile from source via the AUR.

To customise the default user credentials at build time:

docker build \
  --build-arg USER=yourname \
  --build-arg PASS=yourpassword \
  -t arch-desktop .

---

Running

Minimal (ephemeral — nothing persists after docker rm)

docker run -d \
  -p 3389:3389 \
  --name arch-desktop \
  vc.maxkaya.com/maxpeterkaya/archdesktop:DE

DE stands for Desktop Environment. Valid image names: xfce, kde

Recommended (persistent home + reasonable resource limits)

docker run -d \
  -p 3389:3389 \
  --name arch-desktop \
  --shm-size=1g \
  --cpus=4 \
  --memory=4g \
  --memory-swap=6g \
  -v arch-home:/home/desktop \
  -v arch-config:/etc/xrdp \
  arch-desktop

Full options reference

Flag	Purpose	Suggested value
-p 3389:3389	Expose RDP port	Required
--shm-size	Shared memory for browser/GPU apps	512m – 2g
--cpus	Max CPU cores available to container	2 – 8
--memory	RAM cap	2g – 8g
--memory-swap	RAM + swap combined cap	memory × 1.5
--restart unless-stopped	Auto-restart on host reboot	Recommended for always-on use
-v arch-home:/home/desktop	Persist the user's home directory	Strongly recommended
-v arch-config:/etc/xrdp	Persist xrdp config/certs	Optional
--hostname mydesktop	Sets hostname shown inside the container	Cosmetic
--cpuset-cpus=0-3	Pin container to specific CPU cores	Performance tuning

---

Connecting

Connect your RDP client to localhost:3389.

Default credentials:

Username: desktop
Password: changeme

Change these by rebuilding with --build-arg (see above) or by exec-ing into the running container:

docker exec -it arch-desktop passwd desktop

---

Persistent volumes

Docker named volumes survive docker stop, docker rm, and host reboots.

# Create volumes explicitly (or let Docker create them on first run)
docker volume create arch-home
docker volume create arch-config

# Inspect where data lives on the host
docker volume inspect arch-home

# Back up the home volume to a tarball
docker run --rm \
  -v arch-home:/data \
  -v $(pwd):/backup \
  archlinux \
  tar czf /backup/arch-home-backup.tar.gz -C /data .

# Restore
docker run --rm \
  -v arch-home:/data \
  -v $(pwd):/backup \
  archlinux \
  tar xzf /backup/arch-home-backup.tar.gz -C /data

What each volume contains:

• arch-home — everything in /home/desktop: documents, downloads, browser profile, shell history, dotfiles, installed user-level configs
• arch-config — xrdp TLS certificates and xrdp.ini/sesman.ini; useful if you've tuned xrdp settings and don't want them reset on rebuild

---

Useful docker commands

# Start / stop without destroying data
docker stop arch-desktop
docker start arch-desktop

# Open a root shell inside the running container
docker exec -it arch-desktop bash

# Open a shell as the desktop user
docker exec -it -u desktop arch-desktop bash

# Live resource usage
docker stats arch-desktop

# Tail xrdp logs (useful for connection debugging)
docker exec arch-desktop tail -f /var/log/xrdp.log
docker exec arch-desktop tail -f /var/log/xrdp-sesman.log

# Rebuild image without touching volumes
docker stop arch-desktop
docker rm arch-desktop
docker build -t arch-desktop .
docker run -d -p 3389:3389 --name arch-desktop \
  -v arch-home:/home/desktop \
  arch-desktop

---

Installing software inside the container

The desktop user has passwordless sudo. Open a terminal in the XFCE session or docker exec in:

# Official repos
sudo pacman -S code neovim python nodejs

# AUR (yay is not pre-installed; install it once, it persists in the home volume)
cd /tmp && git clone https://aur.archlinux.org/yay.git && cd yay && makepkg -si
yay -S google-chrome visual-studio-code-bin

---

Changing the display resolution

RDP clients let you set resolution in their own settings before connecting. Inside the session you can also right-click the desktop → Display Settings to change resolution live.

For a fixed default resolution, edit /etc/xrdp/xrdp.ini inside the container (or via the arch-config volume) and set:

max_bpp=32
xres=1920
yres=1080

Then restart xrdp:

docker restart arch-desktop

---

Swapping the desktop environment

Replace xfce4-related packages in the Dockerfile and update .xinitrc:

DE	Packages	.xinitrc exec
KDE Plasma	plasma plasma-wayland-protocols kde-applications	exec startplasma-x11
GNOME	gnome gnome-extra	exec gnome-session
MATE	mate mate-extra	exec mate-session
Cinnamon	cinnamon	exec cinnamon-session
i3	i3-wm i3status dmenu	exec i3

---

Security notes

• Do not expose port 3389 directly to the internet. RDP is a common brute-force target. Use a VPN, SSH tunnel, or firewall rule to restrict access.
• Change the default password before first use.
• xrdp uses a self-signed TLS certificate by default. Mounting a real cert into /etc/xrdp/ and pointing xrdp.ini at it will silence client warnings.

SSH tunnel example (connect from a remote machine safely):

# On the remote machine — tunnel port 3389 through SSH
ssh -L 3389:localhost:3389 user@your-server

# Then RDP to localhost:3389 locally as usual

---

Troubleshooting

Black/grey screen after login The session script failed to start XFCE. Check:

docker exec arch-desktop cat /home/desktop/.xinitrc
# Should contain:
#   #!/bin/sh
#   export $(dbus-launch)
#   exec startxfce4
docker exec arch-desktop tail -30 /var/log/xrdp-sesman.log

Connection refused

docker ps                          # is container running?
docker logs arch-desktop           # any startup errors?
docker exec arch-desktop ss -tlnp  # is :3389 actually listening?

D-Bus errors in session These are usually harmless warnings from apps that expect a full systemd login session. If they cause visible breakage, exec in and run:

export DBUS_SESSION_BUS_ADDRESS=$(cat /tmp/dbus-session-address)

Or consider setting it persistently in /home/desktop/.bashrc.

Slow/choppy RDP

• Increase --shm-size and --memory
• In your RDP client, lower colour depth to 16-bit and disable font smoothing
• On Linux hosts: xfreerdp /v:localhost /u:desktop /p:changeme /gfx:rfx /rfx /clipboard