server

module

v0.9.5 Latest Latest Go to latest Published: Mar 31, 2026 License: GPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ubuntu/ubuntu-insights

Links

Open Source Insights

README ¶

Ubuntu Insights Server Services

The Ubuntu Insights Services are the components for aggregating and processing reports. They do not record any personally identifying information such as IPs.

There are two server services, a web exposed web service which handles incoming HTTP requests as well as an ingest service which does simple validations before inserting reports into a database.

Neither of these services are meant for local use.

Usage

Web Service

  ubuntu-insights-web-service <allowlist> [flags]
  ubuntu-insights-web-service [command]

Options

Available Commands:
  help        Help about any command
  version     Returns the running version of ubuntu-insights-web-service and exits

Flags:
      --config string              use a specific configuration file
  -h, --help                       help for ubuntu-insights-web-service
      --json-logs                  enable JSON formatted logs
      --listen-host string         host to listen on
      --listen-port int            port to listen on (default 8080)
      --max-header-bytes int       maximum header bytes for HTTP server (default 8192)
      --max-upload-bytes int       maximum upload bytes for HTTP server (default 131072)
      --metrics-host string        host for the metrics endpoint
      --metrics-port int           port for the metrics endpoint (default 2112)
      --read-timeout duration      read timeout for HTTP server (default 5s)
      --reports-dir string         directory to store reports in (default "~/.cache/ubuntu-insights-services~/reports")
      --request-timeout duration   request timeout for HTTP server (default 3s)
  -v, --verbose count              issue INFO (-v), DEBUG (-vv)
      --write-timeout duration     write timeout for HTTP server (default 10s)

Ingest Service

  ubuntu-insights-ingest-service <allowlist> [flags]
  ubuntu-insights-ingest-service [command]

Options

Available Commands:
  help        Help about any command
  migrate     Run migration scripts
  version     Returns the running version of ubuntu-insights-ingest-service and exits

Flags:
      --config string            use a specific configuration file
      --db-host string           database host
  -n, --db-name string           database name
  -P, --db-password string       database password
  -p, --db-port int              database port (default 5432)
  -s, --db-sslmode string        database SSL mode
  -u, --db-user string           database user
  -h, --help                     help for ubuntu-insights-ingest-service
      --json-logs                enable JSON formatted logs
      --metrics-host string      host for the metrics endpoint
      --metrics-port int         port for the metrics endpoint (default 2113)
      --read-timeout duration    read timeout for the metrics HTTP server (default 5s)
      --reports-dir string       base directory to read reports from (default "~/.cache/ubuntu-insights-services/reports")
  -v, --verbose count            issue INFO (-v), DEBUG (-vv)
      --write-timeout duration   write timeout for the metrics HTTP server (default 10s)

The Allowlist

The allowlist configuration file, which can be passed to either the web service or the ingest service or shared with both, is a required JSON file which defines an allowlist for the sources being processed. This file is watched by the service in a manner such that changes to it will be applied without requiring the service to restart.

See this file for an example of how it should be formatted.

An application must be included in this list for the web service to accept HTTP requests from a given application endpoint, and for the ingest service to process reports for that application.

Applications or items meant to be treated as legacy reports from Ubuntu Report should be added with the format: ubuntu-report/<distribution>/desktop/<version>.

Reserved Names

The following applications and items are reserved and cannot be used within the allowlist

ubuntu_report
schema_migrations

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
ingest-service command Package main is the entry point for the ingest-service application.	Package main is the entry point for the ingest-service application.
ingest-service/daemon Package daemon provides the ingest service daemon for Ubuntu Insights.	Package daemon provides the ingest service daemon for Ubuntu Insights.
web-service command Package main is the entry point for the web service application.	Package main is the entry point for the web service application.
web-service/daemon Package daemon provides the web service daemon for Ubuntu Insights.	Package daemon provides the web service daemon for Ubuntu Insights.
internal
common/config Package config provides a configuration manager that loads and watches a JSON configuration file.	Package config provides a configuration manager that loads and watches a JSON configuration file.
common/constants Package constants is responsible for defining the constants used in the application.	Package constants is responsible for defining the constants used in the application.
common/metrics Package metrics provides a Prometheus metrics HTTP server.	Package metrics provides a Prometheus metrics HTTP server.
common/testutils Package testutils package provides ingest-service specific test utilities.	Package testutils package provides ingest-service specific test utilities.
ingest Package ingest is responsible for running the ingest-service in the background.	Package ingest is responsible for running the ingest-service in the background.
ingest/database Package database provides the database connection and upload functionality for the ingest service.	Package database provides the database connection and upload functionality for the ingest service.
ingest/models Package models provides the data structures for payloads used in the ingest service.	Package models provides the data structures for payloads used in the ingest service.
ingest/processor Package processor provides the functionality to process JSON files.	Package processor provides the functionality to process JSON files.
ingest/workers Package workers provides worker management for the ingest service.	Package workers provides worker management for the ingest service.
webservice Package webservice provides an HTTP server that handles incoming requests for uploading data and retrieving version information.	Package webservice provides an HTTP server that handles incoming requests for uploading data and retrieving version information.
webservice/handlers Package handlers provides HTTP handlers for the server.	Package handlers provides HTTP handlers for the server.
webservice/metrics Package metrics provides middleware for collecting metrics in the web service, to be interpreted by Prometheus.	Package metrics provides middleware for collecting metrics in the web service, to be interpreted by Prometheus.