Skip to main content

Getting started

This page runs Census with the configuration file shipped in the repository, which reads the public Infrahub sandbox and the NetBox demo, and sends the first queries.

Requirements​

  • Docker with Docker Compose.
  • A clone of the Census repository.
  • Optional: a token for the NetBox demo. Without one, the NetBox contribution fails to refresh and the inventory reports itself as incomplete, which also shows how Census reports a source that cannot be read.

Start Census and Memgraph​

From the root of the repository:

export NETBOX_TOKEN=...      # optional
docker compose up -d --build

Docker Compose starts two containers:

  • memgraph, the cache, on port 7687.
  • census, built from the repository's Dockerfile, on port 8080. It reads ./config.toml, mounted at /etc/census/config.toml.

Docker Compose passes INFRAHUB_API_KEY, INFRAHUB_WEBHOOK_SECRET and NETBOX_TOKEN from the shell or from a .env file to the Census container.

When Census starts, it checks the configuration file, connects to Memgraph and starts one full refresh of each contribution. The first refresh of the Infrahub sandbox takes a few seconds.

Send the first queries​

List the inventories, then read the devices inventory's definition and location hierarchy:

curl -s localhost:8080/v1/inventories
curl -s localhost:8080/v1/inventories/devices
curl -s localhost:8080/v1/inventories/devices/locations

List the devices whose status is active or planned, sorted by role in descending order:

curl -s 'localhost:8080/v1/inventories/devices/entities?filter.status=active&filter.status=planned&sort=-role&limit=50'

List the devices of the site us/atl1, and fail with 409 if the inventory is incomplete:

curl -s 'localhost:8080/v1/inventories/devices/entities?location=us/atl1&require_complete=true'

Read one device with full detail, which shows the source object and field of every value:

curl -s 'localhost:8080/v1/inventories/devices/entities/atl1-core1?detail=full'

List the records Census could not use, and the values it could not map:

curl -s 'localhost:8080/v1/inventories/devices/diagnostics?kind=unmapped&kind=duplicate_hfid'

List the source connections and the inventories that use them:

curl -s localhost:8080/v1/connections

Open the web UI and the API reference​

  • http://localhost:8080/ui/: the read-only web UI. It shows the inventories, entities, contributions and diagnostics that the API returns.
  • http://localhost:8080/docs: the interactive API reference, generated from the server's handlers.
  • http://localhost:8080/openapi.json: the OpenAPI document.

Run Census from source​

To build Census from source, run Memgraph in Docker and Census with Cargo:

docker compose up -d memgraph
cargo run -p fic-server -- --config config.toml

A binary built from source includes the web UI only when the UI was built first. The deployment page gives the commands.

Next steps​

  • To define your own inventories, start with Administration.
  • To write a program that reads inventories, start with the Query API.