feat: Docker deployment for Synology NAS (Container Station)

[jcodling]

What

Add a self-contained Docker deployment path for running the daily report pipeline on a Synology NAS via Container Station — no longer dependent on macOS and launchd.

Why

The NAS is already always-on and has the power to run the pipeline reliably at 3 AM without waking a Mac. This moves the scheduler from a personal Mac (which goes to sleep, loses power, etc.) to a dedicated always-on device.

Changes

New files

• Dockerfile — Alpine-based Bun image (~80 MB), runs the pipeline as a one-shot container (bun run generate), uses non-root appuser
• docker-compose.yml — Compose spec for local dev; deploy script handles NAS provisioning directly
• .dockerignore — Excludes node_modules, .env, logs/, reports/ from build context
• scripts/deploy-nas.sh — One-command deployment: builds image locally, SCPs the tar to NAS, loads it, starts the container
• DOCKER-DEPLOY.md — Full guide: CLI deploy, GUI fallback, scheduling, troubleshooting
• .editorconfig — Enforces spaces, LF, trailing whitespace removal across editors
• scripts/pre-commit.hook + scripts/lint-fix.sh — Pre-commit hook blocks trailing whitespace + bash syntax errors

Modified files

• README.md — Added NAS deployment section, updated stack/scheduler to list both options
• scripts/run.sh — Detects Docker env; skips caffeinate/pmset when inside container

How it works

1. deploy-nas.sh builds the Docker image locally on your Mac
2. Saves + SCPs the tar to NAS, loads it, starts container with persistent volumes
3. One-time setup in Container Station: scheduled task (daily 03:00, task: Start)
4. Container runs ~3-5 seconds then exits. Container Station restarts it daily.

NAS Deployment

brew install --cask docker && brew install sshpass rsync
./scripts/deploy-nas.sh
# Then in Container Station: Scheduled Task -> daily 03:00 -> Start

Linting

Pre-commit hook blocks trailing whitespace and bash syntax errors. Run ./scripts/lint-fix.sh to fix whitespace, then commit.

[jcodling]

Code Review

Overview

Adds a self-contained Docker deployment path for running the daily report pipeline on a Synology NAS, so it no longer depends on macOS + launchd. Includes Dockerfile, compose spec, a one-shot deploy script, documentation, and developer tooling (editorconfig, pre-commit hook, lint-fix script).

---

Bugs

Critical — NAS_PASS default value syntax (deploy-nas.sh:597)

NAS_PASS="${NAS_PASS:""}"   # BUG: should be "${NAS_PASS:-}"

${var:""} is not a valid default-value expansion — it's parsed as a substring with an empty offset, which effectively just expands $NAS_PASS. With set -u active, if NAS_PASS is unset the script dies on this line before it even reaches the helpful error check at line 611. Fix: "${NAS_PASS:-}".

---

Medium — scp for image transfer runs without sshpass (deploy-nas.sh:633)

scp "$IMAGE_FILE" "${NAS_USER}@${NAS_IP}:/tmp/"   # no sshpass!

Every other SSH command uses sshpass -p "$NAS_PASS", but this one doesn't — it'll prompt interactively and break the automation. Fix: sshpass -p "$NAS_PASS" scp -o StrictHostKeyChecking=no ....

---

Medium — env-file check runs locally, not on NAS (deploy-nas.sh:679)

$(if [ -f /volume1${DOCKER_DIR}/.env ]; then echo '--env-file ...'; fi) \

This command substitution inside the heredoc is evaluated on the Mac before the SSH session, so it checks /volume1/docker/dailyreport/.env on the Mac (which doesn't exist). The --env-file flag is never passed, so the container always starts without environment variables. Fix: either always include --env-file (the file is guaranteed to be there by step 5), or escape the $() so it evaluates on the NAS.

---

Medium — .env copied to wrong NAS path (deploy-nas.sh:661-662)

sshpass -p "$NAS_PASS" scp ... "$PROJECT_DIR/.env" "${NAS_USER}@${NAS_IP}:${DOCKER_DIR}/.env"

DOCKER_DIR is /docker/dailyreport, so this copies to /docker/dailyreport/.env. But the NAS stores data under /volume1/, so the correct destination is /volume1/docker/dailyreport/.env. All other NAS paths in the script correctly use /volume1${DOCKER_DIR}.

---

Lower-priority issues

grep -P not available on macOS default grep (lint-fix.sh:794)

if grep -Pn '\s+$' "$file" >/dev/null 2>&1; then

macOS ships BSD grep, which doesn't support -P. This silently always returns false (no match), so trailing whitespace is never detected. Fix: grep -En '[[:space:]]+$'.

---

--all flag positional coupling (lint-fix.sh:762-768)

--all is hardcoded as $2, so ./lint-fix.sh --all is silently ignored — you'd have to run ./lint-fix.sh "" --all. Use getopts or loop over "$@" to parse flags properly.

---

docker exec on an exited container (DOCKER-DEPLOY.md:252-258)

docker exec dailyreport_daily ls /app/reports/
docker exec dailyreport_daily cat /app/reports/2025-05-08.md

Since the container runs for ~5 seconds and exits, docker exec will fail ("container is not running"). Replace with direct NAS filesystem access (ls /volume1/docker/dailyreport/reports/) or docker run --rm with the image.

---

Named volume vs bind mount inconsistency (docker-compose.yml:22 vs deploy-nas.sh:680)

The compose file uses a named Docker volume (dailyreport-data:/app), while the deploy script uses a bind mount (-v /volume1/docker/dailyreport:/app). Named volumes aren't accessible from Synology File Station. The compose file comment says it's for local dev, which is fine — but add an explicit note that it should not be used on the NAS, since the bind mount behavior differs materially.

---

bun install not pinned (Dockerfile:21)

RUN bun install --production

Consider adding --frozen-lockfile to guarantee the image reproduces exactly from bun.lock, avoiding silent dependency drift between deploys.

---

What works well

• Non-root appuser in Dockerfile is the right call
• Layer ordering (deps first, then source copy) enables good cache reuse
• scripts/run.sh container detection via /.dockerenv is idiomatic and clean
• Pre-commit hook architecture (warn on tabs, block on trailing whitespace + bash syntax errors) is solid
• .dockerignore is thorough and correct
• PR description and documentation are clear and detailed

---

Summary

Three medium bugs need fixing before merge: the sshpass missing on the scp call, the env-file check running on the wrong host, and the .env being copied to the wrong NAS path. The NAS_PASS syntax bug is critical and will cause an immediate failure for anyone with the variable unset. The rest are polish items.

[jcodling]

Review fixes applied

Critical

• NAS_PASS default syntax (deploy-nas.sh) — replaced invalid ${NAS_PASS:""} with ${NAS_PASS:-} so set -u no longer crashes before the error handler runs.

Medium

• Missing sshpass on scp (deploy-nas.sh) — added sshpass -p "$NAS_PASS" to the image transfer command so it doesn't hang on an interactive password prompt.
• Env-file check runs locally (deploy-nas.sh) — removed the $(if [ -f ... ]) conditional (which ran on the Mac, not the NAS) and replaced it with a direct --env-file flag using the consistent DOCKER_DIR path.
• .env copied to wrong path (deploy-nas.sh) — fixed scp destination from ${DOCKER_DIR}/.env (which resolves to /docker/dailyreport/.env) to /volume1${DOCKER_DIR}/.env, matching all other NAS paths in the script.

Low

• grep -P on macOS (lint-fix.sh) — replaced grep -Pn '\s+$' with grep -En '[[:space:]]+$' since BSD grep doesn't support -P (Perl regex).
• --all flag broken (lint-fix.sh) — replaced positional $1/$2 flag parsing with a case loop so flags can be passed in any order and combined. Also fixed a pre-existing bug: --no-exclude-standard (invalid git option) → --exclude-standard (the correct flag), which is why --all never actually worked.
• docker exec on exited container (DOCKER-DEPLOY.md) — replaced docker exec commands in "View generated reports" and "Cannot reach SFTP host" sections with direct SSH+NAS filesystem commands, since the container exits after ~5s.
• Named volume vs bind mount inconsistency (docker-compose.yml) — added a comment clarifying the named volume is for local dev only; NAS deployments use a bind mount so the storage dir is accessible from File Station.
• bun install not pinned (Dockerfile) — added --frozen-lockfile to guarantee reproducible images from bun.lock.

All fixes verified with bash -n syntax checks and pre-commit hooks pass clean.

[jcodling]

Claude Code — Sonnet 4.6 reviewing the PR code changes

---

Code Review — fix commits

Critical — 1 remaining bug

deploy-nas.sh:165 — docker exec still present in next-steps output

The DOCKER-DEPLOY.md fixes replaced all docker exec calls with direct NAS filesystem commands because the container exits after the pipeline run. That same fix was missed in the script's own printed output:

echo "  docker exec ${CONTAINER_NAME} ls /app/reports/"   # line 165

docker exec fails on exited containers. The docker logs command on line 166 is fine (it works on exited containers). Line 165 should be:

echo "  ssh ${NAS_USER}@${NAS_IP} ls /volume1${DOCKER_DIR}/reports/"

---

Medium — --all flag doesn't implement its documented behavior

lint-fix.sh:33 + header comment (line 7)

The header says --all "also scans untracked text files", but git ls-files --exclude-standard without -o/--others only shows tracked files — identical to the default mode. The fix correctly replaced the invalid --no-exclude-standard with --exclude-standard, but -o is still missing.

The flag change fixed the crash but didn't restore the intended behavior. Current behavior of both modes is identical. Should be:

files=$(git ls-files -z --others --exclude-standard 2>/dev/null | tr '\0' '\n')

Or if the intent is "tracked + untracked":

files=$(
  git ls-files -z 2>/dev/null
  git ls-files -z --others --exclude-standard 2>/dev/null
) | tr '\0' '\n'

---

Low

pre-commit.hook:43 — git grep -P has same portability issue as the grep -P already fixed in lint-fix.sh

if git grep --cached -P '\t' -- "$file" >/dev/null 2>&1; then

-P (PCRE) requires git to be compiled with libpcre. On a stock macOS git this silently fails and the tab check never fires. Replace with a literal tab:

if git grep --cached -F $'\t' -- "$file" >/dev/null 2>&1; then

lint-fix.sh:23-24 — unknown option doesn't exit

*)
  echo "Unknown option: $arg" >&2
;;

A typo like lint-fix.sh --dryrun prints the warning but continues running. Should add exit 1 after the echo.

---

Verified clean

• deploy-nas.sh:25 — ${NAS_PASS:-} ✅
• deploy-nas.sh:62 — sshpass -p "$NAS_PASS" scp ✅
• deploy-nas.sh:91 — .env copies to /volume1${DOCKER_DIR}/.env ✅
• deploy-nas.sh:108 — --env-file /volume1${DOCKER_DIR}/.env ✅
• Dockerfile — --frozen-lockfile --production ✅
• docker-compose.yml — named volume comment accurate ✅
• DOCKER-DEPLOY.md — docker exec → direct NAS/SSH commands ✅
• lint-fix.sh — --exclude-standard flag correct, case loop correct ✅

---

Summary: 3 actionable issues. The docker exec in deploy-nas.sh next-steps output is the only true regression — same bug fixed in DOCKER-DEPLOY.md but missed in the script. The --all behavior bug is pre-existing but the fix commit implied it was resolved. The git grep -P portability issue is the same class of problem already addressed in lint-fix.sh.

[jcodling]

I'm Pi Agent running qwen3.6. The following is the result of a full automated review of the changes in this branch:

1. Medium Issues

• Missing .env validation (deploy-nas.sh): The script copies .env to the NAS after running rsync. If a user doesn't have one, the script fails with a generic “No such file or directory” error. It's best to add an early check: [ ! -f “$PROJECT_DIR/.env” ] && error “No .env file found.”
• sed portability (lint-fix.sh): The script uses sed -i '' (macOS/BSD syntax). On a Linux or WSL environment, this will crash. Ensure this is noted in the README or the script is ported to use a temp-file approach.

2. Nice-to-haves

• Missing .env.example: The script relies on variables like FTP_HOST and FTP_USER, but no example configuration file is provided. Adding config/.env.example with dummy values will prevent “blank config” errors for others.
• Volume mismatch documentation: Ensure the docker-compose.yml named volume is explicitly flagged in the docs—users shouldn't accidentally try to use it for NAS deployments where bind mounts are required for File Station access.

3. Security Observations

• sshpass visibility: The script passes the NAS password in the command line. This is standard for simple NAS scripts but worth noting in the docs, as the password will be visible in ps aux for a brief moment on the NAS.

Positive Findings

• Robustness in scripts: The cleanup logic in deploy-nas.sh (removing the image tar and checking for duplicate scheduled tasks) is excellent.
• Security: The Dockerfile correctly uses a non-root appuser and bun install --frozen-lockfile.

Verdict: The branch is ready to merge once the missing .env check and example are added!

[jcodling]

I'm Pi Agent running qwen3.6. Here is a summary of the most recent changes applied to this branch:

• deploy-nas.sh: Replaced docker exec with ssh in the “next steps” output so users aren't given commands that fail on exited containers.
• lint-fix.sh: Added --others to the --all flag so it actually scans untracked files as documented.
• lint-fix.sh: Added exit 1 on unknown options so typos fail fast rather than proceeding silently.
• pre-commit.hook: Replaced git grep -P with git grep -F to ensure the tab-detection check works on macOS stock git.

All changes have passed the pre-commit hooks and bash syntax validation.

[jcodling]

Claude Code — Sonnet 4.6 reviewing the PR code changes

---

Code Review — followup round

All previous bugs confirmed fixed

• ${NAS_PASS:-} ✅
• sshpass -p on scp ✅
• --env-file always passed, correct path ✅
• .env scp destination uses /volume1${DOCKER_DIR} ✅
• docker exec in deploy-nas.sh next-steps output → ssh ... ls /volume1... ✅
• git grep -P → git grep -F $'\t' ✅
• grep -P → grep -E '[[:space:]]+$' ✅
• --all flag parses correctly via case loop ✅
• Unknown option now exit 1 ✅
• --frozen-lockfile in Dockerfile ✅
• Named volume comment in docker-compose.yml ✅

---

New issues

Medium — deploy-nas.sh:42-43 — warn for required dependencies instead of error

command -v sshpass  || warn  "sshpass not found — run: brew install sshpass"
command -v rsync    || warn  "rsync not found — run: brew install rsync"

sshpass is called on 8 lines throughout the script; rsync on line 79. Using warn lets the script continue past pre-flight into actual work, where it fails with command not found: sshpass or a cryptic rsync error. Both should be error.

---

Medium — lint-fix.sh:33 — --all mode scans only untracked files, not tracked+untracked

if [ "$SCAN_ALL" = "1" ]; then
    files=$(git ls-files -z --others --exclude-standard 2>/dev/null | tr '\0' '\n')
else
    files=$(git ls-files -z 2>/dev/null | tr '\0' '\n')

Header says --all also scans untracked text files — the "also" implies tracked + untracked combined. Current implementation replaces the tracked-file list with an untracked-only list. Default mode catches tracked, --all catches untracked, but neither mode catches both. The fix added --others (resolving the crash), but the additive behavior described in the header still isn't implemented. Should be:

if [ "$SCAN_ALL" = "1" ]; then
    files=$(
        git ls-files -z 2>/dev/null
        git ls-files -z --others --exclude-standard 2>/dev/null
    ) | tr '\0' '\n'
else

---

Low — deploy-nas.sh — no pre-flight check for local .env

The scp at line 90-91 fails with a generic No such file or directory if .env doesn't exist locally. A check next to the other pre-flights (line 40) would give a clear error early:

[ -f "$PROJECT_DIR/.env" ] || error "No .env file found at $PROJECT_DIR/.env — create it before deploying"

---

Low — DOCKER-DEPLOY.md:128-134 — "Manual full rebuild" mixes NAS and Mac commands in one block

ssh admin@192.168.1.100
docker stop dailyreport_daily
docker rm dailyreport_daily
docker rmi dailyreport:latest
./scripts/deploy-nas.sh

The docker stop/rm/rmi commands need to run on the NAS, but ./scripts/deploy-nas.sh runs on the Mac. Presented in one block, a user who copy-pastes will run docker stop/rm/rmi locally against Docker Desktop, not the NAS. Should be split:

# On NAS:
ssh admin@192.168.1.100 "docker stop dailyreport_daily; docker rm dailyreport_daily; docker rmi dailyreport:latest"

# On Mac:
./scripts/deploy-nas.sh

The same pattern appears in DOCKER-DEPLOY.md:97-100 and 184-187 (ssh followed by docker logs/images in a single block) but those are lower stakes — read-only, no Mac/NAS ambiguity.

---

Pre-existing — lint-fix.sh:68 — sed -i '' is BSD-only

Not introduced by this PR. sed -i '' (empty backup extension) is macOS/BSD syntax; GNU sed (Linux, WSL) requires sed -i with no argument. Worth a note in the script header or a temp-file approach if portability matters.

---

Summary

Four actionable items. The warn-for-required-tools issue is the most likely to cause confusion in practice — it silently proceeds past the pre-flight check and then fails mid-deploy. The --all behavior gap means the documented mode still doesn't do what the header says. The other two are documentation fixes.