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. Here are three ways to get started:

• Via your favorite web server
• Through the Docker image
• New Using the Television Simulator Launcher

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

Heads up!

Try the new Television Simulator Launcher for an easier way to install, update, and manage TVS on Windows!

If you want to use a traditional web server on Windows instead, here’s how to get started.

Download and unzip the web files

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.)

---

Use the built‑in Windows web server (IIS)

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.

---

What is a “web server” exactly?

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

• IIS is the program we’re using. You told it: “serve 📁 C:\TVS99 on port 8080”.

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
• 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

Get the official TVS Docker image and run it in a container.

🐧 Linux

This is the recommended way to run TVS as a dedicated server. You get easy updates and can run multiple instances on different ports.

Install Docker Engine

I won’t cover this in detail because it varies by distro. Follow the official instructions.

Docker Compose (recommended)

The Docker image exposes port 3000 as a static web server with all of Television Simulator installed. You need to provide your own configuration file however, which can be done with a volume. If you’d like to serve custom content from TVS server, create a content volume and use /content/your-media.jpg, etc. as the path in config.tvs.yml.

Here’s an example docker-compose.yml you can use:

services:
  tvs-server:
    image: 'zshall/television-simulator:latest'
    restart: unless-stopped
    ports:
      - '80:3000'
    volumes:
      - /var/tvs/config.tvs.yml:/home/static/config.tvs.yml
      - /var/tvs/content:/home/static/content

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.