Skip to main content

Deploy Census

Census is one server binary, fic-server, that needs a Memgraph instance and a configuration file. It serves the query API, the webhook receiver, the API reference and the web UI on one port.

Run the Docker image​

The repository's Dockerfile builds an image that includes the web UI. The configuration file is not part of the image: mount it at /etc/census/config.toml.

docker build -t census .
docker run -p 8080:8080 \
  -v "$PWD/config.toml:/etc/census/config.toml:ro" \
  -e MEMGRAPH_BOLT_URL=bolt://memgraph:7687 \
  -e INFRAHUB_API_KEY -e NETBOX_TOKEN \
  census

The image runs fic-server --config /etc/census/config.toml as the nobody user and exposes port 8080.

The repository's docker-compose.yml starts Memgraph and Census together, and passes INFRAHUB_API_KEY, INFRAHUB_WEBHOOK_SECRET, NETBOX_TOKEN and RUST_LOG from the shell or a .env file.

Run Memgraph​

Census uses Memgraph as its cache, over the Bolt protocol. The Docker Compose file runs the memgraph/memgraph-mage image with write-ahead logging and a snapshot every 300 seconds, and stores its data in a volume.

The cache holds only data that Census can fetch again from the sources. If the cache is emptied, Census refills it with the next full refresh of each contribution.

Build Census from source​

Census builds with Cargo. The Rust version is pinned in rust-toolchain.toml.

The binary includes the web UI only if the UI was built before the binary. A binary built without it answers /ui/ with the command to run.

corepack enable                 # provides the pnpm version pinned in web/package.json
pnpm --dir web install
pnpm --dir web build            # writes web/dist/, which fic-server includes
cargo build --release -p fic-server
./target/release/fic-server --config config.toml

Without --config, Census reads config.toml in the current directory.

Set the server, Memgraph and branch view settings​

Three sections of the configuration file configure the server itself. The configuration reference lists every setting.

[server]
bind = "0.0.0.0:8080"           # address and port of the API, webhooks and web UI

[memgraph]
bolt_url = "${MEMGRAPH_BOLT_URL:-bolt://localhost:7687}"
user = ""
password = ""

[branching]
max_views = 3                   # branch views held at once
idle_ttl = "1h"                 # retire a branch view not read for this long

[branching] is optional. Branch views explains what a branch view is.

Keep secrets out of the file with environment variables​

Census replaces ${NAME} in the configuration file with the value of the environment variable NAME before it reads the file. An unset variable becomes an empty string. ${NAME:-default} uses default when the variable is unset or empty.

Use this for API keys, tokens, webhook secrets and the Memgraph password. No API response contains a credential.

What happens at startup​

  1. Census reads and checks the configuration file. If a rule fails, Census prints one line that names the file, the setting and the rule, and exits with status 2. It does not connect to Memgraph or to any source before the file is valid.
  2. Census connects to Memgraph. If the cache was written by a build with a different storage layout, Census empties it and logs a warning. The cache then refills from the sources.
  3. Census compares each inventory with the definition it stored at the previous start and applies the differences, as described in Apply a configuration change.
  4. Census starts one full refresh of every contribution, then refreshes each contribution on its own interval.
  5. Census starts listening on [server].bind.

Check that Census is running​

GET /healthz returns 200 when Census can reach Memgraph, and 503 when it cannot.

Census writes its logs to standard output. The RUST_LOG environment variable sets the log level, for example RUST_LOG=debug. The default is info.

Protect access to Census​

Census has no authentication or authorization, for the API, the web UI or the webhook receiver. Run it on a trusted network, or put it behind a proxy that controls access. The webhook receiver checks the signature of Infrahub webhooks when the connection has a webhook_secret.