pigway-frame-flow/docs/NAS.md

# Synology NAS deployment / 群晖部署

Target: DS923+, DSM 7.3.1, AMD64, Container Manager.
Directory: /volume1/docker/pigway-frame-flow. Port: 18787.

## 1. Package and upload / 打包上传

From the repository:

```sh
python3 scripts/package-nas.py
scp -O dist/pigway-frame-flow-nas.tar.gz nas-example:/tmp/pigway-frame-flow-nas.tar.gz
ssh nas-example
```

The package contains tracked source/config examples/scripts only, never .env,
actual keys, data or .git. It is a deployment artifact, not a Git backup.
Use `git bundle create frame-flow.bundle --all` separately for history backups.

## 2. Prepare project directory / 准备目录

Verify target is empty or explicitly backed up before extracting. Do not extract
onto another existing installation or other services. If the directory exists,
inspect it first; preserve its .env and data.

```sh
mkdir -p /volume1/docker/pigway-frame-flow
# Only for an empty/new target:
tar -xzf /tmp/pigway-frame-flow-nas.tar.gz -C /volume1/docker
cd /volume1/docker/pigway-frame-flow
mkdir -p data/images data/generated data/cache config
sudo chown -R 10333:10333 data config
cp .env.example .env
chmod 600 .env
```

Edit `.env` on the NAS. Set FRAME_FLOW_TOKEN to a strong random token. API key
stays empty. KOKONNA_MOCK=true and KOKONNA_WRITE_ENABLED=false.
Set WEB_BIND to the actual NAS LAN address (recommended) or explicitly 0.0.0.0;
WEB_PORT=18787. The latter binds every NAS interface, so use the LAN IP when
strict LAN-only binding is required. No firewall/router/proxy edits are performed.
Copy deploy/devices.yml.example to config/devices.yml if multiple devices are desired.

## 3. Validate, build, start / 验证构建启动

Synology Docker is /usr/local/bin/docker. The SSH user may require sudo. Do not
change socket ownership, groups, Docker network settings or other containers.

```sh
sudo /usr/local/bin/docker compose config --quiet
sudo /usr/local/bin/docker compose build --pull
sudo /usr/local/bin/docker compose up -d
sudo /usr/local/bin/docker compose ps
sudo /usr/local/bin/docker compose logs --tail 100
sudo /usr/local/bin/docker inspect pigway-frame-flow \
  --format 'id={{.Id}} started={{.State.StartedAt}} health={{.State.Health.Status}} restart={{.HostConfig.RestartPolicy.Name}} ports={{json .NetworkSettings.Ports}} mounts={{json .Mounts}} network={{json .NetworkSettings.Networks}}'
sudo /usr/local/bin/docker image inspect pigway-frame-flow:latest \
  --format 'id={{.Id}} size={{.Size}} architecture={{.Architecture}}'
```

Do not print unfiltered `docker inspect`: its environment can contain keys/tokens.
Likewise do not print `docker compose config` without --quiet on a live installation.
Run the read-only smoke checker from a machine with Python and set FRAME_FLOW_URL
to http://NAS_LAN_IP:18787; FRAME_FLOW_TOKEN stays in private env/file.

Health: GET /health → 200. Readiness: GET /ready → 200 when SQLite, driver config,
auth and Scheduler are ready. Missing credentials in live mode → 503. The cloud
is not probed by readiness. Cloud loss does not cause healthcheck restart loops.

## 4. Verify persistence / 持久化

Create a disabled test schedule in Web UI and locally stage one image (Mock only).
Record the job and asset IDs, then:

```sh
sudo /usr/local/bin/docker compose restart pigway-frame-flow
```

Wait for healthy state, check /health and /ready, and verify the same job/asset
IDs and history remain. Database is data/frameflow.db with WAL/SHM alongside it;
back up while stopped or use SQLite backup API, not a lone live DB file copy.
Restart policy must read unless-stopped. Do not reboot the NAS for acceptance.

## 5. Live read-only verification / 实机只读

After Mock acceptance, fill KOKONNA_API_KEY; set mock=false, keep writes=false.
Recreate only this service to apply env. Query device and images metadata only.
Verify known model/geometry/timezone/name against real data; missing vendor model
fields are not claimed verified. No original downloads are necessary. Stop on
mismatch; never try to fix cloud state automatically. Obtain explicit owner
permission before any upload/switch/delete. See REAL_DEVICE_TEST.md.

## Layout

```
/volume1/docker/pigway-frame-flow/
  docker-compose.yml
  Dockerfile
  .env
  requirements.lock
  pigway_frame_flow/
  vendor/
  scripts/
  config/
  data/
    frameflow.db
    images/
    generated/
    cache/
```

Container runs UID/GID 10333:10333; only data/config need ownership. Avoid recursive
ownership changes outside this project's paths. Standard Compose bridge is private
and isolated by project name. Logs use stdout/stderr with Docker's capped json-file.
No logs directory or Docker socket mount.