# Secrets and Configuration

Secrets and config let you parameterize values that services need. Use them to avoid hardcoding values in your `specific.hcl`.

## When to use which

- **Secrets** - For sensitive information that should never be committed to version control: API keys, database passwords, signing keys, etc.
- **Config** - For non-sensitive values that may vary between environments: log levels, feature flags, URLs, etc.

## Secrets

Declare secrets that your application needs in `specific.hcl`:

```hcl
secret "stripe_api_key" {}

secret "jwt_secret" {
  generated = true
}

service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    STRIPE_API_KEY = secret.stripe_api_key
    JWT_SECRET = secret.jwt_secret
  }
}
```

### Secret fields

- `generated` - When `true`, auto-generates a random 64-character string if not manually set. Useful for internal secrets like JWT signing keys.
- `length` - Custom length for generated secrets (default: 64). Only applies when `generated = true`.

### Setting secret values

For local development, add secrets to the `secrets` block in `specific.local`:

```hcl
# specific.local
secrets {
  stripe_api_key = "sk_test_..."
}
```

### Generated vs manual secrets

- **Manual secrets** (no `generated` flag) - Must be set in `specific.local`. Error on startup if missing.
- **Generated secrets** (`generated = true`) - Auto-created on first run if not set. You can still override manually.

## Config

Parameterize non-sensitive configuration values across environments.

```hcl
config "log_level" {
  default = "info"
}

service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    LOG_LEVEL = config.log_level
  }
}
```

### Config fields

- `default` - Default value used if not overridden by an environment.

### Setting config values locally

For local development, you can override config defaults in the `config` block of `specific.local`:

```hcl
# specific.local
config {
  log_level = "debug"
}
```

### Environment overrides

Override config values per environment in `specific.hcl`:

```hcl
config "log_level" {
  default = "info"
}

environment "production" {
  config = {
    log_level = "warn"
  }
}

environment "staging" {
  config = {
    log_level = "debug"
  }
}
```

## Local values file

For local development, secrets and config values are stored in `specific.local` (gitignored). The user does not have to fill this out manually. When running, `specific dev`, they will be asked for any missing secrets and config values. The file. This file uses HCL format with separate blocks for secrets and configs:

```hcl
# specific.local
secrets {
  stripe_api_key = "sk_test_..."
}

config {
  log_level = "debug"
}
```

This file is automatically gitignored and not included in deployments. Production secrets are configured separately during deployment.

## Example

```hcl
# specific.hcl

# External API key - must be set manually, sensitive
secret "stripe_api_key" {}

# Internal signing key - auto-generate, sensitive
secret "jwt_secret" {
  generated = true
}

# Log level - not sensitive, varies by environment
config "log_level" {
  default = "info"
}

service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    STRIPE_API_KEY = secret.stripe_api_key
    JWT_SECRET = secret.jwt_secret
    LOG_LEVEL = config.log_level
  }
}

environment "production" {
  config = {
    log_level = "warn"
  }
}
```

And the corresponding local values file:

```hcl
# specific.local (gitignored)
secrets {
  stripe_api_key = "sk_test_..."
}

config {
  log_level = "debug"
}
```
