Configuration¶

aveloxis-cve reads its own JSON file. It looks in this order:

--config <path> (or -c);
the AVELOXIS_CVE_CONFIG environment variable;
./aveloxis-cve.json.

Start from aveloxis-cve.example.json. Keep the real file out of version control and chmod 600 it.

Every key is optional. An omitted key takes the default shown below. An unknown key is an error, so a typo can't silently fall back to a default. Lower bounds are inclusive.

Database¶

Key	Default	Meaning
`database.host`	`localhost`	PostgreSQL host. A path starting with `/` is a Unix-socket directory.
`database.port`	`5432`	Port (1-65535).
`database.user`	(empty)	Login role. Use the read-only `aveloxis_cve` role created by `sql/roles.sql`.
`database.password`	(empty)	Empty means pgx falls back to `PGPASSWORD`, then `~/.pgpass`.
`database.dbname`	(empty)	The Aveloxis database.
`database.sslmode`	`prefer`	libpq `sslmode`.
`database.connect_timeout_seconds`	`10`	Connection timeout (>= 1).
`database.pool_max_conns`	`0`	Pool size. `0` sizes it to at least `workers` + 1, and never below pgx's default. An explicit value must be >= `workers`.

Sessions always run with timezone=UTC and application_name=aveloxis-cve.

Aveloxis integration (read-only)¶

Key	Default	Meaning
`aveloxis_config_path`	(empty)	Optional path to an Aveloxis `aveloxis.json`. Only two fields are read from it. Its `database` block is used only when this file has no `database` key; it must set `user` and `dbname`, because aveloxis-cve does not mirror Aveloxis's own defaults for them. `collection.repo_clone_dir` is read only so that `clone_dir` can be refused if it overlaps Aveloxis's clones. A configured path that does not exist is an error, and so is having no `database` block in either file.

aveloxis-cve never imports Aveloxis code, never writes to Aveloxis's schemas, and never uses Aveloxis's clones: it clones every repository itself from the forge.

Work settings¶

Key	Default	Meaning
`clone_dir`	`<home>/aveloxis-cve-repos`	aveloxis-cve's own clone root (`<dir>/repo_<id>.git`). Must be absolute. Beside each clone is an empty lock file, `<dir>/repo_<id>.git.lock`. Every `sync` or `labor` attempt that gets the repository's database lock creates it, and `clone_dir` with it, even when no clone is made (a repository not ready in Aveloxis, not yet synced, or whose first clone failed). `sync` and `labor` hold an exclusive `flock` on it for a repository's whole run, so a run whose database lock was lost (an idle timeout, a restart) keeps other runs off its clone until it stops; they report the repository busy. Every git a run starts holds the lock too, so it lasts until the last of them exits, even when aveloxis-cve itself was killed. Such an orphaned git is no longer bounded by `git.timeout_seconds`: a hung one (a stalled fetch) keeps the repository busy until it exits. `lsof <dir>/repo_<id>.git.lock` names it (run it as root or as the user that runs aveloxis-cve: lsof silently leaves out other users' processes), and killing it frees the repository. A first clone killed with its process leaves `<dir>/repo_<id>.git.tmp-*`, which the next clone of that repository removes. A lock that cannot be taken at all (for example, `clone_dir` not writable) fails the run, and is recorded as its outcome. It is never removed (delete it only with the clone, with no aveloxis-cve command running). On a network filesystem it is only as strong as that filesystem's `flock`. Do not share one `clone_dir` between installs (configurations with different databases): the lock keeps their runs from overlapping, but their syncs would still fetch their own repositories into the same `repo_<id>.git` in turn. When `aveloxis_config_path` is set, it must not equal or nest with Aveloxis's `repo_clone_dir` in either direction (symlinks, `..` and case-insensitive filesystems resolved).
`workers`	`2`	Repositories processed concurrently (>= 1). Each worker holds one pooled connection, plus one direct connection for its per-repository lock.
`git.timeout_seconds`	`3600`	Bound on any single git invocation (>= 1). This includes git's automatic maintenance of a clone (`git gc --auto`, a repack when packs or loose objects pile up), which each sync runs after its fetch as its own call, in the foreground, so it stays under the clone's lock. A maintenance that fails or reaches this bound is a warning (`repo N: warning: git maintenance of the clone failed: ...`), not a sync failure. The sync then removes what the killed git left (a partial pack, lock files, `packed-refs.new` and `.keep` markers git never takes as stale), every later sync checks for such leftovers before it fetches, and the next sync tries the maintenance again. If the warning names leftovers that could not be removed, the next sync fails on them before it fetches, until they are removed by hand (with no aveloxis-cve command running). A repack longer than this bound therefore never completes: raise it, or run `git gc` on the clone by hand, as the user that runs aveloxis-cve (as root it would leave a root-owned lock file and objects that later runs cannot open), under the clone's lock, so that runs report the repository busy meanwhile instead of removing the manual gc's lock files as leftovers (Linux: `flock -n <dir>/repo_<id>.git.lock git -C <dir>/repo_<id>.git gc`; `-n` gives up at once while a run holds the lock: retry, or drop `-n` to wait. Where there is no `flock(1)`, as on macOS, run it only with no aveloxis-cve command running and none starting until it ends, and `lsof <dir>/repo_<id>.git.lock`, run as root or as the user that runs aveloxis-cve, listing nothing, since a command already running reaches the repository in its turn).
`scc.path`	(empty)	scc binary; empty means `scc` on `PATH`.
`scc.timeout_seconds`	`1800`	Bound on one scc run (>= 1).
`scc.gomaxprocs`	`2`	`GOMAXPROCS` cap for scc (>= 0; `0` means uncapped).
`scc.batch_files`	`2000`	Files measured per scc run (>= 1). Results are cached after every batch. When scc fails on a batch, the batch is split until the failing file is alone. That file is recorded, permanently for this scc version, as not counted only if scc exits with an error status between 1 and 127 on it twice, and scc still measures a known-good control file. Otherwise the run fails, records nothing, and retries next run: on a signal (no exit status, or a wrapper's 128 or above, such as 137 for the OOM killer), on a timeout, and when the control file fails too (scc is broken). Note that scc is a Go program, and a Go panic or runtime out-of-memory exits with status 2, which counts as deterministic. If an environment limit (for example `ulimit -v`) caused that, fix the limit and run `aveloxis-cve labor --retry-uncounted`. That measures again every file the current scc version recorded as not counted (including files scc legitimately does not classify, which come back the same) and recomputes the current window settings of every enabled repository (a repository skipped as busy with a sync, or a run that fails part-way, is finished by the next `labor` or `run`). It holds the labor gate for its whole run: it refuses to start, clearing nothing, while another `labor` or `run` process computes windows (one still under the old limit could record files as not counted again), and labor runs started meanwhile skip every repository as busy.
`labor.window_days`	`60`	Length of each sliding complexity window, in days (>= 1).
`labor.step_months`	`1`	How far each window advances, in months (>= 1).