Repository navigation
Installation and Deployment
Smart Frame Engine is one Docker image (ghcr.io/ant1fr/smart-frame-engine, linux/amd64 and
linux/arm64, so a Raspberry Pi works too) plus one folder for its data.
mkdir smart-frame && cd smart-frame
curl -fsSLO https://raw.githubusercontent.com/ant1fr/Smart-Frame-Engine/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/ant1fr/Smart-Frame-Engine/main/.env.example -o .env
docker compose up -dOpen http://<host>:8080/. Immich, TMDB and the frame can all be configured in the web UI, so
the .env file is optional.
Three deployment settings (in .env, or as stack variables in Portainer) shape the setup:
| Variable | Default | Meaning |
|---|---|---|
HOST_PORT |
8080 |
Port published on the host (the container always listens on 8080). |
DATA_DIR |
smart-frame-data |
Where /data lives. A name creates a Docker volume; an absolute path (/volume1/docker/smart-frame) bind-mounts that host folder. |
PUID / PGID
|
1000 |
User and group that own a bind-mounted folder (id -u, id -g). |
Inside the container the data folder is always /data: docker-compose.yml pins DATA_DIR=/data
for the app, so the host-side DATA_DIR in your .env never leaks into it.
What is stored in /data: config.json (your settings), secrets.json (generated API key and
session secret, mode 0600), history.json, scheduler_state.json, the rendered cache/ and the
deep-sleep upload queue/. Back this folder up and you can restore everything.
Upgrading: docker compose pull && docker compose up -d. Pin a version with
image: ghcr.io/ant1fr/smart-frame-engine:1.0 (tags: 1.0.0, 1.0, 1 and latest;
pre-releases such as 1.1.0-rc.1 never move latest).
Building from source (development): docker compose -f docker-compose.build.yml up -d --build.
- In File Station create a folder such as
/volume1/docker/smart-frame. - Find the owner you want: over SSH,
id <your-user>gives the UID and GID (often1026/100), thensudo chown <uid>:<gid> /volume1/docker/smart-frame. -
Container Manager → Project → Create: choose the folder with the
docker-compose.ymlabove and add a.envnext to it with:DATA_DIR=/volume1/docker/smart-frame PUID=1026 PGID=100 HOST_PORT=8080 - Start the project. The first image pull takes a minute.
Give the frame a DHCP reservation on your router: containers rarely resolve fraimic.local
(mDNS), so use the frame's IP address in Settings → Frame.
Web editor / upload: paste docker-compose.yml and define HOST_PORT, DATA_DIR, PUID,
PGID (and any application variable from .env.example) as stack environment variables.
Portainer writes them to stack.env, which the compose file reads.
Repository mode (stack built from this repo): use docker-compose.yml as the compose path.
(docker-compose.portainer.yml still works for existing stacks; it uses DATA_PATH instead of
DATA_DIR.) Only define the variables you want to set: a variable defined with an empty value
overrides the application default with an empty string.
Create the data folder first and give it to PUID:PGID:
mkdir -p /srv/smart-frame/data && chown 1000:1000 /srv/smart-frame/data.
The engine runs Uvicorn with --proxy-headers, so X-Forwarded-Proto / X-Forwarded-For are
honored (set FORWARDED_ALLOW_IPS to your proxy's address instead of * if you can). The web UI
uses only relative URLs, so it works on a domain or under a sub-path.
On a domain: point the proxy at http://<host>:8080, nothing else to set.
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
client_max_body_size 25m; # image uploads (MAX_UPLOAD_MB)
}Under a sub-path (https://home.example.com/fraimic/): set ROOT_PATH=/fraimic. Both styles
of proxy work: one that strips the prefix (proxy_pass http://127.0.0.1:8080/;) and one that
keeps it (proxy_pass http://127.0.0.1:8080;). The session cookie is scoped to the sub-path.
home.example.com {
handle_path /fraimic/* {
reverse_proxy 127.0.0.1:8080
}
}Nginx Proxy Manager: create a proxy host to <host>:8080 (WebSockets are not needed); for a
sub-path add a custom location /fraimic with the same target.
Traefik: a router matching the path prefix /fraimic and, if the prefix is stripped, a
stripprefix middleware. Always serve it over HTTPS when ADMIN_PASSWORD is set.
The default bridge network is what you want unless you need device discovery:
| bridge (default) | network_mode: host |
|
|---|---|---|
| Reach the frame by IP | yes | yes |
Resolve fraimic.local (mDNS) |
usually no | yes |
Advertise _smartframe._tcp.local. (Zeroconf) |
no (bridge drops multicast) | yes |
| Port |
HOST_PORT mapping |
the engine listens on PORT directly |
For host networking, replace ports: with network_mode: host in the compose file and set
PORT (default 8080) in .env if the port is taken. HOST_PORT no longer applies.
Everything except the deployment variables above can also be set in the web UI, where values
saved in /data/config.json win over the environment (see
Configuration Reference).
| Variable | Default | Meaning |
|---|---|---|
ADMIN_PASSWORD |
(empty) | Enables the web UI login (user admin) and locks every route except /api/health, the login and the public images. |
APP_API_KEY |
(empty) | API key for Home Assistant and scripts. Generated into /data/secrets.json when ADMIN_PASSWORD is set and this is empty. |
SESSION_TTL_HOURS |
168 |
Lifetime of a UI login. |
SESSION_SECRET |
(generated) | Key that signs login cookies. |
PUBLIC_IMAGE_ENDPOINTS |
true |
Keep /api/current.jpg, /api/current.bin readable without a key (Home Assistant Generic Camera). |
ZEROCONF_ENABLED |
true |
Advertise _smartframe._tcp.local. over mDNS (needs host networking in Docker). |
ROOT_PATH |
(empty) | Sub-path behind a reverse proxy, e.g. /fraimic. |
CORS_ORIGINS |
* |
Allowed CORS origins. |
FORWARDED_ALLOW_IPS |
* |
Proxies trusted for forwarded headers. |
MAX_UPLOAD_MB |
20 |
Size limit for uploaded and downloaded images. |
BLOCK_PRIVATE_URLS / URL_ALLOWLIST
|
false / empty |
SSRF protection for outgoing image fetches; the allowlist takes hosts or CIDRs. |
LOG_LEVEL |
INFO |
Log verbosity. |
TZ |
UTC |
Timezone for quiet hours, {season} and other date logic (e.g. Europe/Paris). |
IMMICH_URL, IMMICH_API_KEY
|
Seed an Immich account named default. |
|
TMDB_API_KEY, TMDB_LANGUAGE
|
TMDB key and poster language (fr-FR, en-US...). |
|
FRAIMIC_HOST, FRAIMIC_POWER_MODE, FRAIMIC_PANEL, ORIENTATION
|
Frame address (use its IP), continuous or deepsleep, 133 or 315, portrait or landscape. |
|
SMART_MIX_ENABLED, SCHEDULER_ENABLED, REFRESH_INTERVAL_HOURS, QUIET_HOURS_START/END
|
Scheduler defaults, also editable in the UI. |
Frame settings that can change later (power mode, orientation) are better set in the UI than in the environment: environment values are only defaults until you save a setting.