Getting Started

Get started with Conjure by following this step-by-step tutorial to install, configure, and generate your first configuration.

This tutorial will walk you through installing Conjure, setting up your configuration, creating a templates repository, and generating your first configuration.

Prerequisites

Before you begin, ensure you have:

  • Command-line access on your machine
  • Basic familiarity with your terminal
  • A text editor installed

Note

This tutorial can be completed in under 10 minutes.

Select Your Operating System

Choose your operating system to see platform-specific commands throughout this tutorial:

Install Conjure

First, download and install Conjure for your operating system.

Install on macOS

Download the binary manually from the download page and move it to your PATH:

wget https://github.com/wizardopstechtech/conjure/releases/latest/download/conjure_1.0.0_Darwin_arm64.tar.gz
sudo mv conjure /usr/local/bin/
sudo chmod +x /usr/local/bin/conjure

Verify the installation:

conjure --version

You should see output displaying the installed version of Conjure.

Set Up Your Workspace

Create a dedicated directory for your Conjure projects. This helps keep your templates and configurations organized.

mkdir ~/conjure-workspace
cd ~/conjure-workspace

Create Your Templates Repository

Conjure requires a templates or bundles repository to operate. This repository contains the template files that Conjure will use to generate artifacts.

Repositories can be hosted in in two ways:

Create a local repository:

mkdir templates
mkdir bundles

Create a Configuration File

Conjure needs a configuration file to know where to find your templates and bundles. Create a config file in your workspace.

touch ~/.conjure.yaml

Open ~/.conjure.yaml in your text editor and add the following configuration. Replace <username> with your macOS username:

templates_source: local
bundles_source: local
templates_local_dir: /Users/<username>/conjure-workspace
bundles_local_dir: /Users/<username>/conjure-workspace

Important

Conjure does not expand the ~ shorthand in directory paths. Use fully qualified absolute paths in your configuration file.

Create Your First Template

Create a simple template to demonstrate Conjure's capabilities. Templates are at the core of how conjure operates. They use Go templating syntax to allow the creation of flexible templates.

Note

Templates are organized in versioned directories following the pattern templates/{name}/{version}/. Each version contains a conjure.json metadata file and a template.tmpl file. Variables with default: "" are required and must be provided by the user.

cd templates

Create the versioned template directory:

mkdir -p greeting/1.0.0

Create the template files:

touch greeting/1.0.0/template.tmpl
touch greeting/1.0.0/conjure.json

Open greeting/1.0.0/template.tmpl in your text editor and add the following content:

Hello, {{.name}}!

Welcome to Conjure, {{.name}}. You are part of the {{.team}} team.
This is your first generated template.

Open greeting/1.0.0/conjure.json and add the metadata:

{
  "schema_version": "v1",
  "version": "1.0.0",
  "template_name": "greeting",
  "template_type": "txt",
  "template_description": "A simple greeting template",
  "variables": [
    {
      "name": "name",
      "description": "Your name",
      "type": "string",
      "default": ""
    },
    {
      "name": "team",
      "description": "Your team name",
      "type": "string",
      "default": "Platform Engineering"
    }
  ]
}

List Templates

List the template you just created. Listing templates and bundles is useful for browsing the templates and bundles repositories.

  • Learn more about using the conjure list command to explore repositories and find templates and bundles important to you.
conjure list templates

Expected output:

Available Templates:

  greeting
    Description: A simple greeting template
    Type: txt
    Latest: 1.0.0

Total: 1 template

Generate Your First Artifact

Now that you have a template, let's use Conjure to generate an artifact from it.

Navigate back to your workspace:

cd ~/conjure-workspace

Run Conjure to generate from your template:

conjure template greeting -o greeting.txt --var name="DevOps Engineer"

You should see output confirming that Conjure generated your artifact:

Using template: greeting v1.0.0 (source: local)
Using metadata: A simple greeting template

Variables:
  name = DevOps Engineer
  team = Platform Engineering

✓ Template rendered successfully
✓ Output written to: greeting.txt

View the generated file to see your personalized greeting:

# View the generated file
cat greeting.txt

Expected output:

Hello, DevOps Engineer!

Welcome to Conjure, DevOps Engineer. You are part of the Platform Engineering team.
This is your first generated template.

Summary

Congratulations! You've successfully:

  • ✓ Installed Conjure
  • ✓ Created a workspace
  • ✓ Configured Conjure
  • ✓ Created your first template
  • ✓ Generated an artifact

Next Steps

Congratulations! You've completed the basic setup. Continue learning with these guides:

Advanced Topics


Edit on GitHub