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.
Prerequisites
Section titled “Prerequisites”| 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.
Make targets
Section titled “Make targets”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.
Version numbers
Section titled “Version numbers”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.
First build
Section titled “First build”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/:
git clone https://github.com/TheOriUHD/aperture.gitcd aperturemake buildAfter 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 development loop
Section titled “The development loop”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.
-
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:8555log:level: infostreams: errorTerminal window go2rtc -config ./go2rtc.yaml -
In the repository, start the daemon:
Terminal window make runWith no environment set,
config.Loaduses these defaults: it listens on:8080, keeps its database and secrets in./dataand footage in./recordings(both ignored by git), and expects go2rtc athttp://localhost:1984andrtsp://localhost:8554. MQTT is off. Override any of them with the variables on Configuration. -
Open
http://localhost:8080. It serves the web bundle from your lastmake 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. -
For frontend work, start the Vite dev server in a second terminal:
Terminal window make web-devIt serves the app on
http://localhost:5173with hot reload and proxies/api, WebSockets included, tohttp://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:
(cd web && npm run build)APERTURE_WEB_DIR=web/dist make runThen 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:
go run ./cmd/nvrctl --url http://localhost:8080 --token "$(cat data/cli.token)" statusWithout --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.
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.
The API test harness
Section titled “The API test harness”API tests run against the real router. newTestServer in
internal/api/harness_test.go:
- opens a fresh SQLite store in
t.TempDir()withstore.Open, so every migration runs; - builds an
auth.Managerwith fixed test secrets and a CLI token, and wires the same API-token resolver ascmd/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 |
Example bundles
Section titled “Example bundles”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:
make examplestools/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.
cd webnpm testThe 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.
Conventions
Section titled “Conventions”These rules are enforced by code or kept consistently throughout it. A change that breaks one will usually fail a test or the boot.
API routes
Section titled “API routes”- Register every route in
Server.routesthrough theapiRouter(g.Get,g.Post,g.Put,g.Delete) with an access spec. A route added any other way stopsnvrdat boot (How it works). - Pick the narrowest spec. A route about one camera with an
{id}parameter uses a…Camspec so the camera check is central. Anything that could take over an account or the system (users, tokens, credentials, backup, restore, restart) isadminSessionOnlyorauthedSessionOnly, never a scope. Every other non-public route names the scope a token needs; a new scope goes intoknownScopesininternal/api/scopes.go. /api/v1grows 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
writeJSONandwriteErrororwriteErrorCodeininternal/api/respond.go, so errors carry a stablecodeand lists are[], nevernull. - Publish a change-feed message after a mutation the web app shows (
emitConfig,emitStorage,emitAutomationininternal/api/feed_handlers.go), so open tabs update without polling.
Database
Section titled “Database”- One migration per change, in
internal/store/migrationsasNNNN_name.sqlwith 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.
Secrets
Section titled “Secrets”- 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 withsecret.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).
Languages and binaries
Section titled “Languages and binaries”- Go for the daemon and every tool (
tools/mkbundlesis 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.shunpacks Deno’s zip withunzip,bsdtaror BusyBox’sunzip, whichever is present, and stops with an error before downloading anything if none is. On systems withapt-get,deploy/install.shinstallscurlandunzipbefore 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
apdetectprocess. - Native and third-party code runs in its own process, never inside
nvrd. Theapdetectworker and extension backends are started withPdeathsigso they die withnvrd, and with a raisedoom_score_adjso the kernel ends them before the recorder (internal/ai/worker.go,internal/ext/supervisor.go).
Web strings
Section titled “Web strings”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.
Contributing and license
Section titled “Contributing and license”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.