Skip to content

Latest commit

 

History

History
121 lines (95 loc) · 7.66 KB

README.md

File metadata and controls

121 lines (95 loc) · 7.66 KB

Lens for QNAP NAS

A self-contained QPKG, built with QDK, that installs Lens from the App Center like any other app. Lens runs in Container Station, but you don't set up any containers: the package carries the Lens images (API and worker, web app) and SurrealDB, loads them on its first start, and runs the stack. Nothing is built or downloaded on the NAS.

  • NAS: QTS 5 or QuTS hero 5 with Container Station 3, on an Intel/AMD (x86_64) or ARM 64-bit (arm_64) model. 4 GB of RAM or more; transcription is heavy.
  • Space: a few GB on the volume: the package's image files while they're loaded on the first start (they're deleted afterwards), the images in Container Station, and whatever your archive holds.

Build the package

On any machine with Docker and buildx (Linux, macOS, Windows with WSL), from the repository root:

packaging/qnap/build.sh                    # Intel/AMD NAS: packaging/qnap/build/Lens_0.3.0_x86_64.qpkg
packaging/qnap/build.sh --arch arm_64      # ARM NAS:       packaging/qnap/build/Lens_0.3.0_arm_64.qpkg
  • The version comes from fastapi_backend/pyproject.toml (--version overrides it, 10 characters at most).
  • The backend image is the lean target by default: it reads audio, video, PDFs and images. --target full adds LibreOffice and Chromium, to read Office files, text, web pages and emails, and object detection, for a much bigger package. --extras "msg" adds Outlook .msg emails (see docs/deployment.md).
  • Building for the other architecture than your machine's uses QEMU. Docker Desktop has it; on Linux, once: docker run --privileged --rm tonistiigi/binfmt --install arm64 (or amd64). It's slow; building on a machine of the NAS's architecture is quicker.
  • The first run builds a small lens-qdk image with QDK in it, so QDK needn't be installed.
  • The package's images are tagged lens-backend:qnap-<version> and lens-frontend:qnap-<version>, so they never clash with Lens images built some other way. --prebuilt packages images with those tags already in Docker instead of building them (from CI, say).

Releases get the packages automatically: publishing a GitHub release runs .github/workflows/qnap.yml, which builds both and attaches Lens_<tag>_x86_64.qpkg and Lens_<tag>_arm_64.qpkg to it (run it by hand from the Actions tab, with a tag, to rebuild them). The ARM package is built under QEMU, which is slow; set the repository variable QNAP_ARM_RUNNER to an ARM runner (ubuntu-24.04-arm) if the repository has one.

Install on the NAS

  1. Install Container Station from the App Center and open it once, so it finishes its setup.
  2. App Center > the gear icon (top right) > Install Manually > choose the .qpkg for your NAS > Install. QTS warns that the app isn't digitally signed; accept to continue. (Or, over SSH: sh Lens_0.3.0_x86_64.qpkg.)
  3. The first start loads the images into Container Station, which takes a few minutes. When Lens shows as running, click Open in the App Center (or browse to http://<NAS address>:3000).
  4. Create the first admin account with the setup code. It's in the QTS system log (Control Panel > System > System Logs, an entry from Lens saying "create the first admin account with setup code …"), in lens.env in the data folder (LENS_SETUP_CODE), and over SSH: /share/CACHEDEV1_DATA/.qpkg/Lens/lens.sh setup-code (the path depends on the volume you installed to: getcfg Lens Install_Path -f /etc/config/qpkg.conf).
  5. Follow the setup steps: the first namespace, the model provider, and storage, where you can watch /audio (the NAS's Multimedia/Lens folder). Each can be skipped, or answered ahead in lens.env (see Settings).

The containers show up in Container Station as the application lens (surrealdb, backend, worker, frontend), where you can see their logs and resource use.

Where things are

The data folder is /share/Container/lens (the Container shared folder Container Station creates), or Lens-data next to the app's folder if that share doesn't exist. It holds:

Path What
lens.env Settings and secrets, written on the first start. Keep it with the rest: losing ARCHIVE_SECRET_KEY makes stored credentials and model API keys unreadable.
surrealdb/ The database.
archive/ Uploads, media and derived files.

Back up the whole folder (Hybrid Backup Sync works, as it's a shared folder) with Lens stopped. Removing the app keeps the data folder and drops the images; reinstalling picks up where it was. Delete the folder yourself to remove everything.

Your recordings and documents: Lens sees one folder on the NAS, Lens in the Multimedia share (/share/Multimedia/Lens, created on the first start), as /audio, read-only. The setup steps after the first admin account (namespace, model provider, storage) can watch it, or a folder in it, so what you put there is picked up. Set AUDIO_DIR in lens.env to use another folder. Settings changed in the web app are kept in the database.

Settings

Edit lens.env in the data folder, then stop and start Lens in the App Center (or lens.sh restart over SSH).

  • Address and port. FRONTEND_URL is the NAS's LAN address at install time, http://<ip>:3000. Change it, and add the host name to ARCHIVE_ALLOWED_HOSTS, if you reach Lens another way: a fixed host name, a reverse proxy with HTTPS (QTS's own reverse proxy in Control Panel > Network Access, or myQNAPcloud), or if the NAS's address changes. For another port set LENS_PORT and the port in FRONTEND_URL alike. Sharing and IIIF need HTTPS.
  • Mail for password resets: the MAIL_* settings.
  • Unattended setup. The LENS_ADMIN_*, LENS_NAMESPACE, LENS_LLM_* and LENS_SETUP_WIZARD settings answer the first-run setup instead of the web app (see docs/configuration.md); empty ones are left to the web app.
  • Models. Lens talks to OpenAI-compatible servers; set them up in the web app. A model server on the NAS itself (Ollama in Container Station, say) is reachable at the NAS's LAN address, not localhost.
  • To move the data folder: stop Lens, move the folder, then setcfg Lens Data_Path /share/<folder> -f /etc/config/qpkg.conf and start Lens.

Over SSH

lens.sh in the app's folder (getcfg Lens Install_Path -f /etc/config/qpkg.conf):

lens.sh status              # the containers
lens.sh logs [backend]      # follow the logs (all, or one service)
lens.sh setup-code          # the first-admin setup code
lens.sh restart

Upgrading

Build the new version's package and install it over the old one, as in step 2. The new images are loaded on the next start and the old version's are removed; the data folder carries over.

How the package is made

build.sh builds the images for the NAS's platform, saves them into <arch>/images/ next to the qpkg/ sources (with a manifest naming each one), and runs QDK's qbuild on the lot. In the package:

  • qpkg.cfg: requires Container Station 3, opens the web app on port 3000, gives the first start 15 minutes.
  • lens.sh: the service script. On start it waits for Container Station's Docker, writes lens.env with fresh secrets on the first run, loads any image that isn't in Docker yet, and runs docker compose up on docker-compose.yml as the project lens. On removal it stops the stack and removes its own images (tagged qnap-<version>).
  • docker-compose.yml: the same stack as docker-compose.prod.yml, with the bundled images, the data folder as bind mounts and the web app on the NAS's port 3000.
  • archive.yaml: the processing configuration: /audio as the folder the web app may watch, and no namespaces, so the first-run setup asks for one.