Initial upload with full project structure
This commit is contained in:
300
app/README.md
Normal file
300
app/README.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Confgen
|
||||
|
||||
A CLI tool that generates, validates, and manages environment-specific configuration files from templates with schema validation, secrets interpolation, diff preview, and interactive editing.
|
||||
|
||||
## Features
|
||||
|
||||
- **Template-based config generation**: Define templates with Jinja2-style variable placeholders
|
||||
- **Multi-environment support**: Generate configs for dev, staging, and prod environments
|
||||
- **Schema validation**: Validate generated configs against JSON Schema definitions
|
||||
- **Secrets interpolation**: Replace secret placeholders with values from env vars or vault backends
|
||||
- **Diff preview**: Show colored diff between current and generated config before applying
|
||||
- **Interactive TUI editor**: Edit config values interactively in the terminal
|
||||
- **Output with secret masking**: Mask secret values in output with *** pattern
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Using pip
|
||||
|
||||
```bash
|
||||
pip install confgen
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Create a template file (e.g., `config.yaml.j2`):
|
||||
|
||||
```yaml
|
||||
app_name: {{APP_NAME}}
|
||||
database:
|
||||
host: {{DB_HOST}}
|
||||
port: {{DB_PORT}}
|
||||
password: {{env.SECRET_DB_PASSWORD}}
|
||||
```
|
||||
|
||||
2. Create a `confgen.yaml` configuration:
|
||||
|
||||
```yaml
|
||||
templates:
|
||||
config:
|
||||
path: config.yaml.j2
|
||||
format: yaml
|
||||
|
||||
environments:
|
||||
dev:
|
||||
variables:
|
||||
APP_NAME: myapp-dev
|
||||
DB_HOST: localhost
|
||||
DB_PORT: 5432
|
||||
prod:
|
||||
variables:
|
||||
APP_NAME: myapp
|
||||
DB_HOST: db.example.com
|
||||
DB_PORT: 5432
|
||||
```
|
||||
|
||||
3. Generate a config:
|
||||
|
||||
```bash
|
||||
confgen generate --template config --environment dev --output config.dev.yaml
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `CONFGEN_TEMPLATES_DIR` | Directory containing template files | `~/.confgen/templates` |
|
||||
| `CONFGEN_CONFIG_DIR` | Directory for generated configs | `~/.confgen/output` |
|
||||
| `CONFGEN_ENV` | Default environment (dev/staging/prod) | `dev` |
|
||||
| `CONFGEN_VAULT_URL` | Vault backend URL (optional) | `` |
|
||||
| `CONFGEN_VAULT_TOKEN` | Vault authentication token (optional) | `` |
|
||||
|
||||
### confgen.yaml
|
||||
|
||||
The main configuration file defining templates, environments, and schema:
|
||||
|
||||
```yaml
|
||||
templates:
|
||||
my_config:
|
||||
path: templates/config.yaml.j2
|
||||
format: yaml
|
||||
schema: schemas/config.json
|
||||
|
||||
environments:
|
||||
dev:
|
||||
variables:
|
||||
VAR1: value1
|
||||
staging:
|
||||
variables:
|
||||
VAR1: value2
|
||||
prod:
|
||||
variables:
|
||||
VAR1: value3
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### generate
|
||||
|
||||
Generate a configuration file from a template.
|
||||
|
||||
```bash
|
||||
confgen generate [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--template, -t` | Template name (required) |
|
||||
| `--environment, -e` | Environment name (default: dev) |
|
||||
| `--output, -o` | Output file path |
|
||||
| `--format, -f` | Output format (json/yaml/toml) |
|
||||
| `--validate` | Validate generated config against schema |
|
||||
| `--diff` | Show diff before applying |
|
||||
| `--edit` | Open interactive editor |
|
||||
|
||||
### list
|
||||
|
||||
List available templates and environments.
|
||||
|
||||
```bash
|
||||
confgen list [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--templates` | List available templates |
|
||||
| `--environments` | List available environments |
|
||||
| `--env` | Show variables for specific environment |
|
||||
|
||||
### validate
|
||||
|
||||
Validate a configuration file against a schema.
|
||||
|
||||
```bash
|
||||
confgen validate [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--config, -c` | Config file to validate |
|
||||
| `--schema, -s` | Schema file path |
|
||||
| `--template, -t` | Template name to use its schema |
|
||||
|
||||
### edit
|
||||
|
||||
Open interactive editor for editing config values.
|
||||
|
||||
```bash
|
||||
confgen edit [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--template, -t` | Template name (required) |
|
||||
| `--environment, -e` | Environment name |
|
||||
| `--output, -o` | Output file path |
|
||||
|
||||
## Template Syntax
|
||||
|
||||
### Variables
|
||||
|
||||
Use Jinja2-style syntax for variable substitution:
|
||||
|
||||
```yaml
|
||||
app_name: {{APP_NAME}}
|
||||
port: {{PORT}}
|
||||
debug: {{DEBUG_MODE}}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Access environment variables with `env.` prefix:
|
||||
|
||||
```yaml
|
||||
password: {{env.SECRET_PASSWORD}}
|
||||
database_url: {{env.DATABASE_URL}}
|
||||
```
|
||||
|
||||
### Secrets (with masking)
|
||||
|
||||
Secrets are automatically masked in output:
|
||||
|
||||
```yaml
|
||||
api_key: {{vault.SECRET_API_KEY}}
|
||||
db_password: {{env.SECRET_DB_PASSWORD}}
|
||||
```
|
||||
|
||||
### Conditionals
|
||||
|
||||
Use Jinja2 conditionals:
|
||||
|
||||
```yaml
|
||||
{% if USE_CACHE %}
|
||||
cache:
|
||||
enabled: true
|
||||
ttl: {{CACHE_TTL}}
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
### Loops
|
||||
|
||||
Use Jinja2 loops:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
{% for service in SERVICES %}
|
||||
- name: {{service.name}}
|
||||
port: {{service.port}}
|
||||
{% endfor %}
|
||||
```
|
||||
|
||||
## Secrets Management
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Secrets from environment variables:
|
||||
|
||||
```yaml
|
||||
password: {{env.SECRET_PASSWORD}}
|
||||
```
|
||||
|
||||
### Vault Backend
|
||||
|
||||
Secrets from a vault backend:
|
||||
|
||||
```yaml
|
||||
api_key: {{vault.SECRET_API_KEY}}
|
||||
```
|
||||
|
||||
Configure vault with environment variables:
|
||||
- `CONFGEN_VAULT_URL`: Vault server URL
|
||||
- `CONFGEN_VAULT_TOKEN`: Authentication token
|
||||
|
||||
## Schema Validation
|
||||
|
||||
Validate your configurations against JSON Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"app_name": {"type": "string"},
|
||||
"port": {"type": "integer", "minimum": 1, "maximum": 65535},
|
||||
"debug": {"type": "boolean"}
|
||||
},
|
||||
"required": ["app_name", "port"]
|
||||
}
|
||||
```
|
||||
|
||||
## Interactive Editor
|
||||
|
||||
Launch an interactive terminal UI to edit config values:
|
||||
|
||||
```bash
|
||||
confgen edit --template my_config --environment dev
|
||||
```
|
||||
|
||||
The editor provides:
|
||||
- Type-aware input validation
|
||||
- Default values from template
|
||||
- Secret field masking
|
||||
- Environment-specific editing
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
pip install -e .[dev]
|
||||
|
||||
# Run tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Run with coverage
|
||||
pytest tests/ --cov=src/confgen --cov-report=term-missing
|
||||
|
||||
# Format code
|
||||
black src/confgen tests/
|
||||
|
||||
# Lint code
|
||||
ruff check src/confgen tests/
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See the `examples/` directory for complete examples:
|
||||
- `simple.yaml`: Basic template example
|
||||
- `complex.yaml`: Template with secrets and conditionals
|
||||
- `schema.json`: JSON Schema for validation
|
||||
- `confgen.yaml`: Complete configuration example
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user