Codify.json file

The codify.json file defines the desired applications, programs, CLI tools, paths, etc. that the CLI should install on the system. Let’s go over an example file to learn the syntax.

Example File

codify.json

[
  {
    "type": "homebrew",
    "formulae": ["jq", "openjdk@17", "jenv", "docker"],
    "casks": ["openvpn-connect", "1password", "google-chrome"]
  },
  { "type": "git-lfs" },
  {
    "type": "git-clone",
    "parentDirectory": "~/projects",
    "remote": "[email protected]:kevinwang5658/codify-plugin-lib.git"
  },
  {
    "type": "path",
    "path": "$HOME/projects/dev-tools/bin",
    "dependsOn": ["git-clone"]
  }
]

The codify.json file is top level json array [] with child objects representing individual configs which defines resources.

Parts of the file

1. This config block defines a homebrew resource. A resource is anything that can be installed on the operating system. It is specified in a codify.json file using the keyword type. All config blocks must have a type field.

2. Resources can also have additional parameters that configure the installation or configuration options. For the git-clone resource, we can specify the parent directory to clone into and the remote repository to clone from. Parameters can be optional or required. In this example remote is a required parameter for the git-clone resource. For more information on the git-clone resource, visit here.

3. dependsOn is a reserved keyword that is available to all resources. Use dependsOn to specify dependencies between multiple resources. Codify will this information to determine the order that plans and applies should happen in. For a full list of resource keywords, visit here.

Resource configs

Resource configs form the majority of configs found in a codify.json file. A resource config is defined by adding a json object with a type { type: "resource-type-id" } into the top level array. Resources provide Codify the ability to refresh, apply, modify and destroy packages on macOS.

codify.json

[
  {
    "type": "homebrew",
    "name": "main",
    "formulae": ["jq", "openjdk@17", "jenv", "docker"],
    "casks": ["openvpn-connect", "1password", "google-chrome"],
    "dependsOn": ["rubyenv"]
  }
]

Resources are provided by individual plugins and the available resources must be looked up in the plugin registry. For documentation on the resources provided by the default core-plugin, see here.

A name parameter can be added to a resource to fully qualify it. Names are useful for referencing a specific resource when multiple resources of the same type are in a config (for ex: multiple git clones in the example above). Codify will combine the type and the name with a . to form the fully qualified name. If there are multiple resources of the same type but no name is defined an ascending integer value will be used for the name. For example:git-clone.0, git-clone.1, git-clone.2

A dependsOn parameter can be added to control the order that multiple resources are applied. Sometimes, unrelated resources have a dependency on each other and will need to be applied in a certain order. Use "dependsOn": [] with a fully qualified id (type.name) to specify.

In the future a VSCode and Intellij plugin will be created to provide intellisense for resources. Additionally, the CLI will allow names to be looked up without having to open up the registry.

Project Configs

In addition to resource configs, a codify.json file can also have project configs. Project configs are denoted by "type": "project". The type project is reserved.

codify.json

[
  {
    "type": "project",
    "description": "A cloud infrastructure environment setup config file",
    "version": "1.0.0",
    "plugins": [
      "ssh",
      "azure"
    ]
  },
  { "type": "ssh" },
  ...
]

Project configs are mainly used to add additional plugins to a codify.json file.

Caution

Plugins developed by the core team and reviewed plugins are marked as verified on the registry. These plugins have been reviewed by the team to the best of our abilities to have no malicious code or vulnerabilities.

Unverified plugins will generate a warning and Codify will automatically run them in secure mode to prevent unauthorized sudo access.

A description can be added to describe the purpose of the codify.json file.

A version semver parameter can be added to lock the version of the Codify CLI that is applying the file. See standard semver syntax like >=0.1.0, ^1, 2.3.0 to specify the version.

Keywords

Resource Configs

• type: Use type to specify the resource type. Types are dynamic and based on the resources types provided by each plugin. Some types provided by the default plugin include: homebrew, nvm, pyenv, terraform, etc.

• name: Use name to unique identify a resource when there are multiple resources of the same type. Names must be alphanumerical including slashes and underscores. A zero indexed integer name (0, 2, 3) is automatically generated when multiple resources of the same type with no names are detected. Examples: "name": "main", "name": "infrastructure-repo".

• dependsOn: Use dependsOn to specify the order resources should be applied in. DependsOn takes an array of fully qualfied ids (type.name). Examples: "dependsOn": ["git-clone.0", "git-clone.1"],, "dependsOn": ["path.infrastructure"]

Project Configs

• type: To define a project config, the type must be project.

• description: A description of the project. This property is not used by the CodifyCLI. Example: "description": "This is a dependency setup file"

• version: The version parameter is a semver that specifies the version of CodifyCLI that must be used to apply the config. Examples: "version": ">=0.5.0", "version": "^1.3".

• plugins: A list of plugins that will be used by the config. Plugins must first be declared in the project.plugins section before they can be used. An alternative is to specify a fully qualified type plugin@resource-type instead. A local js or ts can also be specified for the plugin. This is useful for local plugin development. Example: "plugins": ["default", "../plugins/in-progress"]