SearchBrainz will start by waiting for database connection. Once a connection is established, it will wait for connection towards NATS.
Brainz can be scaled out with multiple instances. All instances need access to the same database in
order to operate in the same cluster. Multiple brainz instances will all act as active and the
message handling will be spread among them. Each brainz instance also requires it’s own base-dir
which must be unique between different brainz instances.
# Ubuntu/Debian
sudo apt install varnish-controller-brainz
# RPM-based
sudo dnf install varnish-controller-brainz
Brainz require git as a dependency. This is to support the git functionality for Git deployments.
Deployments using Git will be performed on the brainz instances. Hence, each brainz instance requires access to the configured git-repositories. Any of the running brainz instances may clone the git repository that is deployed. The deployed files from git will be stored as files in the Controller database and deployed to the varnish servers. Hence, only brainz requires access to git, not the agents.
A system administrator user is required in order to use the system. This user is a special user with full system permissions and can only be created using the brainz binary.
See authentication chapter for details about creating an system administrator account.
When the installation is done you need to add your license file. Brainz will by default look for the
license file named varnish-controller.lic in the
/var/lib/varnish-controller7/varnish-controller7-brainz/ directory. If you want to change where
Brainz looks for the license file, edit the systemd service file and add a command line parameter
-license or add the VARNISH_CONTROLLER_LICENSE environment variable.
For details about the license, see the license chapter.
Brainz is started with user, password and database for PostgreSQL.
varnish-controller-brainz -db-server localhost:5432 -db-user varnish-controller -db-pass mypassword -db-name varnish-controller
These can be configured in the systemd service file as environment variables (or as environment variables in containers).
There are some configuration parameters that can be tuned to change how the brainz process operates. These might not be self-explanatory and are described below.
-deployment-throttle <duration>VARNISH_CONTROLLER_DEPLOYMENT_THROTTLE=<duration>This is mainly for handling large numbers of API requests that trigger changes to the deployed VCLGroups. When there is a flood of requests the deployment algorithm will wait this number of seconds before it will decide where things will be deployed. This is to avoid too many re-configurations due to a high number of fast changes. (default 1s)
-deployment-update <duration>VARNISH_CONTROLLER_DEPLOYMENT_UPDATE=<duration>This is the time between each periodic deployment configuration verification. A deployment configuration is basically the algorithm that checks where things should be deployed and verifies that they are. This just makes sure that things are correct in the system. In normal operation this wouldn’t trigger any changes to the system. (default 10s)
-hb-timeout <duration>VARNISH_CONTROLLER_HB_TIMEOUT=<duration>This is the maximum time since last heartbeat from an agent. If this is reached and no heartbeats
have been received during this time, the agent is considered down. Any VCLGroup deployed to this
agent will be moved to any other matching agent if one exists. It is important that this value is in
correlation with the agent heartbeat rate. An agent heartbeat rate set to higher than this value
will mark the agent as down. (default 10s)
-tick-rate <duration>VARNISH_CONTROLLER_TICK_RATE=<duration>The brainz process has a main loop that handles a lot of different tasks, such as removal of old database entries, checking deployments, down agents, updating states of deployments, etc. This is the interval for which these checks will run. (default 2s)
-mod-admin-user <bool>VARNISH_CONTROLLER_MOD_ADMIN_USER=<bool>This will tell brainz to update or create a system administrator. When specifying the two
environment variables VARNISH_CONTROLLER_SYSTEM_ADMIN_USER and
VARNISH_CONTROLLER_SYSTEM_ADMIN_PASS the user given by the environment variables will
automatically be created/updated. If these two environment variables aren’t set, brainz will ask for
interactive input of username and password.
-max-key-age <duration>VARNISH_CONTROLLER_MAX_KEY_AGE=<duration>The max key age is the maximum age the current JWT signing key can have before a new key is generated. The previous keys will be kept until there are no signed JWTs with these keys remaining. All new JWTs will be signed with the latest generated key. Both the access token and refresh token consist of a JWT that is signed with these keys. (default 24h0m0s)
-mmdb-file-csv <file/url>VARNISH_CONTROLLER_MMDB_FILE_CSV=<file/url>GeoIP database file as CSV for geolocation validation and ensuring correctness of location naming. This should be the corresponding CSV version of the GeoIP MMDB file added to the router. This is only necessary if the router is in use and the routing decision ‘Geolocation’ will be used. The argument to this flag can either be a file path or an URL. in case this is a URL, ‘Last-Modified’ header must to be set.
-mmdb-file-csv-watcher <duration>VARNISH_CONTROLLER_MMDB_FILE_CSV_WATCHER=<duration>How often to check for a new or updated GeoIP CSV file during runtime.(default 24h0m0s)
-compile-timeout <duration>VARNISH_CONTROLLER_COMPILE_TIMEOUT=<duration>When a VCLGroup is deployed OR validated its given VCL files will be compiled. This is a process
that can take some time depending on the size of the VCL files. This setting should be set larger
than the maximum time it takes to compile used VCL files. If this is set to low, timeout will occur
between both agent and brainz and also for the REST API calls for functions that compile the VCL
files. This should also be configured with the same value for api-gw. (default 1m0s)
-deploy-retry-time <duration>VARNISH_CONTROLLER_DEPLOY_RETRY_TIME=<duration>The deploy retry time is multiplied with number of current retries for a previously failed
deployment to an agent. Hence, the first retry attempt will be performed after the configured
deploy-retry-time and if that attempt also fails, the next attempt will be performed after twice
as long time. The maximum time to wait for a retry will be the deploy-retry-max configured time.
Note that deployments will not be made at the exact interval configured here. Rather it will mark the VCLGroup for deployment and brainz will take it into account during the next deployment verification that happens at least every 10sec. If a retry should be made faster, a deploy or a reload can be triggered via the API. A deploy or reload of the VCLGroup will also reset the retry counter and the back-off algorithm described here, will be reset. (default 10s)
-deploy-retry-max <duration>VARNISH_CONTROLLER_DEPLOY_RETRY_MAX=<duration>Maximum time between each retry of a previously failed deployment to an agent. When the
deploy-retry-time multiplied with the number of retries reaches a delay longer than
deploy-retry-max, the deploy-retry-max value will be used. Meaning that from now on, each deploy
attempt will be made every deploy-retry-max (until successful deployment). (default 5m0s)
-quitVARNISH_CONTROLLER_QUITWhen this argument is provided, brainz will automatically exit after performing tasks such as
-mod-admin-user for administrator user creation. This is suitable as a one shot invocation to
create the first system administrator account without the further need of exposing system
administrator credentials when starting brainz.
--helpThe varnish-controller-brainz provides a full list of parameters with --help and then exit.