Installing the CMS server

This is the order for setting up the CMS server at a site. It is written so you can follow it without specialist knowledge — the installer checks whether everything is ready by itself, and installs what it needs.

What you need

• On a Windows PC, start by creating a Hyper-V virtual machine — begin at step 0.
• If you already have a PC or virtual machine with Ubuntu 26.04 LTS installed, start at step 1. (At least 6GB of memory and 120GB of disk recommended — the disk is where content accumulates)
• Ubuntu installation image: ubuntu-26.04.x-live-server-amd64.iso (the Server edition)
• The installation package folder you received when adopting TreeT (copy it over on a USB drive or similar)
• A network for this PC to connect to (internet access is not strictly required for installation — see below)

Before you start — gather what you received in one place

Put everything you received into C:\treet on the Windows PC. If the folder doesn’t exist, create it.

The package you receive looks like this — move it as a whole folder.

C:\treet\
  읽어주세요.md                      ← 🔴 **Read this first.** It contains this site's values
  목록.md                            ← list of included files and their sha256
  TreeT_코드서명_공개인증서.cer      ← 🔴 register on each kiosk **before installing**
  check-install.ps1                  ← script that checks whether installation went correctly
  설치파일\                          ← installers for the kiosks (+ Android APK)
  CMS\treet-cms-offline-<version>.tar.gz  ← CMS installation package
  매뉴얼\                            ← offline copy of this manual
  키오스크셋팅\                      ← kiosk PC optimization scripts

(읽어주세요.md = Read me, 목록.md = file list, 설치파일 = installers, 매뉴얼 = manual, 키오스크셋팅 = kiosk setup.)

Download one more item and put it in the same place — we don’t provide it:

  ubuntu-26.04.x-live-server-amd64.iso   ← Ubuntu to install in the virtual machine (download from ubuntu.com)

C:\treet is a convention, not a requirement

The installers work relative to the folder they are in — they run wherever you put them. There are still two reasons to settle on one place.

• Later, it is in the same place no matter who looks. Once there are several sites, this makes a big difference.
• When we guide you over the phone, “that folder” means the same place to both of us.

Just avoid these places

Don’t put it inside OneDrive, Dropbox, or the Desktop. In sync folders, the configuration files and data keep being synchronized, causing conflicts and locks; the Desktop is inside a user account, so it isn’t visible when logged in with another account. C:\treet is neither.

The CMS is not installed from this folder

C:\treet is a place to gather things. The CMS is installed inside a virtual machine (Ubuntu), so the treet-cms-offline package is later moved into the VM (step 1). The contents of 설치파일 (installers) are moved to each kiosk PC and run on that PC.

The whole process at a glance

If this is your first time, look over this map once before starting. You’re done after going from top to bottom once.

	What	How long	Who does it
Prep	Gather what you received in C:\treet (just above)	5 min	You
0	Create the virtual machine and install Ubuntu	30–60 min	You
0-e	🔴 Expand the disk — Ubuntu uses only half	1 min	You
1	Move the installation package into the VM	5–10 min	You
2	Run sudo bash install.sh	1 min	You
3	Readiness checks	Automatic	The installer
4	Answer three questions	1 min	You
5	Write down the administrator password	1 min	You
6	Confirm it actually comes up	Automatic (a few minutes)	The installer
7	Turn on backups — automatic · just check	1 min	The installer
7-b	Install Watchdog on this PC — restarts the CMS VM if it stops	5 min	You
8	Prepare remote access	When needed	You
9	Internet address and certificate + admin entrance	20 min	You (token, browser approval) + script

When you’re done

The admin console opens in a browser at http://<this PC's address>:8080, and you can log in as the administrator. From there you register devices and schedule content.

What the installer does by itself and what you do

Steps 3 and 6 are sections to read and move past — the installer does them, and there’s nothing for you to do. The rest (prep · 0 · 0-e · 1 · 2 · 4 · 5 · 7) is up to you.

🔴 Of those, two are easy to forget: 0-e expanding the disk (if you skip it, you won’t find the cause later) and 7 turning on backups (this site’s certificate cannot be recreated).

If it stops partway

The installer checks before doing anything irreversible, and if it gets stuck it writes on screen what to do and how. Just follow that text — there’s no need to come back to this document to look it up.

0. Create the virtual machine (Hyper-V)

The CMS runs inside an Ubuntu virtual machine. On a Windows PC, create that VM first.

Why a virtual machine?

The CMS runs on Docker, and Docker is stable when it runs on Linux.

0-a. Turn on Hyper-V and create an external switch

In Control Panel → Programs → Turn Windows features on or off, check Hyper-V and reboot.

If Hyper-V is not in the list

It isn’t available in Windows Home. You need Pro or higher. Also, if virtualization (Intel VT-x / AMD-V) is turned off in the BIOS, turn it on.

After rebooting, create the external switch before the VM. For the kiosks to connect to this VM, the VM must be connected to this PC’s physical network card.

Using the GUI: Hyper-V Manager → Virtual Switch Manager → New virtual network switch → External → name it TreeT-External → choose the network card this PC actually uses. ⚠️ If you created it through the GUI, be sure to also do ③ Check and fill in DNS from the commands below afterwards (with a static IP, DNS gets dropped).

Using commands (administrator PowerShell) — this also takes care of missing DNS in one go:

# ① Check the network card name — the one on the same network as the kiosks (usually '이더넷' / Ethernet)
Get-NetAdapter -Physical | Format-Table Name, InterfaceDescription, Status, LinkSpeed

# ② Enter the Name from the list above
$Switch = "TreeT-External"
$Nic    = "이더넷"

# Remember the current settings before creating it — with a static IP, only DNS disappears when the switch is created
$Static = (Get-NetIPInterface -InterfaceAlias $Nic -AddressFamily IPv4).Dhcp -eq "Disabled"
$Dns    = (Get-DnsClientServerAddress -InterfaceAlias $Nic -AddressFamily IPv4).ServerAddresses
"고정 IP: $Static · 지금 DNS: $($Dns -join ', ')"

# Create the switch — skipped if it already exists (⚠️ the network drops for a few seconds)
if (-not (Get-VMSwitch -Name $Switch -ErrorAction SilentlyContinue)) {
    New-VMSwitch -Name $Switch -NetAdapterName $Nic -AllowManagementOS $true | Out-Null
}

# ③ Check and fill in DNS — if the new adapter has no DNS, fill it in
#    With a static IP, DNS doesn't carry over, and even with an automatic IP it sometimes isn't picked up right away.
#    So it is filled in **whenever it's empty**, regardless of static or automatic.
$vEth = "vEthernet ($Switch)"
for ($i = 0; $i -lt 10 -and -not (Get-DnsClientServerAddress -InterfaceAlias $vEth -AddressFamily IPv4).ServerAddresses; $i++) { Start-Sleep 2 }
if (-not (Get-DnsClientServerAddress -InterfaceAlias $vEth -AddressFamily IPv4).ServerAddresses) {
    if (-not $Dns) {
        # If DNS was empty to begin with, use the router (gateway) and a public DNS
        $Gw  = (Get-NetIPConfiguration -InterfaceAlias $vEth).IPv4DefaultGateway.NextHop
        $Dns = @($Gw, "8.8.8.8") | Where-Object { $_ }
    }
    Set-DnsClientServerAddress -InterfaceAlias $vEth -ServerAddresses $Dns
    Clear-DnsClientCache
}

# ④ Check — both must show results
Get-VMSwitch $Switch | Format-Table Name, SwitchType, NetAdapterInterfaceDescription
Get-DnsClientServerAddress -InterfaceAlias $vEth -AddressFamily IPv4 | Format-Table InterfaceAlias, ServerAddresses
Resolve-DnsName ubuntu.com -Type A | Select-Object -First 1 Name, IPAddress

If internet names don’t resolve after creating the switch on a static-IP PC — DNS is missing

Symptom: the cable and IP are fine, but you can’t reach sites by name, and the DNS servers in ipconfig /all show only fec0:0:0:ffff::1. That isn’t a real server — it’s a placeholder Windows puts in when there are no DNS settings.

To fix it — redo ③ above, or enter it directly (adjust the router address for your site):

Set-DnsClientServerAddress -InterfaceAlias "vEthernet (TreeT-External)" -ServerAddresses 192.168.0.1, 8.8.8.8
Clear-DnsClientCache
Resolve-DnsName ubuntu.com

⚠️ Don’t check with ping — many sites’ routers block ICMP, so it fails even when everything is fine. To see whether you can reach the DNS server, use Test-NetConnection 192.168.0.1 -Port 53. 🔵 Ubuntu inside the VM may be blocked too — after fixing the host, check from the VM with resolvectl query ubuntu.com. 🔵 At DHCP (automatic IP) sites the new adapter usually gets DNS, but sometimes it is empty at first — if it’s empty in ④ above, fill it in the same way.

If you choose an internal or private switch, the kiosks can’t connect

Make sure the type is External. ⚠️ The moment it is created, this PC’s network drops for a few seconds — if you are working over a remote connection, you may be disconnected.

0-b. Create the VM

Hyper-V Manager → New → Virtual Machine.

Item	Value	Why this value
Generation	Generation 2	UEFI boot. Generation 2 is the default for Ubuntu 26.04
Memory	6 GB (dynamic memory off)	Measured idle use is 214 MB, but installation, DB import, and video conversion need headroom
Processor	4 cores	Video conversion uses the CPU — this is where extra investment is felt most
Hard disk	120 GB · dynamically expanding	The program is small (about 200 MB), but media and images accumulate. Because it’s dynamic, it doesn’t take 120 GB from the start
Network	TreeT-External (the external switch created in 0-a)	The kiosks must be able to connect to this VM
Secure boot template	Microsoft UEFI Certificate Authority	If left at the default (Windows), Ubuntu won’t boot

Don’t make the disk small

This is where content accumulates. You can enlarge it later, but you have to shut down the VM and also adjust the partitions. Because it’s dynamically expanding, even at 120 GB it only takes up as much as is actually used.

One command is more accurate than the wizard

If you miss even one value, it’s a hassle to fix later. After creating the switch in 0-a, paste the following into administrator PowerShell. It finds and uses the Ubuntu installation image you downloaded to C:\treet in the prep step.

$VM     = "treet-cms"
$Root   = "C:\treet\HyperV"          # where the VM disk goes — under C:\treet, where you gathered everything
$Switch = "TreeT-External"
# Find the Ubuntu installation image downloaded to C:\treet in the prep step
$Iso    = (Get-ChildItem "C:\treet\ubuntu-26.04*-live-server-amd64.iso" | Select-Object -First 1).FullName
if (-not $Iso) { throw "C:\treet 에 Ubuntu 설치 이미지(ubuntu-26.04.x-live-server-amd64.iso)가 없습니다 — 먼저 받아 두세요" }

# Create the VM
New-Item -ItemType Directory -Force -Path "$Root\$VM" | Out-Null
New-VM -Name $VM -Generation 2 -MemoryStartupBytes 6GB -NewVHDPath "$Root\$VM\$VM.vhdx" -NewVHDSizeBytes 120GB -SwitchName $Switch | Out-Null
Set-VMMemory    $VM -DynamicMemoryEnabled $false
Set-VMProcessor $VM -Count 4
Set-VM          $VM -AutomaticStartAction Start -AutomaticStopAction ShutDown

# Make Ubuntu bootable — secure boot template · installation image · boot order
Set-VMFirmware $VM -SecureBootTemplate MicrosoftUEFICertificateAuthority
Add-VMDvdDrive $VM -Path $Iso
Set-VMFirmware $VM -FirstBootDevice (Get-VMDvdDrive $VM)

# Start it and open the console
Start-VM $VM
vmconnect.exe localhost $VM

🔵 Name the VM treet-cms for consistency. 🔵 AutomaticStartAction Start means the VM starts when the host starts — so after a power outage, nobody has to go on site.

Two common sticking points

• The TreeT-External switch cannot be found — you haven’t created the switch in 0-a yet. The switch must exist before the VM. If an earlier attempt left only C:\treet\HyperV\treet-cms\treet-cms.vhdx behind, delete that file and create it again.
• The VM doesn’t boot and hangs — the secure boot template is still set for Windows. MicrosoftUEFICertificateAuthority is the one for Ubuntu.

0-c. Attach the installation image and start the VM

🔵 If you created the VM with the commands above, the image is already attached and the VM is running — skip to 0-d.

If you used the wizard: attach the downloaded ubuntu-26.04.x-live-server-amd64.iso to SCSI Controller → DVD Drive in the VM settings and start the VM.

If it won’t boot — secure boot

The default secure boot template for Generation 2 VMs is Windows only, so Ubuntu won’t boot. In VM settings → Security, change the template to “Microsoft UEFI Certificate Authority” (this is the -SecureBootTemplate line in the commands above).

0-d. Install Ubuntu

You can accept the defaults, but pay attention to just two things — a static IP (+DNS) and OpenSSH.

① Network — give the VM a static IP

The kiosks connect to the CMS at this address, and during CMS installation this address is also put into the certificate. If it changes, the kiosks disconnect, so use a static IP.

First decide the address — it must be an unused address in the same range as the host PC, and outside the range the router hands out automatically (DHCP). On the host, check the range and the router (default gateway) with ipconfig.

Example	Value
Host PC	192.168.0.4
Router (gateway)	192.168.0.1
Address to give this VM	192.168.0.10 (adjust for your site)

On the installation screen — Network configuration → eth0 → Edit IPv4 → Manual:

Field	Value
Subnet	192.168.0.0/24
Address	192.168.0.10
Gateway	192.168.0.1
Name servers	192.168.0.1, 8.8.8.8
Search domains	Leave empty

Don’t leave Name servers empty — the most common sticking point on site

If you leave it empty, the cable and IP are fine but name resolution alone fails, so it looks as if nothing works — the cause isn’t visible, so you can waste a long time. Enter the router address and 8.8.8.8. (If there is an in-house DNS server, put that first.)

If you’ve already finished installing — configure it inside the VM. First check the network card name (usually eth0).

ip -br link

sudo tee /etc/netplan/60-treet-static.yaml > /dev/null <<'EOF'
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: false
      addresses: [192.168.0.10/24]
      routes:
        - to: default
          via: 192.168.0.1
      nameservers:
        addresses: [192.168.0.1, 8.8.8.8]
EOF
sudo chmod 600 /etc/netplan/60-treet-static.yaml
sudo netplan try

🔵 After applying, netplan try reverts to the previous settings unless you press Enter within 120 seconds — so it’s safe even if a mistake cuts off the connection. After pressing Enter, check:

ip -4 addr show eth0 | grep inet
resolvectl query ubuntu.com

② Check Install OpenSSH server

Connecting from another PC to work is far easier than typing directly on the VM screen. You also use it to move the installation package.

When installation finishes, reboot, log in, and check with the command below that the static IP you chose is assigned.

ip -4 addr show | grep inet

0-e. 🔴 Must do right after installation — expand the disk

The Ubuntu installer uses only half the disk. Even if you give it 120 GB, the space actually used is about 58 GB.

sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv
df -h /

It worked if df -h / shows 100 GB or more.

If you skip this, you won’t find the cause later

You’ll be left wondering “I gave it 120 GB, so why is it already full?”. It takes 30 seconds now; later, you have to stop the service to do it.

You don’t need to install Docker

install.sh checks for it at startup and installs it itself if it’s missing. ⚠️ However, automatic installation requires internet access. On a closed network, install Docker beforehand — the checks recognize that situation and tell you.

Once you’re here, go on to step 1 below.

1. Move the installation package into the VM

Move the single file CMS\treet-cms-offline-<version>.tar.gz from the package into the VM and extract it there. Inside the VM, put it in a fixed local path. For example: /home/user/

How do I move it?

Use whichever of these three is convenient.

• Via SSH (if you turned on OpenSSH in 0-d) — from Windows: scp C:\treet\CMS\treet-cms-offline-<version>.tar.gz user@<VM-address>:~/
• Via USB — attach USB in the VM settings, or share a host folder
• Via a network share — share a Windows folder and mount it in the VM

🔵 It’s a single file (1.3 GB), so it’s much faster than moving a whole folder. It takes a few minutes.

Once it’s moved, extract it inside the VM.

cd ~
tar xzf treet-cms-offline-*.tar.gz
cd treet-cms-offline

Don’t put it in a cloud sync folder

If you put it inside a sync folder such as OneDrive or Dropbox, the configuration files and data keep being synchronized, causing conflicts or locks. The installer warns you if it detects this.

2. Start the installation

Inside the folder, run the following.

sudo bash install.sh

It is run with sudo because the installer installs items that aren’t ready (such as Docker) itself.

3. The installer checks things first (read and move on)

🔵 There’s nothing for you to do here. The installer checks by itself — the following explains what it checks, and is written down so you can come back and look it up if you get stuck.

If anything is missing, it tells you on screen what to do and how.

Check	If there’s a problem
Operating system	Tells you if it’s not Ubuntu 26.04 LTS (installation continues)
Name resolution (DNS)	If it fails, tells you the cause too — see below
Internet connection	Normal on a closed network (Docker must already be installed)
Docker	If missing, installs it automatically
Clock	Tells you if the time is far off
Disk · memory	Stops if there isn’t enough
Ports	Stops if another program is already using them
File permissions	Tells you if the location doesn’t enforce them (installation continues) — see below

The most common sticking point at sites that use a static IP

If you set a static IP but don’t enter DNS servers, name resolution fails. The network cable is plugged in, but it looks as if nothing works.

The installer recognizes this case, tells you, and shows how to fix it. Add the following to the configuration file in /etc/netplan/ and run sudo netplan apply.

      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]

If this PC is a Hyper-V virtual machine, the host (Windows) side has the same trap — when you create a virtual switch, the IP moves over but DNS doesn’t follow. For how to fix it, see “DNS is missing” in 0-a.

Installing on a Windows drive leaves private keys unprotected

If you install in a place where Linux borrows a Windows drive (/mnt/c, /mnt/d, etc.), that location only pretends to enforce file permissions. Installation works and the CMS runs normally, but the site’s private keys are open to other users on that PC.

This applies especially to the key for issuing site certificates — that key cannot be recreated (recreating it disconnects every player already registered).

Recommendation: install in a place Linux uses as its own disk (e.g. /home/user/…). The installer tells you about this situation but does not stop you — you should choose knowingly.

4. It asks three questions

Once the checks pass, it asks only the three questions below. Everything else is configured automatically.

① This site’s name

1) 이 사이트의 이름 (영문 소문자·숫자·하이픈).
   추천: kjr7zbs  ← 지금 사용 가능한 이름입니다
   >

(The prompt asks for the site’s name — lowercase letters, digits, and hyphens — and suggests a name that is currently available.)

You can use the suggested name as is (press Enter). This name is used to tell apart the signals exchanged with the devices.

Why a meaningless name?

When a public certificate is issued for the site address, that name stays in public records permanently. Using a company or branch name would expose the customer list, so a meaningless name is used.

② The address for accessing this CMS

2) 이 CMS 에 접속할 주소입니다 — 재생기가 이 주소로 붙습니다.
   여러 개면 쉼표로 나열하세요. [192.168.0.5]
   >

(The prompt asks for the address the players will use to connect to this CMS; separate several with commas.)

The value in square brackets is this PC’s address, detected automatically. If it’s correct, just press Enter.

③ The address from the outer network

3) 바깥 망에서 이 CMS 로 들어오는 주소가 있으면 적으세요 — 공유기 포워딩 주소(여러 개면 쉼표).
   이름으로 붙는 것이 먼저입니다. 이름이 안 풀리는 망(폐쇄망 · 이중 NAT 바깥)에서 쓰는 IP 만 적으세요. 없으면 엔터.
   >

(The prompt asks for any address through which devices on an outer network reach this CMS — the router forwarding address; separate several with commas. Connecting by name comes first; enter only IPs used where names do not resolve. Press Enter if there is none.)

Most sites just press Enter (leave it empty). Fill it in only when devices or a relay on an outer network — for example behind two routers — must reach this CMS by the router’s forwarding address (IP). The addresses you enter go into the CMS certificate. If it needs to change after installation, it is changed from the admin screen without reinstalling — contact your administrator.

5. Write down the administrator password

When installation finishes, the initial administrator password is shown once.

You can’t see this value again

It is shown on screen only once. Be sure to write it down. After logging in, we recommend that each person change to their own password.

6. The installer checks itself (read and move on)

🔵 A one-screen check appears at the end — the results of the four host settings (time zone set to the site time · Docker starting at boot · the KVP daemon on Hyper-V · the backup schedule), plus the CMS status address, the next scheduled times and this machine’s address. For a line marked ⚠️, run the command that line shows (the installation still succeeded).

Finally, the installer checks that the screens actually come up. Sometimes the screens don’t appear even though the containers are running, so it checks not “the command finished” but “it actually responds”.

설치 검증 (실제로 응답하는지 — 최초 설치는 DB 초기화로 몇 분 걸립니다)...
  ✓ 컨테이너 web 동작
  ✓ 컨테이너 laravel 동작
  ✓ 컨테이너 db 동작
  ✓ 컨테이너 guacd 동작 (원격제어)
  ✓ 컨테이너 guacamole 동작 (원격제어)
  ✓ CMS 응답 확인 (HTTP 200)

(Installation verification: each container — web, php, db, and the two remote-control containers guacd and guacamole — is running, and the CMS responds with HTTP 200. The first installation takes a few minutes while the DB is initialized.)

Once you see this, you can connect in a browser at http://<this PC's address>:8080.

Installation is fine even if the two remote-control lines show ⚠️

The screens run fine; only the [Remote view] · [Open with control] buttons can’t be used. To fix it, do as that line says: docker compose up -d guacd guacamole.

If you see a warning like this when reinstalling

When you reinstall on the same PC, the installer keeps the existing settings (so the site settings aren’t wiped). So if a secret in .env is still the default value, a line like this appears:

🔴 이 사이트가 **다른 사이트와 같은 시크릿**을 쓰고 있습니다: LARAVEL_APP_KEY

(It says this site is using the same secret as other sites.) This means that site’s own secret has not been created yet. As shown on screen, change that value in the .env file — this doesn’t appear on new installations.

⚠️ Changing LARAVEL_APP_KEY logs everyone out once (just log in again).

7. Turn on backups (be sure to do this)

🔵 The installer does this itself — daily at 03:40 (site time) · kept 14 days · in the installation folder’s backup/. Use the steps below to check it is on or to change the location (installing it again is fine).

sudo bash docker/install-backup-timer.sh

Every day before dawn, it backs up settings, certificates, and the database as one bundle and keeps them for 14 days.

Decide where to keep backups

The default location is backup/ inside the installation folder. It’s convenient, but if you later move or delete the installation folder as a whole, the backups disappear with it. We recommend a location outside the installation folder.

sudo bash docker/install-backup-timer.sh '*-*-* 03:40:00' 14 /var/backups/treet

The three values are, in order, run time · days to keep · storage location. For extra safety, put this folder on another disk or a NAS.

Without backups, recovery is impossible

The certificates that exist only at this site cannot be recreated. If new ones are made, the players already registered can’t connect to the CMS. Backing up only the database is not enough to recover.

Run it once by hand and check that a file is actually created.

sudo systemctl start treetweb-backup-site.service
ls -la backup/

7-b. Install Watchdog on this PC — it restarts the CMS if it stops

The CMS runs inside a virtual machine on this PC. If that VM stops, screen management at the site is cut off entirely, and the VM cannot report that by itself. So Watchdog guards it from outside (this Windows PC).

1. Install Watchdog the same way as on a player PC — see the Watchdog installation in Site deployment. When the installer asks for the CMS address, enter this VM’s address (e.g. http://192.168.0.5:8080).

2. Nothing else to do. When Watchdog starts, it finds the VM with the same IP as the CMS address by itself and starts watching it.

3. ⚠️ But the Hyper-V integration tools must be running inside the VM for Watchdog to see the VM’s IP (the installer sets them up automatically — it needs internet). Check on this Windows PC (administrator PowerShell):

   Get-VMNetworkAdapter -VMName treet-cms | Select-Object -ExpandProperty IPAddresses

   If the VM’s address (e.g. 192.168.0.5) does not show and the result is empty, install and start the integration tools inside the VM (needs internet):

   sudo apt install -y linux-cloud-tools-$(uname -r)
   sudo udevadm trigger --subsystem-match=misc --action=add
   sudo systemctl restart hv-kvp-daemon

   When the command above shows the address, you are done. Within 10 minutes the CMS log shows “this PC’s Hyper-V VM ‘treet-cms’ was recognized as the CMS and added to monitoring”.

   🔵 This state is reported for you — if the VM is running but its IP is not visible, the monitoring line in the CMS log says ”… the IP is not visible to Hyper-V: hv-kvp-daemon … must run inside the VM …”. When you see that line, run the three lines above.

🔵 If Watchdog is already installed on the PC, do not install it again — that is the case at sites where the player and the CMS share one PC. That Watchdog guards the CMS too.

With it running:

When this happens	Watchdog
The VM is turned off or paused	Turns it back on (checks every 3 minutes)
The CMS does not respond for more than 3 minutes	Records it in the CMS log, and when it recovers, adds one line: “no response from … to … (N minutes)“
The VM is on but only the CMS does not respond	Only reports it — Watchdog cannot touch programs inside the VM

When you turn the VM off on purpose for maintenance

Watchdog will turn it back on within 3 minutes. If it needs to stay off for a while, ask your administrator to pause the watch.

If you installed directly on an Ubuntu PC without a virtual machine — the installer installs Watchdog too

When step 2 (sudo bash install.sh) detects a physical PC, it installs Watchdog as well and has it guard the CMS. There is nothing else to do — you will see “Watchdog(CMS 돌보기): …” lines on the install screen.

• Stopped CMS programs normally restart by themselves. Watchdog handles only the cases where that does not happen — it brings back just the one left stopped, or everything if all of them are gone (every 3 minutes).
• If a health check fails, it only reports it — so as not to take down a running database.
• If the CMS does not respond for more than 3 minutes, it is recorded the same way as above.

⚠️ If the install screen says it did not install, do what that line says (e.g. if ps is missing, run apt-get install procps and try again).

When you stop the CMS on purpose for maintenance

Even if you stop it with docker compose stop, the Watchdog brings it back up within 3 minutes (reviving what is left stopped is the rule above). If you need it stopped for long, turn monitoring off for that time.

8. How to connect remotely (these are two different things)

People often confuse these, so they are written up separately.

8-a. To connect to this CMS PC — use SSH

The installer doesn’t install it. Checking Install OpenSSH server when installing Ubuntu is what takes care of it (see 0-d).

If you didn’t, install it now.

sudo apt install -y openssh-server
systemctl status ssh

If you can’t connect, check the following in order.

Check	Command · location
Is SSH running?	systemctl status ssh
This PC’s address	ip -4 addr show | grep inet
🔴 Is the VM on an external switch?	Hyper-V Manager → VM settings → Network adapter. If it’s internal/private, you can’t connect from outside
Firewall	sudo ufw status (off by default)

8-b. To view a device’s screen — use the remote-control feature

This feature lets you look at a kiosk’s screen in the browser from the CMS admin console. It is on as soon as it is installed — there’s nothing else to do.

There’s no separate address to connect to

The remote-control program doesn’t open any ports to the outside. The CMS receives connections in front of it and passes them on, so only people logged in to the CMS can use it.

How to use it: admin console → Devices → click a device to open its device page → the [Remote view] (or [Open with control]) button at the top → a new tab opens. The only address involved is the CMS address you always use.

🔴 You must install UltraVNC on each device

The CMS side is ready, but the part that sends out the screen lives on the device. Install and run a VNC server (UltraVNC) on every kiosk PC.

On the device	Value
VNC server	UltraVNC (set to start automatically after installation)
Port	5900 (leave the default)
Password	No need to set one — each time a button is pressed, that PC’s Watchdog sets a one-time password (from CMS 2026.9.725 · Watchdog 2026.9.153)

On the CMS side, in most cases just leave it empty (the IP reported by the device · 5900). Only when the address or port differs, enter address[:port] in the Devices → device page → Edit basic information → “Remote access” field of the admin console — do not enter a password.

Devices with an old Watchdog use the site-wide password

A device with a Watchdog version that can’t do one-time passwords yet connects with GUACAMOLE_VNC_PASSWORD in .env. If that value differs from the device’s UltraVNC password, the tab opens but the screen is just black — it doesn’t look like a connection failure. The easiest fix is to update that device’s Watchdog to a new version.

If pressing [Remote view] doesn’t work

Symptom	Cause
”원격제어가 구성되지 않았습니다” (Remote control is not configured)	GUACAMOLE_JSON_SECRET_KEY in .env is empty (the installer creates it, so this rarely happens)
A new tab opens with 502	The remote-control containers aren’t running → docker compose up -d
The tab opens but no screen appears	It’s UltraVNC on the device — see above
Watchdog 응답 없음 (Watchdog not responding)	That PC’s Watchdog is off or its heartbeat interval is long — the last response on the device page’s Watchdog tab
The new tab doesn’t open at all	The browser’s pop-up blocker — allow this CMS address

There is no setting to turn it off

Remote control is always on in the installed package — there is no separate setting to turn it off. To pause it, run docker compose stop guacamole guacd. While it is stopped, the remote access button answers “원격제어 서비스가 실행 중이 아닙니다” (“the remote control service is not running” — this message is shown in Korean). To turn it back on, run docker compose up -d guacd guacamole (the message also ends with this command). ⚠️ It comes back on with an update or reinstall (up -d starts it again) — this is not a permanent switch.

9. Internet address and certificate — set up both entrances together

A site has two entrances. The default setup uses both.

Address	Who uses it	How it comes in
https://<site>.treetsites.com:8443	Devices · large video uploads · day-to-day administration	Router → straight to the CMS (public certificate)
https://admin-<site>.treetsites.com	Administrators only — an emergency entrance for when the router port is blocked	Cloudflare tunnel

Don’t put the admin entrance into devices

Put only the first address into the CMS address of devices (player, Watchdog, SyncServer). The tunnel decrypts traffic once along the way, so device certificates don’t work through it — the symptom is “it connects but authentication fails”, which makes the cause hard to find. You can’t upload files larger than 100MB through the admin entrance (a Cloudflare limit). Upload large videos through the first address.

TreeT staff set up the two entrances

The certificate and the admin entrance are created under the treetsites.com name that TreeT manages, so TreeT staff do this during installation. The only thing the site needs to prepare is router port forwarding — outside 8443 → CMS VM 8443. When it is done, check that both addresses open with 9-e below.

9-e. Check

On the VM:

sudo ./cert-check.sh            # is it a public certificate · how many days until it expires
sudo ./install-tunnel.sh --check  # tunnel service · response from outside

Then open both addresses yourself in a Windows browser — both must show a padlock icon, and no warning screen should appear. 🔵 If the first address won’t open from the network inside the site, the router is blocking connections that loop back to its own public IP (hairpinning) — check using mobile data, or use the admin entrance.

Time server — the CMS gives devices the time

Installing the CMS also starts a time server (NTP). There is no switch to turn it off — it must be ready the moment a device turns on time sync. Devices on the same internal network get the time from this CMS over UDP 123. Even on a closed network that can’t reach internet time servers, the devices stay in step with this CMS clock.

What to do	Why
If you turned on the CMS VM’s firewall, open UDP 123 coming in from the internal network	If it is blocked, devices can’t get the time
Don’t open it to the outside on the router	Public time servers get abused for attacks
Don’t install another time-server program (chrony · ntpd) on the CMS VM	They fight over port 123 and the CMS time server can’t start — the pre-install check stops and tells you in that case. Ubuntu’s default time keeping (timesyncd) is fine

The CMS’s own clock is kept by the VM (Hyper-V integration services time sync · Ubuntu’s default time keeping).

Checking that everything is done

If you’ve come this far, all of the following should work. If even one doesn’t, go back to that step.

Check	How	If not
The admin console opens	In a browser, http://<this PC's address>:8080	Step 6
You can log in as administrator	With the password you wrote down in step 5	Step 5
Backups are turned on	systemctl list-timers | grep treetweb	Step 7
Backup files are actually created	ls -la backup/	Step 7
The site address opens without warnings	https://<site>.treetsites.com:8443	Step 9
The admin entrance opens	https://admin-<site>.treetsites.com	9-d

Be sure to check the two backup rows

“Turned on” and “files are created” are different things. Run it once by hand and see that a file is actually created. The certificates that exist only at this site cannot be recreated.

What to do next

Installation covers setting up the CMS. For content to appear on screens, three more things are needed.

1. Install the player (TreeTview) on the kiosk PCs, and on each PC enter this CMS’s address with F8. 🔴 Installing alone does not connect it — the player comes with the development default (127.0.0.1). Once you enter the address, it registers itself and appears in the device list (it also gets its device certificate automatically). → Site deployment ⚠️ After entering it, look with your own eyes at the [사이트설정] 확인 line in the player log. Appearing in the list is not enough — if you skip this check, you won’t be able to find the cause later.
2. Upload and schedule content — decide what plays on which screen and when.
3. Install UltraVNC on each device — remote control is already on on the CMS side, and only the part that sends out the screen needs to be on the device (8-b).

How to use it is in the admin console documentation — device registration, scheduling, and remote control are described in screen order.

Going into operation — set the update channel to stable

A CMS that has just been installed is treated as not yet in operation (development stage). At this stage it also receives development versions (app and CMS versions still in testing). Once devices are connected, scheduling is done and all setup is finished, move it into operation — from then on it receives only versions that finished testing and were officially released (stable).

1. Open .env in the installation folder: sudo nano .env
2. Delete the # at the start of the #TREET_UPDATE_CHANNEL=stable line. If that line is missing, add TREET_UPDATE_CHANNEL=stable at the end.
3. Save and bring the CMS up again: sudo docker compose up -d

TREET_UPDATE_CHANNEL	This CMS is
(empty — default)	Not yet in operation. It also receives development versions
stable	In operation. It receives only promoted (stable) versions — the app update list, CMS update packages and manually uploaded installers alike

After going into operation, manual installer uploads are promoted versions only too

When you upload an app installer directly in the admin console, a CMS in operation accepts only versions with a promotion certificate (see uploading an app installer in the admin console documentation). The same goes for CMS update packages that upgrade the CMS itself — a CMS in operation applies only promoted CMS versions. If a test version has to go to the site, ask your contact.

Unknown values are refused

A value other than stable (for example beta) makes the CMS update refuse. Check for typos.

Updating the CMS to a new version

It’s the same as the first installation — get the new package and run install.sh again inside it. There is no separate update procedure.

# Inside the VM, in the folder where the new package was extracted
sudo bash install.sh

Site values are kept

If .env (DB password, site address) and the certificates already exist, they are not overwritten. The administrator password is kept in the database, not in .env, so it stays as it is. So running it again doesn’t require re-entering the site settings. Content and the DB are kept as well.

Still, check the backups first

Before updating, see with your own eyes that backup files actually exist — ls -la backup/. The certificates that exist only at this site cannot be recreated.

Check what changed with the package’s 읽어주세요.md (Read me) and the version number. After updating, go through the checks in “Checking that everything is done” above again — especially whether the admin console opens.

Devices are separate

Updating the CMS does not change the players on the kiosks on the spot. New device-side versions are installed outside each device’s operating hours, according to the CMS’s update mode (automatic · manual); to install right away, press [지금 설치] (Install now) → Site deployment

When you need to reinstall (recovery)

To set up the same site again, you must have a backup file first.

bash docker/restore-site.sh <backup-file>            # put settings and certificates back in place
sudo bash install.sh                              # install
bash docker/restore-site.sh <backup-file> --db-only  # load the data

After restoring, restart the viewer on each device once

Deployment numbers count up automatically, so after a restore they start again from the number at backup time. A deployment you publish after the restore can therefore be lower than the number the device is already showing (one published after the backup), and the device receives it but only applies a higher number, so the screen does not change. In this case “just save the schedule again” may not work.

• Press [Restart] in the command menu on the device page; the viewer then shows the schedule it has received.
• Restart only after the device has fully received the new deployment — after 업데이트 완료: contents appears in the device log (Devices → Log). If you restart before it has finished, it falls back to the previous schedule and postpones the new one.
• Right after a restore, do not save a schedule while it is empty — an emptied schedule is still published, and the device keeps the layout (split · background) but fills the empty slots with the background (the content looks gone).

Don’t reinstall under the same name without a backup

The installation finishes as if it succeeded, but new certificates are created, so the existing players can’t connect to the CMS. If the installer detects this case, it stops and tells you what’s needed.

When restoring is refused — there are two cases

Before loading anything, restore first checks whether the backup is usable. If it stopped, it’s one of two things.

• “끊어진 링크입니다” (This is a broken link) — the file latest.tar.gz pointed to was deleted after its retention period (or backups weren’t running in the meantime). Specify another treetweb_site_*.tar.gz in the same folder directly.
• “덤프가 끝까지 나오지 않았습니다” (The dump did not complete) — that backup was cut off partway while being created. Use a backup from another date.

🔴 Don’t force it in. You’d end up with a half-loaded database, and that state looks like “restore complete”. By then the original has already been overwritten, which makes it much harder to undo.

If something goes wrong

docker compose logs --tail 50 web laravel   # recent logs (add laravel-scheduler media-worker for scheduled jobs)
docker compose ps                       # what's running
sudo bash docker/preflight.sh           # re-run the readiness checks