# Local Provider

The **local** provider is a special built-in provider for storing secrets directly on the local filesystem. Unlike other providers that connect to external systems, the local provider operates entirely on your local machine, making it ideal for development, testing, and scenarios where secrets need to be stored as files.

## Overview

| Property | Value |
|----------|-------|
| **Provider Kind** | `local` |
| **Authentication** | None required |
| **Target Types** | `file`, `template` |
| **Use Cases** | Local development, `.env` files, configuration files, template rendering |

## Features

- ✅ **No external dependencies** - Works immediately without configuration
- ✅ **Multiple file formats** - Supports dotenv, JSON, YAML, and TOML
- ✅ **Template rendering** - Generate configuration files from Jinja2 templates
- ✅ **File merging** - Optionally merge secrets with existing files
- ✅ **Always available** - Built into SecretZero, no installation needed

## Configuration

The local provider does not require any configuration or authentication. Simply specify `provider: local` in your target configuration.

```yaml
providers:
  local:
    kind: local  # Optional - local provider doesn't need explicit configuration
```

In most cases, you can use `provider: local` directly in targets without defining it in the `providers` section.

## Target Types

### File Target

Store secrets in local files with various formats.

**Configuration Options:**

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `path` | `string` | Yes | - | File path (relative or absolute) |
| `format` | `string` | Yes | - | File format: `dotenv`, `json`, `yaml`, `toml` |
| `merge` | `boolean` | No | `true` | Merge with existing file content |

**Example - .env file:**

```yaml
secrets:
  - name: database_password
    kind: random_password
    config:
      length: 32
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true
```

**Generated .env file:**
```env
DATABASE_PASSWORD=Xy9k2...random...
```

**Example - JSON Configuration:**

```yaml
secrets:
  - name: api_credentials
    kind: static
    config:
      default: '{"key": "abc123", "secret": "xyz789"}'
    targets:
      - provider: local
        kind: file
        config:
          path: config/credentials.json
          format: json
          merge: false
```

**Example - YAML Configuration:**

```yaml
secrets:
  - name: app_config
    kind: static
    config:
      default: |
        database:
          host: localhost
          port: 5432
        api:
          timeout: 30
    targets:
      - provider: local
        kind: file
        config:
          path: config.yaml
          format: yaml
```

### Template Target

Render Jinja2 templates with secret values to generate configuration files.

**Configuration Options:**

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `template_path` | `string` | Yes | - | Path to Jinja2 template file |
| `output_path` | `string` | Yes | - | Path for rendered output file |

**Example Template (config.yaml.j2):**

```jinja2
database:
  host: {{ db_host }}
  port: {{ db_port }}
  password: {{ db_password }}
  
api:
  key: {{ api_key }}
  endpoint: {{ api_endpoint }}
```

**Secretfile configuration:**

```yaml
secrets:
  - name: app_config
    kind: templates.server_config
    config:
      db_host: localhost
      db_port: 5432
      db_password:
        generator: random_password
        length: 32
      api_key:
        generator: random_string
        length: 64
      api_endpoint: https://api.example.com
    targets:
      - provider: local
        kind: template
        config:
          template_path: config.yaml.j2
          output_path: config.yaml
```

## File Formats

### Dotenv Format

Standard `.env` file format for environment variables:

```env
# Generated by SecretZero
DATABASE_URL=postgresql://localhost/mydb
API_KEY=abc123xyz789
SECRET_KEY=random_secret_value
```

**Characteristics:**
- Key-value pairs: `KEY=value`
- Comments start with `#`
- No nested structures
- Ideal for environment variables

### JSON Format

Structured JSON for complex configurations:

```json
{
  "database": {
    "password": "secret123",
    "url": "postgresql://localhost/mydb"
  },
  "api": {
    "key": "abc123",
    "secret": "xyz789"
  }
}
```

**Characteristics:**
- Supports nested objects
- Strict syntax
- Good for structured data

### YAML Format

Human-readable YAML configuration:

```yaml
database:
  password: secret123
  url: postgresql://localhost/mydb

api:
  key: abc123
  secret: xyz789
```

**Characteristics:**
- Indentation-based structure
- Supports comments
- Most readable format

### TOML Format

Configuration file format popular in Rust/Python:

```toml
[database]
password = "secret123"
url = "postgresql://localhost/mydb"

[api]
key = "abc123"
secret = "xyz789"
```

**Characteristics:**
- Section-based structure
- Type-safe values
- Good for configuration files

## Common Use Cases

### Local Development Environment

Create a complete `.env` file for local development:

```yaml
version: '1.0'

secrets:
  - name: db_password
    kind: random_password
    config:
      length: 16
      special: false
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

  - name: jwt_secret
    kind: random_string
    config:
      length: 32
      charset: hex
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

  - name: api_key
    kind: static
    config:
      default: ${API_KEY}
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true
```

### Docker Compose Configuration

Generate secrets for Docker Compose:

```yaml
secrets:
  - name: postgres_password
    kind: random_password
    config:
      length: 24
    targets:
      - provider: local
        kind: file
        config:
          path: docker/secrets/postgres_password.txt
          format: json

  - name: redis_password
    kind: random_password
    config:
      length: 24
    targets:
      - provider: local
        kind: file
        config:
          path: docker/secrets/redis_password.txt
          format: json
```

### Application Configuration Files

Generate complete app configuration from templates:

```yaml
templates:
  app_config:
    description: Application configuration
    fields:
      - name: database_url
        description: Database connection URL
        generator: static
        config:
          default: postgresql://localhost:5432/myapp
      - name: database_password
        description: Database password
        generator: random_password
        config:
          length: 32
      - name: redis_url
        description: Redis connection URL
        generator: static
        config:
          default: redis://localhost:6379

secrets:
  - name: app_config
    kind: templates.app_config
    targets:
      - provider: local
        kind: template
        config:
          template_path: templates/config.yaml.j2
          output_path: config/production.yaml
```

## File Merging Behavior

When `merge: true` (default), SecretZero will:

1. **Read existing file** if it exists
2. **Parse the content** according to the format
3. **Update matching keys** with new secret values
4. **Preserve other keys** that aren't in the secret definition
5. **Write back** the merged content

**Example:**

**Existing .env:**
```env
# User-defined settings
APP_NAME=MyApp
DEBUG=true
DATABASE_PASSWORD=old_password
```

**After sync with merge: true:**
```env
# User-defined settings
APP_NAME=MyApp
DEBUG=true
DATABASE_PASSWORD=new_generated_password
```

When `merge: false`, the file is completely replaced:

```env
DATABASE_PASSWORD=new_generated_password
```

## Security Considerations

### ⚠️ Important

- **Do not commit secrets to version control** - Add secret files to `.gitignore`
- **Restrict file permissions** - Use `chmod 600` for sensitive files
- **Be careful with templates** - Template outputs may contain sensitive data
- **Local files are unencrypted** - For production, use external providers

### Recommended .gitignore

```gitignore
# SecretZero generated files
.env
.env.local
*.secret.json
*.secret.yaml
config/secrets/
secrets/

# Lockfile may contain hashed values (optional)
.gitsecrets.lock
```

### File Permissions

SecretZero attempts to set restrictive permissions on secret files:

```bash
# Automatically set by SecretZero
-rw------- 1 user user  256 Jan 1 12:00 .env
-rw------- 1 user user  512 Jan 1 12:00 secrets.json
```

## Best Practices

### ✅ Do

- Use local provider for development and testing
- Combine with cloud providers for multi-stage deployments
- Store templates in version control, not rendered outputs
- Use `.env` files for environment variables
- Set `merge: true` to preserve manual configurations

### ❌ Don't

- Use local provider for production deployments (prefer cloud providers)
- Commit generated secret files to version control
- Store production secrets in local files
- Use absolute paths (prefer relative paths for portability)

## Limitations

- **No encryption at rest** - Files are stored in plain text
- **No access control** - Relies on filesystem permissions
- **No audit logging** - No record of who accessed secrets
- **No versioning** - No built-in secret rotation history
- **No high availability** - Files are local to one machine

For production environments, consider using cloud providers like [AWS](aws.md), [Azure](azure.md), or [Vault](vault.md) which provide encryption, access control, and audit logging.

## Related Documentation

- [File Targets](../targets/file.md) - Detailed file target configuration
- [Template Targets](../targets/template.md) - Template rendering guide
- [Local Development Use Case](../../use-cases/local-development.md) - Complete local dev example
- [Secretfile Configuration](../configuration/secretfile.md) - Secretfile reference

## Next Steps

- [Learn about cloud providers →](index.md)
- [Configure AWS provider →](aws.md)
- [Set up Vault provider →](vault.md)
- [View local development examples →](../../examples/index.md)
