Installation guide
Set up in minutes, not days
Install on Android TV directly, or run the admin backend on a Raspberry Pi, Ubuntu server, or Docker container.
Android TV Installation
- 01
Download the app
Search for HospitalityTV on the Google Play Store, or download the APK directly from our releases page.
- 02
Enable unknown sources (APK only)
Go to Settings → Security and enable "Install from unknown sources" or "Unknown apps" for your file manager.
- 03
Install and launch
Open the Play Store app (or the downloaded APK) and install. Launch HospitalityTV from your app drawer.
- 04
Connect to admin server
Enter your admin backend URL (local IP or public domain) to sync your property content and settings.
- 05
Enter your license key (Cloud)
If you subscribed to HospitalityTV Cloud, enter your license key during setup or in Settings to unlock all features and custom branding. Self-hosted setups can skip this step.
Raspberry Pi Backend Setup
Run the HospitalityTV admin backend locally on a Raspberry Pi. Ideal for single-property setups without a cloud server. All Android TVs on the same network will connect automatically.
- 01
Flash Raspberry Pi OS
Download Raspberry Pi OS Lite (64-bit) and flash it to an SD card. Enable SSH and set your WiFi credentials.
- 02
Install Docker & Docker Compose
SSH into your Pi and run:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
- 03
Clone the repository
git clone https://github.com/your-org/hospitality-tv-admin.git
cd hospitality-tv-admin
- 04
Configure environment
Copy .env.example to .env and fill in your settings: APP_URL, database credentials, and license secret.
- 05
Start the stack
docker compose up -d
The admin panel will be available at http://<pi-ip>:3001
- 06
Pair your Android TV
On the TV app, enter http://<pi-ip>:4000 as the backend URL. Screens appear in your admin panel automatically.
Ubuntu Server Installation
Deploy the admin backend on a VPS or dedicated Ubuntu server. Supports remote access over the internet via HTTPS.
- 01
Install Ubuntu 22.04 LTS
Provision a VPS (2 vCPU, 2 GB RAM minimum).
sudo apt update && sudo apt upgrade -y
- 02
Install Node.js & Docker
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs docker.io docker-compose
sudo systemctl enable --now docker
- 03
Clone and configure
git clone https://github.com/your-org/hospitality-tv-admin.git
cd hospitality-tv-admin
cp .env.example .env
- 04
Run database migrations
npm run db:migrate
npm run db:seed
- 05
Start the backend
docker compose up -d
- 06
Configure SSL & domain
Point your domain DNS to the server IP. Use Caddy or Nginx + Certbot for HTTPS. Update APP_URL in .env to your domain.
- 07
Connect TVs
Enter your public backend URL in the Android TV app. Screens will register automatically.
Docker Compose Setup
The quickest way to run the full stack anywhere Docker is available. Works on Linux, macOS, and Windows.
# docker-compose.yml
version: "3.9"
services:
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_DB: hospitalitytv
POSTGRES_USER: htv
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db_data:/var/lib/postgresql/data
api:
image: ghcr.io/your-org/hospitality-tv-api:latest
restart: unless-stopped
depends_on: [db]
ports:
- "4000:4000"
environment:
DATABASE_URL: postgresql://htv:${DB_PASSWORD}@db:5432/hospitalitytv
APP_URL: ${APP_URL}
LICENSE_SECRET: ${LICENSE_SECRET}
admin:
image: ghcr.io/your-org/hospitality-tv-admin:latest
restart: unless-stopped
depends_on: [api]
ports:
- "3001:3001"
environment:
API_URL: http://api:4000
volumes:
db_data:
- 01
Copy and configure
Copy the compose file above. Create a .env file with DB_PASSWORD, APP_URL, and LICENSE_SECRET.
- 02
Start the stack
docker compose pull && docker compose up -d
- 03
Access admin panel
Open http://localhost:3001 in your browser to access the admin dashboard.
- 04
Update procedure
docker compose pull && docker compose up -d
(Zero-downtime rolling update)
