Geomancy#
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#
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 an environment file and a secrets
file can be checked based on the This check file can be used to check multiple environments: In this case,
Validation of layered and combined environments
$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"
# 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
...
deployments/dev/.env
is an
environment file
that sets ENV=dev
, deployments/test/.env
is an
environment file
that sets ENV=test
.
Environment files are loaded using the
Full environment file support of the docker
env file syntax
-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"
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.
Concurrent checks with multiple threads to quickly probe
I/O bound resources
AWS:
TemplateS3:
checkS3: myproject-cfn-templates
StaticS3:
checkS3: myproject-static
MediaS3:
checkS3: myproject-media
Including yaml (e.g. or toml (e.g. or toml with each check on 1 line (e.g.
Load checks in multiple formats
.geomancy.yaml
)checks:
Environment:
desc: Check environment variables common to all development environments
Path:
decs: Search paths for executables
checkEnv: $PATH
.geomancy.toml
)[checks.Environment]
desc = "Check environment variables common to all development environments"
[checks.Environment.Path]
desc = "Search paths for executables"
checkEnv = "$PATH"
.geomancy.toml
)[Checks.Environment]
Path = {checkEnv = "$PATH", desc = "Search paths for executables"}
[tool.geomancy.checks.Environment]
desc = "Check environment variables common to all development environments"
[tool.geomancy.checks.Environment.Path]
desc = "Search paths for executables"
checkEnv = "$PATH"
Available Checks#
The following shows an example in yaml format. Checks can be formatted in
toml format as well.Operating systems meet the minimum required
versions
(checkOS)
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"
The following shows an example in yaml format. Checks can be formatted in
toml format as well.Environment variables are properly set and
have valid values with regular expressions
(checkEnv)
Username:
desc: The current username
checkEnv: "$USER"
regex: "[a-z_][a-z0-9_-]*[$]?"
The following shows an example in yaml format. Checks can be formatted in
toml format as well.Paths exist and they're the right type
(checkPath)
PyprojectToml:
desc: A project's pyprojectfile
checkPath: ./pyproject.toml
type: file
The following shows an example in yaml format. Checks can be formatted in
toml format as well.Executables are available and meet minimum
or correct versions
(checkExec)
Python:
desc: Python interpreter (version 3.11 or higher)
checkExec: "python3>=3.11"
The following shows an example in yaml format. Checks can be formatted in
toml format as well.Python packages are available minimum or
correct versions
(checkPythonPkg)
PythonPackages:
geomancy:
desc: Geomancy python package
checkPythonPkg: "geomancy>=0.1"
The following shows an example with the The The This example is in yaml format, and checks can be formatted in toml format
as well.Group checks and specify
conditional (all or any) pass criteria
(Groups of Checks)
checks
group containing 2 groups,
OperatingSystem
, Environment
.OperatingSystem
group contains 3 checks: checkMacOS
,
checkLinuxOS
, checkWindows
, and the OperatingSystem
group check
passes if any of these 3 checks pass (subchecks: any
)Environment
group contains 1 check, Path
, and 1 group, Username
,
which itself contains 2 checks: UnixUsername
and WindowsUsername
.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_-]*[$]?"
The following shows an example in yaml format. Checks can be formatted in
toml format as well.AWS resources exist and are securely setup
(AWS checks)
AWS:
IAM:
desc: Check the default authentication and security settings
checkIAM:
TemplatesS3Bucket:
desc: Check the bucket for cloudformation templates
checkS3: "myproject-cfn-templates"