Get Started

Television Simulator (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

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

Download and unzip the web files

Get the latest release from GitHub.
Click the latest tvs-{version}.zip file to download it.
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)

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

Point IIS at your folder

Press Start, type IIS and open Internet Information Services (IIS) Manager.
In the left tree, right‑click Sites → Add Website…
Fill in:
- Site name: TVS99
- Physical path: 📁 C:\TVS99 (the folder with 📄 index.html)
- Port: 8080 (to avoid conflicts—any free port is fine)
Click OK. If it didn’t auto‑start, click Start on the right.
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.

Troubleshooting

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).
Firewall prompt. If Windows asks, click Allow so your browser can connect to the local server.
Invalid configuration message displayed. Make sure that YAML files are allowed to be served by IIS. By default, IIS blocks unknown file types. You can add a MIME type for .yml files with the value text/yaml in IIS Manager under your site → MIME Types.

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

I’d recommend trying Linux for a dedicated server, but if you want to use Docker on Windows here’s how to get started.

Install Docker Desktop for Windows (from docker.com).
Open Docker Desktop → Settings (gear) → General → turn on Start Docker Desktop when you sign in to your computer.

Note: Docker Desktop starts after you log in unfortunately. Containers marked restart: unless-stopped will auto-start once Docker is running.

Make a folder structure

Create a 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\

If this is the first time you’re using TVS you may want to start with the example config file. This means not mapping the volume for config.tvs.yml shown below and just using the default config that comes with the image to familiarize yourself with the app. You can always add your own later.
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

Open PowerShell.

Run:

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

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:
Terminal window
```
docker compose down
```
Update to the latest image later:
Terminal window
```
docker compose pull
docker compose up -d
```