Get Started

Television Simulator ‘99 (TVS) is a configurable web-based media frontend that simulates an analog TV, tuner, receiver and cable headend. It is a web-based application and needs to be hosted on a web server to be used. There are two currently supported ways of running TVS:

• Via your favorite web server
• Through the Docker image

Compatibility

TVS is designed to run on all platforms that support the latest version of the Chromium browser. Browsers like Google Chrome, Brave, Edge, etc. will work. Firefox and Safari may run but support is not guaranteed.

Using a Web Server

You can run Television Simulator on any web server that serves static files. This includes Apache, Nginx, IIS, and more. TVS is distributed as a collection of web files (HTML, CSS, JS, etc.) and can be hosted anywhere you’d like. Some features like Twitch integration require TVS to run in a “secure context”, meaning either via HTTPS or locally on your computer using 🌎 localhost.

Windows

Download and unzip the app

1. Get the latest release from GitHub.

2. Click the latest tvs-{version}.zip file to download it.

3. In File Explorer, right‑click the zip → Extract All…

   • Pick a simple folder, e.g. 📁 C:\TVS99
   • When you open 📁 C:\TVS99, you should see files like 📄 index.html, placeholders/, etc. (If there’s an extra top‑level folder, go into it; the folder that contains 📄 index.html is what we’ll serve.)

---

Option A — Use the built‑in Windows web server (IIS)

Good if you want a “set it and forget it” setup that starts with Windows.

Turn on IIS (one‑time)

1. Press Start, type Windows Features, open Turn Windows features on or off.
2. Check Internet Information Services (leave default sub‑items as they are) → OK.
3. Wait for it to install.

Point IIS at your folder

1. Press Start, type IIS and open Internet Information Services (IIS) Manager.

2. In the left tree, right‑click Sites → Add Website…

3. Fill in:

   • Site name: TVS99
   • Physical path: 📁 C:\TVS99 (the folder with 📄 index.html)
   • Port: 8080 (to avoid conflicts—any free port is fine)

4. Click OK. If it didn’t auto‑start, click Start on the right.

5. Open your browser and go to http://localhost:8080/ You should see Television Simulator ‘99.

To stop later: in IIS Manager, select TVS99 → Stop. To remove it: right‑click the site → Remove.

---

Option B — Use a tiny “temporary” server (Python)

Great for quick testing or one‑off demos. You run a command, use the app, then close the window.

Install Python (one‑time)

1. Open the Microsoft Store.
2. Search Python 3 (from the Python Software Foundation) and click Get / Install.

Start a simple server

1. Open File Explorer and go to your folder (e.g. 📁 C:\TVS99).

2. Click the address bar, type powershell and press Enter (opens PowerShell in that folder).

3. Run:

   py -m http.server 8000

4. Open your browser and go to http://localhost:8000/

Keep that PowerShell window open while you’re using the app. Press Ctrl + C in that window to stop the server.

---

What is a “web server” exactly?

It’s just a program that shows the files in a folder to your browser as a website.

• In the first example, IIS is that program. You told it: “serve 📁 C:\TVS99 on port 8080”.
• In the second example, the Python command temporarily serves the same folder until you close it.

The “root” of your web server is simply the folder you serve (the one with 📄 index.html).

---

Common pitfalls & quick fixes

• I only see a file list, not the app. Make sure you’re serving the folder that directly contains 📄 index.html (not a parent folder).
• Port already in use. Try a different port (e.g. 8081) when adding the site in IIS or in your Python command (py -m http.server 8081).
• Firewall prompt. If Windows asks, click Allow so your browser can connect to the local server.
• Blank page / 404 on refresh. Try the site root (e.g. 🌎 http://localhost:8080/). If you bookmarked a deep link, go to the homepage first.
• Updating the app later. Stop your server, replace the files in 📁 C:\TVS99 with the new zip contents, then start again.

Using Docker

Windows + Docker Desktop

Install Docker Desktop and set it to auto-start when you sign in

1. Install Docker Desktop for Windows (from docker.com).

2. Open Docker Desktop → Settings (gear) → General → turn on Start Docker Desktop when you sign in to your computer. ([Docker Documentation][1])

   Note: Docker Desktop starts after you log in; that’s normal on Windows. Containers marked restart: unless-stopped will auto-start once Docker is running.

---

Make a folder structure

Create a simple folder for your setup, for example:

C:\TVS99\
├─ docker-compose.yml
├─ config\
│   └─ config.tvs.yml        ← your TVS config file
└─ content\                  ← any media you want TVS to serve
    ├─ images\
    └─ videos\

• You can grab or author your 📄 config.tvs.yml as usual.
• Inside your config, you can reference files in the content folder using paths like /content/your-media.jpg.

---

Create docker-compose.yml

In C:\TVS99\docker-compose.yml, paste:

services:
  tvs:
    image: zshall/television-simulator:latest
    container_name: tvs99
    restart: unless-stopped
    ports:
      - "8080:3000"               # visit http://localhost:8080
    volumes:
      - ./config/config.tvs.yml:/home/static/config.tvs.yml:ro
      - ./content:/home/static/content:ro

Why these paths? The image serves the app from a static web server on port 3000, and it expects your config file to be available from the site root. Mapping to /home/static/... makes the file available at http://localhost:8080/config.tvs.yml, and mapping the folder to /home/static/content makes your content reachable at /content/... as referenced in your config.

If you already run something on port 8080, change "8080:3000" to another free port like "8081:3000".

---

Start it up

1. Open PowerShell.

2. Run:

   cd C:\TVS99
   docker compose pull
   docker compose up -d

3. Open your browser to http://localhost:8080/. You should see Television Simulator ‘99.

---

Everyday use

• Start with Windows sign-in: Docker Desktop will launch after you log in (because you enabled that toggle). Your tvs99 container will auto-start thanks to restart: unless-stopped.

• Stop the app:

  docker compose down

• View logs:

  docker compose logs -f

• Update to the latest image later:

  docker compose pull
  docker compose up -d

---

Common pitfalls & quick fixes

• Blank page / 404: Make sure your 📄 path is exactly as mounted (/home/static/config.tvs.yml) and that your browser can fetch http://localhost:8080/config.tvs.yml.
• Media not found: In your config, reference media using paths like /content/... (e.g., /content/images/logo.png). Confirm the file really exists under C:\TVS99\content\.... ([Docker Hub][2])
• Port already in use: Change 8080:3000 to another free port.
• Compose file location: The ./... paths are relative to the folder that contains docker-compose.yml—keep your files under C:\TVS99\ so the mounts work.