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.
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(--versionoverrides it, 10 characters at most). - The backend image is the
leantarget by default: it reads audio, video, PDFs and images.--target fulladds LibreOffice and Chromium, to read Office files, text, web pages and emails, and object detection, for a much bigger package.--extras "msg"adds Outlook.msgemails (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(oramd64). It's slow; building on a machine of the NAS's architecture is quicker. - The first run builds a small
lens-qdkimage with QDK in it, so QDK needn't be installed. - The package's images are tagged
lens-backend:qnap-<version>andlens-frontend:qnap-<version>, so they never clash with Lens images built some other way.--prebuiltpackages 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 Container Station from the App Center and open it once, so it finishes its setup.
- App Center > the gear icon (top right) > Install Manually > choose the
.qpkgfor 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.) - 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). - 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.envin 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). - Follow the setup steps: the first namespace, the model provider, and storage, where you can watch
/audio(the NAS'sMultimedia/Lensfolder). Each can be skipped, or answered ahead inlens.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.
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.
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_URLis the NAS's LAN address at install time,http://<ip>:3000. Change it, and add the host name toARCHIVE_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 setLENS_PORTand the port inFRONTEND_URLalike. Sharing and IIIF need HTTPS. - Mail for password resets: the
MAIL_*settings. - Unattended setup. The
LENS_ADMIN_*,LENS_NAMESPACE,LENS_LLM_*andLENS_SETUP_WIZARDsettings 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.confand start Lens.
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 restartBuild 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.
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, writeslens.envwith fresh secrets on the first run, loads any image that isn't in Docker yet, and runsdocker compose upondocker-compose.ymlas the projectlens. On removal it stops the stack and removes its own images (taggedqnap-<version>).docker-compose.yml: the same stack asdocker-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:/audioas the folder the web app may watch, and no namespaces, so the first-run setup asks for one.