Clova
Clova is a service orchestration tool designed to simplify the management of servers.
Warning
Clova is currently in early development. Expect breaking changes and do not use for mission critical infrastructure!
Quick Links:
Features
- Source-Of-Truth. Maintain a single source of truth for the definitions of your services with support for version control.
- Central Orchestration. Start, stop and monitor your services from a single location.
- Target Monitoring. View your fleet of servers at a glance and swap services between them with a single command.
- SSH-only. No need for a process to stay running on your server.
Contributing
The Clova project welcomes contributors! Please see the Contributor’s Guide to learn more about the project and how you can get involved.
Licence
Clova and its documentation are licensed under the Mozilla Public License v2.0.
Glossary
Clova uses specific terminology to refer to certain concepts throughout its CLI, the documentation and the code. This section will provide definitions for these terms.
Home : The location for which Clova data should be stored on target(s), including synchronised services.
Service : A single deployable program that can be run on a target, e.g. a Docker Compose definition, a Node application or a web server.
Service Definition : Configuration which tells Clova information about a service and how to deploy it.
Target : A destination server for services to be deployed on.
Target Definition : Configuration which tells Clova information about a target and how to interact with it.
Asking For Help
Installation
TBD (probably through Cargo)
Walkthrough
So, you’re interested in learning how to manage your servers with Clova? You’re in the right place!
Clova is designed with flexibility in mind in the hopes that it can fit into your existing workflow nicely, so you get to choose how you use it. With that being said, this guide will cover using Clova as we recommend while you’re getting started.
Need help? Ask! Either we’ll point you in the right direction, or you’ll point us in the direction of something which needs fixing!
Confused about a term? Check the glossary for key terminology used throughout Clova. If something is missing, let us know by asking for help.
Covered By This Guide
We will cover:
- The basics of what you can do with Clova and how it works, as well as how to get set up with a working directory.
- How Clova discovers and interprets configuration files.
- The general structure of a typical configuration file.
- How to define targets, both local and remote.
- How to define services.
- How to work with Clova’s CLI to deploy and manage services.
Before You Begin
You don’t need much to get started with Clova, but there are a few things that may help you:
- A basic understanding of using a terminal and working with UNIX-based systems.
- Familiarity with a text editor and the TOML configuration format.
- A basic understanding of Git.
In addition, to follow along with this walkthrough you will need:
- Clova installed on your local machine (see Installation).
- A target which you don’t mind Clova working with (this can be your local machine, but we recommend using a fresh Linux VM or server).
- (Optionally) Docker or Podman installed on your target of choice.
- (Optionally) Git installed on your local machine.
First Steps
This section will tell you a little bit about what you can do with Clova, as well as how to get set up with a basic working directory to build from.
The Basics
Clova uses the filesystem you create on your local machine to manage and manipulate the state of things on targets. You can use it to synchronise files and run commands on targets.
Because everything revolves around the filesystem, you can create a single source of truth from which you control your entire network. You can also add it to version control, allowing you to maintain consistency if managing targets from multiple machines as well as keep a history of all the changes you’ve made to your network. Made a mistake somewhere? No problem, just undo your changes and re-sync. Git to the rescue!
Fundamentally, you write a small amount of configuration alongside the files necessary to deploy your service and Clova handles the rest!
A Working Directory
Theoretically, so long as you give it the configuration it needs, Clova can work with any directory structure you desire. We recommend something similar to the following to get started:
.
├── clova.toml
├── service1/
│ ├── service.clova.toml
│ └── (other service files)
└── service2/
├── service.clova.toml
└── (other service files)
Here, we have a top-level configuration (clova.toml) and directories representing each service we wish to deploy with names that correspond to the name we’d like to give our service. Each service directory contains a configuration file with a service definition (service.clova.toml) and the other files necessary for the service to function.
When we run a command through Clova on one of these service directories, its entire contents will be synchronised to the configured target at the configured location. Any commands we run will then be executed from this directory on the target.
More on configuration later!
Initialising A Directory
Clova can create a basic working directory for you with the following command:
clova init /path/to/directory
This will do a couple of things:
- Create the directory you specified if it doesn’t already exist.
- Create a top-level configuration.
- Create a sample service directory with a sample service definition.
- Initialise the directory you specified as a Git repository, unless you specify otherwise with
--no-git-initor-g.
Once you’ve done that, cd into the directory and have a look around before moving on to the next section!
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.