Skip to main content

Controller Setup

FrameOS controller

The FrameOS controller is the application you use to deploy FrameOS onto individual devices.

Once deployed, the frames don't need the controller to function. It's still useful to keep it up for log aggregation.

FrameOS walkthrough

Running via docker

The easiest way to run the FrameOS controller is via Docker.

# generate a stable secret key
SECRET_KEY=$(openssl rand -base64 32)

# run the latest release
docker run -d --name frameos --restart always \
-p 8989:8989 \
-v ./db:/app/db \

If you want to keep the container up to date, use watchtower:

# update daily to the latest release
docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower \
--interval 86400

# one time update
docker run \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower \
--run-once \

Keep in mind that FrameOS is in early development, and despite best efforts, there are no guarantees of stability between releases.

Developing via docker

If you want to run the development build locally via docker:

# build your own
git clone
docker build frameos -t frameos
docker run -d -p 8989:8989 -v ./db:/app/db --name frameos frameos

Then load, preferably with a local IP that your frames can connect to.

Setup the raspberry

You're now ready to add frames to FrameOS.

Follow the Raspberry Pi setup guide to get your frames setup.

Once you see the frames over SSH, press "add a smart frame", and tell the controller the new frame's IP or hostname.

Install apps and scenes

Next, read about the apps you can install, and about writing your own.