# TigerVNC + Guacamole Setup Guide for Ubuntu EC2 (Private Subnet)

This document explains how to correctly install, configure, and auto-start TigerVNC on an Ubuntu EC2 instance running in a **private subnet**, and how to connect to it using **Apache Guacamole** running inside Docker.

It also covers common issues such as authentication failures, systemd misconfiguration, DNS problems, and password setup issues.

---

## ## 1. Install TigerVNC on the EC2 Instance

```bash
sudo apt update
sudo apt install -y tigervnc-standalone-server tigervnc-common xfce4
```

---

## 2. Create the VNC Password (Required for Guacamole)

### Stop any running VNC server first:
```bash
sudo systemctl stop vncserver@1
```

### Switch to the correct user and deactivate any venv:
```bash
sudo su - ubuntu
deactivate 2>/dev/null
```

### Set the VNC password:
```bash
/usr/bin/vncpasswd
```

Expected output:
```
Password:
Verify:
Would you like to enter a view-only password (y/n)? n
```

### Verify the password file:
```bash
ls -l ~/.vnc/passwd
```
Should show today’s timestamp.

---

## 3. Create the Systemd Service File

Create the template:
```bash
sudo nano /etc/systemd/system/vncserver@.service
```

Paste this:

```ini
[Unit]
Description=VNC Server for display %i (user ubuntu)
After=network.target

[Service]
Type=simple
User=ubuntu
PAMName=login
PIDFile=/home/ubuntu/.vnc/%H:%i.pid
WorkingDirectory=/home/ubuntu
ExecStartPre=-/bin/sh -c 'rm -f /tmp/.X*-lock /tmp/.X11-unix/X%i'
ExecStart=/usr/bin/vncserver :%i -fg -geometry 1920x1080 -depth 24 -rfbport 5901
ExecStop=/usr/bin/vncserver -kill :%i
Restart=on-failure
TimeoutStartSec=30

[Install]
WantedBy=multi-user.target
```

---

## 4. Enable & Start the VNC Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable vncserver@1
sudo systemctl start vncserver@1
```

### Confirm it runs as `ubuntu`:
```bash
ps aux | grep Xtigervnc
```
Should show:
```
ubuntu   <pid>   Xtigervnc ...
```

If it shows **root**, VNC auth will fail.

---

## 5. Security Group Configuration

### On the VNC server EC2:
Allow inbound:
```
TCP 5901 → Source: security group of Guacamole server
```
(Do NOT open to the world.)

---

## 6. Configure Guacamole Connection

In the connection settings:

### **GUACD Parameters**
```
Hostname: guacd
Port: 4822
Encryption: None
```

### **VNC Network Settings**
```
Hostname: 10.0.2.17      ← PRIVATE IP ONLY
Port: 5901
```

### **Authentication**
```
Username: (leave blank)
Password: (the VNC password you set using vncpasswd)
```

### IMPORTANT
Do **not** use EC2 internal DNS names like:
```
ip-10-0-2-17.ap-southeast-2.compute.internal
```
Docker containers cannot resolve them.

---

## 7. Troubleshooting

### **Check VNC Logs**
```bash
cat /home/ubuntu/.vnc/*.log
```

### **Check if VNC is listening**
```bash
sudo ss -tulpn | grep 5901
```
Should show:
```
LISTEN 0 5 0.0.0.0:5901
```

### **Check GUACD logs (inside Guacamole EC2)**
```bash
docker logs guacd
```

### Common GUACD Errors

| Error | Meaning | Fix |
|-------|---------|------|
| `Unable to connect to VNC server` | DNS or wrong IP | Use raw IP (10.x.x.x) |
| `Authentication failed` | Wrong password | Reset password with `/usr/bin/vncpasswd` |
| `Connection refused` | VNC not running | Restart service |

---

## 8. Resetting VNC Password If Needed

Stop the service:
```bash
sudo systemctl stop vncserver@1
```

As ubuntu:
```bash
sudo su - ubuntu
deactivate 2>/dev/null
rm ~/.vnc/passwd
/usr/bin/vncpasswd
```

Restart VNC:
```bash
sudo systemctl start vncserver@1
```

---

## 9. Ensuring VNC Works After Reboot

After reboot test:

```bash
systemctl status vncserver@1
ps aux | grep Xtigervnc
```

If it runs as **root** → service file is wrong.
If password file is wrong permissions:

```bash
sudo chown ubuntu:ubuntu /home/ubuntu/.vnc/passwd
sudo chmod 600 /home/ubuntu/.vnc/passwd
```

---

## 10. Summary Checklist

- [ ] VNC installed
- [ ] Password created with `/usr/bin/vncpasswd`
- [ ] Systemd template created
- [ ] Service enabled: `systemctl enable vncserver@1`
- [ ] VNC runs as ubuntu at boot
- [ ] Security group allows 5901 from Guacamole SG
- [ ] Guacamole uses `10.x.x.x` IP
- [ ] GUACD set to `guacd:4822`

---

## Done!
This guide can be used every time you create a new EC2 instance to ensure Guacamole + VNC works correctly — even after reboot.