geomancy 1.0.0

Geomancy validates deployment and development environments

Geomancy makes it easy to check and validate environments, such as development, testing and production.

Environment checks and tests are helpful for testing the correct setting of environment variables, the installation and versions of installed executables, the state of external dependencies, like LaTeX packages, or cloud resources, or for checking environments that use the 12-factor principles.

Features

Capabilities

Validation of layered and combined environments

Layered environments could include a common or base environment, with additional checks for settings of test, development and production environments.

In the following checks file, the existence of environment file and secrets file can be checked based on the $ENV environment variable. (See the docker environment variable parameter expansion rules)

checks:
  Environment:
    desc: Check environment variables in different deployments

    CheckEnvFile:
      desc: Check the existence of the environment file
      checkPath: "deployments/${ENV}/.env"

    CheckSecretsFile:
      desc: Check the existence of the secrets file
      checkPath: "deployments/${ENV}/.secrets"

This check file can be used to check multiple environments:

# check "dev" environment
$ geo -e deployments/base/.env -e deployments/dev/.env checks.yaml
...
# check "test" environment
$ geo -e deployments/base/.env -e deployments/test/.env checks.yaml
...

In this case, deployments/dev/.env is an environment file that sets ENV=dev, deployments/test/.env is an environment file that sets ENV=test.

Full environment file support of the docker env file syntax

Environment files are loaded using the -e/--env option, which can be layered for different environments.

# Run checks for 'dev' environment
$ geo -e deployments/base/.env -e deployments/dev/.env check
...
# Run checks for 'test' environment
$ geo -e base.env -e test.env run -- echo "Test environment"

Concurrent checks with multiple threads to quickly probe I/O bound resources

The following example concurrently checks that the 3 AWS S3 buckets are accessible using the current credentials and are secured.

This example is in yaml format, and checks can be formatted in toml format as well.

AWS:
  TemplateS3:
    checkS3: myproject-cfn-templates
  StaticS3:
    checkS3: myproject-static
  MediaS3:
    checkS3: myproject-media

Load checks in multiple formats

Including yaml (e.g. .geomancy.yaml)

checks:
  Environment:
    desc: Check environment variables common to all development environments

    Path:
      decs: Paths to search for executables
      checkEnv: $PATH

or toml (e.g. .geomancy.toml)

[checks.Environment]
desc = "Check environment variables common to all development environments"

    [checks.Environment.Path]
    desc = "Paths to search for executables"
    checkEnv = "$PATH"

or pyproject.toml

[tool.geomancy.checks.Environment]
desc = "Check environment variables common to all development environments"

    [tool.geomancy.checks.Environment.Path]
    desc = "Paths to search for executables"
    checkEnv = "$PATH"

Available Checks

Operating systems meet the minimum required versions (checkOS)

The following shows an example in yaml format. Checks can be formatted in toml format as well.

OperatingSystem:
  desc: Check the minimum operating system versions
  subchecks: any

  checkMacOS:
    desc: MacOS 10.9 or later (released 2013)
    checkOS: "macOS >= 10.9"
  checkLinuxOS:
    desc: Linux 4.0 or later (released 2015)
    checkOS: "Linux >= 3.0"
  checkWindows:
    desc: Windows 10 or later (released 2015)
    checkOS: "Windows >= 10"

Environment variables are properly set and have valid values with regular expressions (checkEnv)

The following shows an example in yaml format. Checks can be formatted in toml format as well.

Username:
  desc: The current username
  checkEnv: "$USER"
  regex: "[a-z_][a-z0-9_-]*[$]?"

Paths exist and they're the right type (checkPath)

The following shows an example in yaml format. Checks can be formatted in toml format as well.

PyprojectToml:
  desc: A project's pyprojectfile
  checkPath: ./pyproject.toml
  type: file

Executables are available and meet minimum or correct versions (checkExec)

The following shows an example in yaml format. Checks can be formatted in toml format as well.

Python:
  desc: Python interpreter (version 3.11 or higher)
  checkExec: "python3>=3.11"

Python packages are available minimum or correct versions (checkPythonPkg)

The following shows an example in yaml format. Checks can be formatted in toml format as well.

PythonPackages:
  geomancy:
    desc: Geomancy python package
    checkPythonPkg: "geomancy>=0.1"

Group checks and specify conditional (all or any) pass criteria (Groups of Checks)

The following shows an example with the checks group containing 2 groups, OperatingSystem, Environment.

The OperatingSystem group contains 3 checks: checkMacOS, checkLinuxOS, checkWindows, and the OperatingSystem group check passes if any of these 3 checks pass (subchecks: any)

The Environment group contains 1 check, Path, and 1 group, Username, which itself contains 2 checks: UnixUsername and WindowsUsername.

This example is in yaml format, and checks can be formatted in toml format as well.

checks:
  OperatingSystem:
    desc: Check the minimum operating system versions
    subchecks: any

    checkMacOS:
      desc: MacOS 10.9 or later (released 2013)
      checkOS: "macOS >= 10.9"
    checkLinuxOS:
      desc: Linux 4.0 or later (released 2015)
      checkOS: "Linux >= 3.0"
    checkWindows:
      desc: Windows 10 or later (released 2015)
      checkOS: "Windows >= 10"

  Environment:
    desc: Check environment variables common to all development environments

    Path:
      decs: Paths to search for executables
      checkEnv: $PATH
    Username:
      subchecks: any

      UnixUsername:  # Username on linux and macOS
        desc: The current username
        checkEnv: $USER
        regex: "[a-z_][a-z0-9_-]*[$]?"
      WindowsUsername:  # Username on Windows
        desc: The current username
        checkEnv: $USERNAME
        regex: "[a-z_][a-z0-9_-]*[$]?"

AWS resources exist and are securely setup (checkS3)

The following shows an example in yaml format. Checks can be formatted in toml format as well.

AWS:
  TemplatesS3Bucket:
    desc: The bucket for cloudformation templates
    checkS3: "myproject-cfn-templates"

Quickstart

1. Create a .geomancy.yaml file with checks. See examples/geomancy.yaml for an example of all checks.

   checks:
     Environment:
       desc: Check environment variables common to all development environments
   
       Username:
         desc: The current username
         checkEnv: "$USER"
         regex: "[a-z_][a-z0-9_-]*[$]?"
   
     Paths:
       desc: Checks the existence of needed files and directories
       subchecks: "any" # at least one of the files must be present
   
       Geomancy:
         desc: Check for the 'geomancy.toml' file
         checkPath: examples/geomancy.toml
         type: file
       Pyproject:
         desc: Check for 'pyproject.toml' file
         checkPath: examples/pyproject.toml
         type: file
   
     Executables:
       desc: Check the availability of commands and their versions
   
       Python:
         desc: Python interpreter ver 3.11 or higher
         checkExec: python3>=3.11
   

2. Use geo to run the checks.

   $ geo check
   [✔] .geomancy.yaml...passed
   [✔]   checks...passed
   [✔]     Environment...passed
   [✔]       Check environment variable '$USER'......passed
   [✔]     Paths...passed
   [✔]       Check path 'examples/geomancy.toml'......passed
   [✔]       Check path 'examples/pyproject.toml'......passed
   

   (By default, geomancy will search .geomancy.y[a]ml, geomancy.y[a]ml .geomancy.toml, geomancy.toml and pyproject.toml.)

Documentation

For full documentation please see https://geomancy.readthedocs.io/en/latest.

Bugs or Requests

Please use the GitHub issue tracker to submit bugs or request features.

License

Copyright Justin Lorieau and others, 2023.

Distributed under the terms of the MIT license. geomancy is free and open source software.