Skip to content

Development

This page is for working on Aperture itself: what to install, which make target does what, how to run the daemon and the web app side by side, how the tests are put together, and the rules the code base keeps. For installing a release on a server, see Install; for the architecture, read How it works first.

Tool Version Needed for
Linux any recent distribution Building at all. The Go code uses Linux-only process attributes (SysProcAttr.Pdeathsig in internal/ai/worker.go and internal/ext/supervisor.go), so it does not compile on macOS or Windows. Use a Linux VM or container
Go 1.25 or newer (go 1.25.0 in go.mod) The daemon, nvrctl, apdetect, apdiscovery, the tests
Node.js and npm Node.js 18 or newer (Vite 5 needs it) The web app
ffmpeg and ffprobe on PATH Recording, motion and audio detection, exports, scrub previews, some tests
go2rtc the version deploy/vendor.sh pins (GO2RTC_VERSION, 1.9.14) Anything with video
Deno the version deploy/vendor.sh pins (DENO_VERSION) Only for backend extensions
An MQTT broker any Only for the Home Assistant integration

No C toolchain is needed. SQLite is the pure-Go modernc.org/sqlite, and ONNX Runtime is loaded at run time through purego (internal/ai/ort), so every binary builds with CGO_ENABLED=0.

All targets are in the Makefile.

Target What it runs
make build build-web, then build-go
make build-web npm ci && npm run build in web/, then replaces everything in internal/webassets/dist except the tracked .gitkeep with web/dist, for embedding
make build-go go build of nvrd and nvrctl into bin/, with the version -ldflags
make build-native build-web, then check-web-fresh, then all four binaries (nvrd, nvrctl, apdiscovery, apdetect) with CGO_ENABLED=0. This is what the installer needs
make check-web-fresh Fails if internal/webassets/dist/index.html is missing (only the placeholder is there) or older than any file in web/src or web/index.html
make run go run ./cmd/nvrd
make web-dev npm install && npm run dev in web/: the Vite dev server
make dev Prints a reminder to run make run and make web-dev in two terminals
make test go test ./..., then npm test in web/; a failure in either fails the target. The web step needs web/node_modules (cd web && npm ci)
make lint go vet ./...
make fmt go fmt ./...
make tidy go mod tidy
make examples go run ./tools/mkbundles: rebuilds examples/dist/<name>.zip from each examples/<name>/
make install-cli Builds nvrctl into ~/.local/bin
make vendor sudo deploy/vendor.sh: downloads and checksums the pinned go2rtc and Deno into /usr/lib/aperture/bin
make install build-native, then sudo deploy/install.sh
make uninstall sudo deploy/uninstall.sh
make clean Removes bin/ and dist/, and empties internal/webassets/dist except .gitkeep

make up, make down, make logs and make prune drive the Docker Compose files in deploy/. They are from an earlier setup and are not the supported way to run Aperture.

The Makefile derives the version from the nearest tag matching v[0-9]* (git describe --tags), so a build four commits after v1.2.0 is 1.2.0-4-g1a2b3c4. A build from a tree with uncommitted changes gets +local appended. Both the version and the short commit hash are linked into internal/version. nvrd logs the version on its first line, and GET /api/v1/system/version returns it without authentication.

The embedded web bundle is a build artifact and is not in git. A fresh clone holds only an empty placeholder, internal/webassets/dist/.gitkeep, which the //go:embed all:dist directive in internal/webassets/embed.go picks up, so go build, go run and go test work before the frontend has ever been built. A daemon built that way answers every web-app page with “web UI not built: run make build-web (or make build-native), or set APERTURE_WEB_DIR to a built web/dist”; the API works. make build builds the bundle first, then the binaries into bin/:

Terminal window
git clone https://github.com/TheOriUHD/aperture.git
cd aperture
make build

After that, go build keeps embedding whatever is in internal/webassets/dist, however old it is. Build release binaries through make build or make build-native, which always rebuild the bundle (build-native also runs check-web-fresh, so it can never embed the placeholder or a stale bundle), or run make check-web-fresh before a plain go build. Do not delete .gitkeep by hand: make build-web and make clean keep it.

The daemon serves the API and the web app. For frontend work, the Vite dev server can serve the app with hot reload and forward API calls to the daemon.

  1. Start go2rtc with a configuration like the one the installer writes, in a scratch folder:

    api:
    listen: "127.0.0.1:1984"
    rtsp:
    listen: ":8554"
    webrtc:
    listen: ":8555"
    candidates:
    - stun:8555
    log:
    level: info
    streams: error
    Terminal window
    go2rtc -config ./go2rtc.yaml
  2. In the repository, start the daemon:

    Terminal window
    make run

    With no environment set, config.Load uses these defaults: it listens on :8080, keeps its database and secrets in ./data and footage in ./recordings (both ignored by git), and expects go2rtc at http://localhost:1984 and rtsp://localhost:8554. MQTT is off. Override any of them with the variables on Configuration.

  3. Open http://localhost:8080. It serves the web bundle from your last make build-web. On an empty database the app opens the first-run setup, where you create the administrator account. A camera you add is registered in your go2rtc right away.

  4. For frontend work, start the Vite dev server in a second terminal:

    Terminal window
    make web-dev

    It serves the app on http://localhost:5173 with hot reload and proxies /api, WebSockets included, to http://localhost:8080 (web/vite.config.ts). Sign-in and saving both work through it.

csrfGuard in internal/api/ext_broker.go refuses every cookie-authenticated POST, PUT, PATCH or DELETE whose Origin host differs from Host. The proxy rewrites Host to localhost:8080 (changeOrigin: true), so it also rewrites an Origin that names the dev server itself to http://localhost:8080 (rewriteOwnOrigin). Any other Origin, such as another site or null, passes through unchanged and is still refused. If your daemon listens elsewhere, change API_TARGET at the top of web/vite.config.ts.

To try a production build of the app without the dev server, let the daemon serve it from disk:

Terminal window
(cd web && npm run build)
APERTURE_WEB_DIR=web/dist make run

Then use http://localhost:8080. With APERTURE_WEB_DIR set, nvrd reads the files on each request, so rebuilding the web app needs no daemon restart.

To use nvrctl against the development daemon, pass the URL and the token explicitly:

Terminal window
go run ./cmd/nvrctl --url http://localhost:8080 --token "$(cat data/cli.token)" status

Without --token, nvrctl looks for cli.token in $APERTURE_DATA_DIR, then /var/lib/aperture/data, then ./data, so on a machine that also has an installed Aperture it can pick up the installed one’s token.

Terminal window
go test ./...

Most tests need nothing installed. Some skip themselves when a tool is missing: the recorder’s rotation, shutdown and quality tests need ffmpeg; the extension end-to-end test in internal/api/ext_backend_e2e_test.go needs deno on PATH and root (it drops to an extension uid); and TestWorkerIntegration in internal/ai/worker_test.go runs only when APERTURE_TEST_APDETECT, APERTURE_TEST_ORT_LIB and APERTURE_TEST_MODEL point at a built worker, an ONNX Runtime library and a model.

API tests run against the real router. newTestServer in internal/api/harness_test.go:

  • opens a fresh SQLite store in t.TempDir() with store.Open, so every migration runs;
  • builds an auth.Manager with fixed test secrets and a CLI token, and wires the same API-token resolver as cmd/nvrd/main.go;
  • sets the rate limits so high that they never trigger (the rate-limit test shrinks one bucket on purpose);
  • mounts Server.routes(), so the access specs, the boot-time guard and every middleware run exactly as in production.

Requests go through httptest. The cred helpers apply a credential class to a request: cookieCred with a session from sessionCookieFor, bearerCred for the CLI token or an apt_… token, or nothing for anonymous. reqAs sends the request. Subsystems such as the recorder, go2rtc and the exporter stay nil, so a test may only call routes whose handlers do not need them.

newTestServerNoRouter leaves the router unbuilt so a test can install the extraAPIRoutes seam first; that is how TestFailClosed_UndeclaredRouteRefusesBoot proves that an undeclared route stops the boot. TestMain in internal/api/main_test.go calls ext.RunSpawnTrampoline, because the extension supervisor re-executes the current binary, which in a test is the test binary.

Tests worth knowing before you touch the API:

Test File Pins
TestAuthMatrix auth_matrix_test.go Representative routes for anonymous, viewer, admin and CLI callers: 401, 403 and per-camera denial
TestFailClosed_UndeclaredRouteRefusesBoot, TestRealRouterBootsClean fail_closed_test.go The boot-time guard, and that the real route table passes it
TestOpenAPIGeneratedFromRegistry openapi_test.go The OpenAPI document comes from the route registry
TestV1AliasAndVersionHeaders versioning_test.go /api and /api/v1 behave the same; the alias carries the deprecation headers
TestCameraLinksNeverLeaveWithTheirLogin and the rest of the file camera_credentials_test.go Camera passwords and stream keys never leave the server

TestExampleBundlesAreFresh in internal/ext/example_test.go compares the contents of each examples/dist/<name>.zip with its examples/<name>/ folder and fails if they differ. After you edit an example, run:

Terminal window
make examples

tools/mkbundles writes the zip deterministically (files stored uncompressed, sorted, with a fixed timestamp), so an unchanged example produces identical bytes and the committed zip does not churn.

Terminal window
cd web
npm test

The web tests use Vitest (web/vitest.config.ts). They match src/**/*.test.{ts,tsx} and run in the Node environment; a component test opts into a DOM with a // @vitest-environment jsdom comment at the top of the file. npm run build also type-checks the whole app with tsc in strict mode, with unused locals and parameters as errors.

These rules are enforced by code or kept consistently throughout it. A change that breaks one will usually fail a test or the boot.

  • Register every route in Server.routes through the apiRouter (g.Get, g.Post, g.Put, g.Delete) with an access spec. A route added any other way stops nvrd at boot (How it works).
  • Pick the narrowest spec. A route about one camera with an {id} parameter uses a …Cam spec so the camera check is central. Anything that could take over an account or the system (users, tokens, credentials, backup, restore, restart) is adminSessionOnly or authedSessionOnly, never a scope. Every other non-public route names the scope a token needs; a new scope goes into knownScopes in internal/api/scopes.go.
  • /api/v1 grows only by adding. Do not rename or remove a field or route, and do not change a field’s meaning; add a new one. The /api/v1/ext/ machinery is the exception (frozenExempt).
  • Answer through writeJSON and writeError or writeErrorCode in internal/api/respond.go, so errors carry a stable code and lists are [], never null.
  • Publish a change-feed message after a mutation the web app shows (emitConfig, emitStorage, emitAutomation in internal/api/feed_handlers.go), so open tabs update without polling.
  • One migration per change, in internal/store/migrations as NNNN_name.sql with the next free number. Never edit or renumber one that has shipped.
  • Migrations are forward-only and additive. Backfills run at start on the single database connection, so they must be one fast pass. The rules are on Data model.
  • Credentials are write-only. Camera passwords, stream keys and storage credentials are never returned by the API; a link leaves the server with its secret replaced by a placeholder and is filled in again only for the same host (internal/urlcred). Storage and ONVIF credentials are encrypted at rest with secret.Cipher.
  • Bearer secrets are stored only as hashes (sessions, api_tokens, shares). Secrets compared directly, such as the CLI token and the live-view key, are compared in constant time (subtle.ConstantTimeCompare).
  • Go for the daemon and every tool (tools/mkbundles is Go), TypeScript for the web app, TypeScript on Deno for extension backends. There is no Python in the repository and none should be added. deploy/vendor.sh unpacks Deno’s zip with unzip, bsdtar or BusyBox’s unzip, whichever is present, and stops with an error before downloading anything if none is. On systems with apt-get, deploy/install.sh installs curl and unzip before it vendors.
  • Keep the binaries static: no cgo dependency. Native libraries, like ONNX Runtime, are downloaded at run time and loaded with purego, and only inside the separate apdetect process.
  • Native and third-party code runs in its own process, never inside nvrd. The apdetect worker and extension backends are started with Pdeathsig so they die with nvrd, and with a raised oom_score_adj so the kernel ends them before the recorder (internal/ai/worker.go, internal/ext/supervisor.go).

A string that should be translatable is written as t("key", "English text") with react-i18next. English is the fallback for any key a catalog does not have, so a new string works before it is translated. The German catalog is in web/src/lib/i18n.ts; most screens are not translated yet.

Aperture is source-available under the PolyForm Noncommercial License 1.0.0: you may use, change and pass it on for any noncommercial purpose, keeping the Required Notice line. See License for what that means in practice. Third-party components keep their own licenses, listed in THIRD-PARTY-NOTICES.md.

The repository has no contribution guide. Report bugs on the issue tracker, and report security problems privately as described on Security model. CHANGELOG.md lists what changed in each release.

Related: How it works, Data model, API, Extensions.