obscreen/docs/setup-run-headless.md

Obscreen - Headless run on any server

👈 back to readme

🔵 You just want a slideshow manager, and you'll deal with screen and browser yourself ? You're in the right place.

---

📡 Run the studio instance

Using docker run

# (Optional) Install docker if needed
curl -sSL get.docker.com | sh && sudo usermod -aG docker $(whoami) && logout 
# ....then login again

---

# Prepare application data file tree
cd ~ && mkdir -p obscreen/data/db obscreen/data/uploads && cd obscreen

# Run the Docker container
docker run --restart=always --name obscreen --pull=always \
  -e DEBUG=false \
  -e PORT=5000 \
  -e SECRET_KEY=ANY_SECRET_KEY_HERE \
  -p 5000:5000 \
  -v ./data/db:/app/data/db \
  -v ./data/uploads:/app/data/uploads \
  jierka/obscreen:latest

---

Using docker compose

# Prepare application data file tree
cd ~ && mkdir -p obscreen/data/db obscreen/data/uploads && cd obscreen

# Download docker-compose.yml
curl https://raw.githubusercontent.com/jr-k/obscreen/master/docker-compose.yml > docker-compose.yml

# Run
docker compose up --detach --pull=always

---

System-wide

Install

• Install studio by executing following script

Linux

curl -fsSL https://raw.githubusercontent.com/jr-k/obscreen/master/system/install-studio.sh -o /tmp/install-studio.sh && chmod +x /tmp/install-studio.sh && sudo /bin/bash /tmp/install-studio.sh $USER $HOME
sudo reboot

Windows & MacOS

git clone https://github.com/jr-k/obscreen.git
cd obscreen
python3 -m venv venv
source ./venv/bin/activate
pip install .
cp .env.dist .env

Configure

• Server configuration is editable in .env file.
• Application configuration will be available at http://localhost:5000/settings page after run.
• Check logs with journalctl -u obscreen-studio -f

---

👌 Usage

• Page which plays slideshow is reachable at http://localhost:5000
• Slideshow manager is reachable at http://localhost:5000/manage

📺 Run the player instance

Autorun for a RaspberryPi

How to install

• Install player autorun by executing following script (will install chromium, x11, pulseaudio and obscreen-player systemd service)

curl -fsSL https://raw.githubusercontent.com/jr-k/obscreen/master/system/install-player-rpi.sh -o /tmp/install-player-rpi.sh && chmod +x /tmp/install-player-rpi.sh && sudo /bin/bash /tmp/install-player-rpi.sh $USER $HOME
sudo reboot

How to restart

1. Just use systemctl sudo systemctl restart obscreen-player.service

---

Manually on any device capable of running chromium

When you run the browser yourself, don't forget to use these flags for chromium browser:

# chromium or chromium-browser or even chrome
# replace http://localhost:5000 with your obscreen-studio instance url
chromium \
  --disk-cache-size=2147483648 \
  --disable-features=Translate \
  --ignore-certificate-errors \
  --disable-web-security \
  --disable-restore-session-state \
  --autoplay-policy=no-user-gesture-required \
  --start-maximized \
  --allow-running-insecure-content \
  --remember-cert-error-decisions \
  --noerrdialogs \
  --kiosk \
  --incognito \
  --window-position=0,0 \
  --window-size=1920,1080 \
  --display=:0 \
  http://localhost:5000

---

📎 Additional

How to upgrade studio instance

with docker run

• Just add --pull=always to your docker run ... command, you'll get the latest version automatically.

or with docker compose

• Just add --pull=always to your docker compose up ... command, you'll get the latest version automatically.

or system-wide

• Using Git Updater plugin
• Or by executing following script

cd ~/obscreen
git pull
source ./venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart obscreen-studio.service

---