---
sidebar_label: "Configuration Guide"
sidebar_custom_props:
  section: "Templates"
  section_position: 1
---

{/*

Configuration Guide pages explain how to configure and customize the technology through 
configuration files, environment variables, or settings. Include complete, working examples 
with explanations of key parameters and their effects.

*/}

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Configuration Guide Template

Learn how to configure and customize settings to meet your specific requirements.

## Configuration File Location

Configuration files are typically located in:

- **Project-level:** `./config.yml` or `./.config.yml`
- **User-level:** `~/.config/app/config.yml`
- **System-level:** `/etc/app/config.yml`

Configuration is loaded in order of precedence: project → user → system.

## Basic Configuration

<Tabs>
<TabItem value="yaml" label="YAML">

```yaml title="config.yml"
# Basic configuration example
app:
  name: my-application
  version: 1.0.0
  environment: development

server:
  host: localhost
  port: 8080
  timeout: 30

logging:
  level: info
  format: json
  output: stdout
```

</TabItem>
<TabItem value="json" label="JSON">

```json title="config.json"
{
  "app": {
    "name": "my-application",
    "version": "1.0.0",
    "environment": "development"
  },
  "server": {
    "host": "localhost",
    "port": 8080,
    "timeout": 30
  },
  "logging": {
    "level": "info",
    "format": "json",
    "output": "stdout"
  }
}
```

</TabItem>
</Tabs>

## Configuration Parameters

### Application Settings

| Parameter         | Type    | Default     | Description                          |
|-------------------|---------|-------------|--------------------------------------|
| `app.name`        | string  | -           | Application name                     |
| `app.version`     | string  | -           | Application version                  |
| `app.environment` | string  | `production`| Environment: `development`, `staging`, `production` |
| `app.debug`       | boolean | `false`     | Enable debug mode                    |

### Server Configuration

| Parameter        | Type    | Default     | Description                           |
|------------------|---------|-------------|---------------------------------------|
| `server.host`    | string  | `0.0.0.0`   | Server bind address                   |
| `server.port`    | integer | `8080`      | Server port number                    |
| `server.timeout` | integer | `30`        | Request timeout in seconds            |
| `server.tls`     | boolean | `false`     | Enable TLS/HTTPS                      |


## Advanced Configuration

### Database Connection

```yaml title="config.yml"
database:
  driver: postgresql
  host: db.example.com
  port: 5432
  name: myapp_db
  username: dbuser
  password: ${DB_PASSWORD}  # Use environment variable
  pool:
    min: 5
    max: 20
    idle_timeout: 300
```

### Feature Flags

```yaml title="config.yml"
features:
  new_ui: true
  beta_api: false
  experimental_cache: false
  analytics:
    enabled: true
    provider: google-analytics
    tracking_id: UA-XXXXX-Y
```

## Environment Variables

Configuration values can be overridden using environment variables:

| Environment Variable    | Configuration Path    | Example                  |
|-------------------------|-----------------------|--------------------------|
| `APP_NAME`              | `app.name`            | `APP_NAME=my-app`        |
| `APP_ENVIRONMENT`       | `app.environment`     | `APP_ENVIRONMENT=prod`   |
| `SERVER_PORT`           | `server.port`         | `SERVER_PORT=9000`       |
| `LOG_LEVEL`             | `logging.level`       | `LOG_LEVEL=debug`        |
| `DB_HOST`               | `database.host`       | `DB_HOST=db.prod.com`    |

**Example:**

```bash
# Override configuration with environment variables
export SERVER_PORT=9000
export LOG_LEVEL=debug
./app start
```

## Configuration Validation

Validate your configuration file before deploying:

```bash
# Check configuration syntax
command config validate

# Test configuration with dry-run
command start --dry-run

# Show effective configuration (with overrides)
command config show
```

## Common Patterns

### Using Configuration Templates

```yaml title="config.template.yml"
# Copy this file to config.yml and customize
app:
  name: ${APP_NAME:my-app}  # Default: my-app
  environment: ${ENVIRONMENT:development}

database:
  host: ${DB_HOST:localhost}
  password: ${DB_PASSWORD}  # Required, no default
```

### Splitting Configuration

```yaml title="config.yml"
# Main configuration file
includes:
  - ./config/database.yml
  - ./config/logging.yml
  - ./config/features.yml

app:
  name: my-application
```

```yaml title="config/database.yml"
database:
  driver: postgresql
  host: localhost
  port: 5432
```

:::tip Configuration Best Practices
- Use environment variables for environment-specific values
- Keep configuration files in version control (except secrets)
- Document all configuration options with comments
- Validate configuration on application startup
- Use separate configs for development, staging, and production
:::