Configuration Files

We’ve already seen that Clova can work with multiple TOML-based configuration files, and that these files can be placed wherever you would like in your working directory. This section will give you an overview of how Clova discovers and interprets your configuration.

When you work with Clova operations, you will specify a service directory that will be used as context. For example, if you run the command clova start /path/to/service, you are telling it to start the service in the context of the service directory /path/to/service. It will then discover and interpret the configuration relevant to this context.

At a basic level, this effectively means Clova only knows about one service at a time.

Discovery

There are two ways to tell Clova how to discover configuration for a service: manually or automatically.

We’ll use the following working directory structure to illustrate each:

.
├── clova.toml
└── networking/
    ├── group.clova.toml
    ├── cloudflared/
    │   ├── service.clova.toml
    │   └── (other service files)
    └── tailscaled/
        ├── service.clova.toml
        ├── tailscale.toml
        └── (other service files)

Manual

With manual discovery, you tell Clova the path to the configuration files you want it to use for an operation. You do this using the --config or -c flag.

So, for example, if you wanted to start the cloudflared service using only ./clova.toml and ./networking/cloudflared/service.clova.toml, you would run the following command:

clova -c ./clova.toml -c ./networking/cloudflared/service.clova.toml start ./networking/cloudflared

When you opt for manual discovery, no automatic discovery occurs, so you have to declare every configuration file you want Clova to consider, including top-level configuration. Notice also that configuration flags go before the subcommand (in this case start). This is because they are a global flag.

Further, the only requirement for configuration files passed to Clova manually are that they are the correct format for Clova (TOML). They can be named anything.

Automatic

If you don’t specify any configuration files manually, Clova will attempt to automatically discover them. It does this by looking for any and all files with the name clova.toml or the name ending in .clova.toml, starting in the directory you ran the command in and ending in the service directory you gave it.

So, for example, if you wanted to start the tailscaled, you would run the following command:

clova start ./networking/tailscaled

When you run this command, Clova will look in the following directories:

• ./
  • ./networking
    • ./networking/tailscaled

Finding the following configuration files:

• ./clova.toml
• ./networking/group.clova.toml
• ./networking/tailscaled/service.clova.toml

Notice that it does not consider ./networking/tailscaled/tailscale.toml, even if it contains a valid Clova configuration. This is again because Clova only looks for files named clova.toml or with the extension .clova.toml.

Interpretation

In any case, Clova will take all the configuration it finds and merge them to create one overall configuration containing general configuration, targets and the service relevant to the context of the service directory in question.

This overall configuration will usually contain the following things:

• General configuration used to determine how Clova behaves and works, both with your local machine and with targets.
• One or more target definitions which will tell Clova where to find targets and how to interact with them.
• One service definition corresponding to the service that Clova is working on in that moment.