Skip to main content
Version: v0.2.0

Getting Started

This guide will walk you through the installation of protoconf, creating a basic configuration, and running the protoconf compiler to generate the final configuration.

Installation​

On Linux and macOS, install protoconf with the install script:

curl -s https://protoconf.dev/install | sh

The script picks the release archive for your platform, verifies it against the checksums.txt published with the release, and installs the protoconf binary into /usr/local/bin — or into ~/.local/bin when /usr/local/bin is not writable, in which case it tells you how to put that directory on your PATH.

To install a specific release, or to choose the directory yourself:

curl -s https://protoconf.dev/install | sh -s -- --version v0.2.0 --dir ~/bin

The same options are available as environment variables — PROTOCONF_VERSION and PROTOCONF_INSTALL_DIR — which is usually easier to read in a Dockerfile or a CI step:

curl -s https://protoconf.dev/install | PROTOCONF_VERSION=v0.2.0 sh

Check what you got:

protoconf --version

The same script installs protoconf-terraform, the Terraform importer — name the package as its argument:

curl -s https://protoconf.dev/install | sh -s -- protoconf-terraform
tip

Piping any script into a shell runs whatever the server sends back. Read this one first if you'd rather see it: curl -s https://protoconf.dev/install | less.

Other installation methods​

On macOS, protoconf is also available from Homebrew:

brew install protoconf/tap/protoconf

Container images are published to Docker Hub and the GitHub Container Registry:

docker pull protoconf/protoconf:v0.2.0
docker pull ghcr.io/protoconf/protoconf:v0.2.0

Release archives can always be downloaded by hand from the protoconf releases page — Linux builds for amd64, arm64 and 386, macOS builds for amd64 and arm64 — and the binary added to your PATH.

Defining the Configuration Structure​

First, you'll need to define your configuration structure using Protobuf. The Protobuf files should be stored under ./src/<projectname>/<version>/<filename>.proto. For example:

syntax = "proto3";

package myproject.v1;

import "google/protobuf/duration.proto";

message ServerConfiguration {
  bool is_debug = 1;
  uint32 max_connections = 2;
  float max_payload_size_mb = 3;
  google.protobuf.Duration request_timeout = 4;
}

In this example, ServerConfiguration is the configuration structure for a server. It includes fields for debug mode (is_debug), maximum number of connections (max_connections), maximum payload size (max_payload_size_mb), and request timeout (request_timeout).

Writing the Configuration Logic​

Next, you'll write the configuration logic in a Starlark file, which should use the .pconf extension and be stored under ./src/. For example:

load("//myproject/v1/server_config.proto", "ServerConfiguration")
load("//google/protobuf/duration.proto", "Duration")

def main():
    return ServerConfiguration(
        is_debug=True,
        max_connections=1000,
        max_payload_size_mb=64.0,
        request_timeout=Duration(seconds=5),
    )

In this example, the ServerConfiguration message from the Protobuf file is loaded, and then a new ServerConfiguration object is created in the main() function.

Running the protoconf Compiler​

Finally, run the protoconf compiler to generate the final configuration:

protoconf compile .

The compiled configuration will be stored in a JSON file under ./materialized_config/<projectname>/<filename>.materialized_JSON. For example, ./materialized_config/myproject/server_config.materialized_JSON.

This JSON file contains the final, compiled configuration that your application can consume.

Formatting​

protoconf fmt keeps Starlark sources in one canonical layout, the way gofmt does for Go:

protoconf fmt -w .

See Formatting Starlark Sources.

Iterating locally​

protoconf devserver runs the agent, the compiler service and the mutation server together against a local protoconf directory, with a gRPC web UI on http://localhost:4300:

protoconf devserver .

If you only need an agent that serves what you just compiled, run it in development mode instead:

protoconf agent -dev .

Next steps​

With this, you've created your first protoconf configuration. From here: