Build Pigway Frame Flow with bilingual UI, complete KoKonna driver and safe automation
This commit is contained in:
Pigway
+115
@@ -0,0 +1,115 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user