Skip to content

Installation and Deployment

ant1fr edited this page Nov 18, 2026 · 1 revision

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.

Docker Compose

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 -d

Open 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.

Synology NAS (Container Manager)

  1. In File Station create a folder such as /volume1/docker/smart-frame.
  2. Find the owner you want: over SSH, id <your-user> gives the UID and GID (often 1026/100), then sudo chown <uid>:<gid> /volume1/docker/smart-frame.
  3. Container Manager → Project → Create: choose the folder with the docker-compose.yml above and add a .env next to it with:
    DATA_DIR=/volume1/docker/smart-frame
    PUID=1026
    PGID=100
    HOST_PORT=8080
    
  4. 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.

Portainer

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.

Reverse proxy and ROOT_PATH

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.

Host or bridge networking?

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.

Environment variables

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.


Home · Report an issue · Roadmap

Clone this wiki locally