py-wikijs/docs/CONFIGURATION_GUIDE.md

# Configuration Guide - py-wikijs

Complete guide to configuring the py-wikijs client for your project.

---

## 📋 Table of Contents

- [Quick Start](#quick-start)
- [Configuration Methods](#configuration-methods)
- [Configuration Options](#configuration-options)
- [Examples](#examples)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## 🚀 Quick Start

### **Simplest Method (Hardcoded)**

```python
from wikijs import WikiJSClient

client = WikiJSClient(
    url='https://wiki.example.com',
    auth='your-api-key-here'
)
```

⚠️ **Not recommended for production** - credentials should not be hardcoded!

### **Recommended Method (Environment Variables)**

```bash
# Set environment variables
export WIKIJS_URL="https://wiki.example.com"
export WIKIJS_API_KEY="your-api-key-here"
```

```python
import os
from wikijs import WikiJSClient

client = WikiJSClient(
    url=os.getenv('WIKIJS_URL'),
    auth=os.getenv('WIKIJS_API_KEY')
)
```

### **Best Method (Configuration File)**

Use the config helper (recommended):

```python
from examples.config_helper import create_client_from_config

# Auto-detects config file
client = create_client_from_config()
```

---

## 📁 Configuration Methods

py-wikijs supports multiple configuration methods. Choose the one that best fits your workflow.

### **Method 1: Environment Variables (.env)**

**Best for**: Development, Docker deployments, 12-factor apps

#### Setup:

1. **Copy the example file**:
   ```bash
   cp examples/config.env.example .env
   ```

2. **Edit `.env`** with your settings:
   ```bash
   WIKIJS_URL=https://wiki.example.com
   WIKIJS_API_KEY=your-api-key-here
   WIKIJS_TIMEOUT=30.0
   WIKIJS_RATE_LIMIT=10.0
   ```

3. **Load in your code**:
   ```python
   from dotenv import load_dotenv
   from examples.config_helper import create_client_from_config

   load_dotenv()
   client = create_client_from_config()
   ```

#### Advantages:
- ✅ Keep secrets out of code
- ✅ Easy to change without code modification
- ✅ Works great with Docker/containers
- ✅ Standard 12-factor app methodology

#### Requirements:
```bash
pip install python-dotenv
```

---

### **Method 2: YAML Configuration**

**Best for**: Complex configurations, multiple environments

#### Setup:

1. **Copy the example file**:
   ```bash
   cp examples/config.yaml.example config.yaml
   ```

2. **Edit `config.yaml`**:
   ```yaml
   wikijs:
     url: "https://wiki.example.com"
     auth:
       method: "api_key"
       api_key: "your-api-key-here"

   client:
     timeout: 30.0
     rate_limit: 10.0

   logging:
     level: "INFO"
   ```

3. **Load in your code**:
   ```python
   from examples.config_helper import create_client_from_config

   client = create_client_from_config('config.yaml')
   ```

#### Advantages:
- ✅ Human-readable and editable
- ✅ Supports complex nested structures
- ✅ Easy to comment and document
- ✅ Great for environment-specific configs

#### Requirements:
```bash
pip install pyyaml
```

---

### **Method 3: JSON Configuration**

**Best for**: Programmatic configuration, API-driven setups

#### Setup:

1. **Copy the example file**:
   ```bash
   cp examples/config.json.example config.json
   ```

2. **Edit `config.json`**:
   ```json
   {
     "wikijs": {
       "url": "https://wiki.example.com",
       "auth": {
         "method": "api_key",
         "api_key": "your-api-key-here"
       }
     },
     "client": {
       "timeout": 30.0,
       "rate_limit": 10.0
     }
   }
   ```

3. **Load in your code**:
   ```python
   from examples.config_helper import create_client_from_config

   client = create_client_from_config('config.json')
   ```

#### Advantages:
- ✅ Standard format
- ✅ Easy to generate programmatically
- ✅ Works with JSON APIs
- ✅ No additional dependencies

---

### **Method 4: INI Configuration**

**Best for**: Traditional configurations, legacy systems

#### Setup:

1. **Copy the example file**:
   ```bash
   cp examples/config.ini.example config.ini
   ```

2. **Edit `config.ini`**:
   ```ini
   [wikijs]
   url = https://wiki.example.com
   auth_method = api_key
   api_key = your-api-key-here

   [client]
   timeout = 30.0
   rate_limit = 10.0
   ```

3. **Load in your code**:
   ```python
   from examples.config_helper import create_client_from_config

   client = create_client_from_config('config.ini')
   ```

#### Advantages:
- ✅ Simple format
- ✅ No dependencies
- ✅ Familiar to many developers

---

### **Method 5: Python Dictionary**

**Best for**: Dynamic configuration, testing

```python
from examples.config_helper import create_client_from_config

config = {
    'wikijs': {
        'url': 'https://wiki.example.com',
        'auth': {
            'method': 'api_key',
            'api_key': 'your-api-key-here'
        }
    },
    'client': {
        'timeout': 30.0,
        'rate_limit': 10.0
    }
}

client = create_client_from_config(config)
```

---

## ⚙️ Configuration Options

### **Required Options**

| Option | Type | Description | Example |
|--------|------|-------------|---------|
| `wikijs.url` | string | Wiki.js instance URL | `https://wiki.example.com` |
| `wikijs.auth.api_key` | string | API key for authentication | `ey12345...` |

### **Client Options**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client.timeout` | float | 30.0 | Request timeout (seconds) |
| `client.rate_limit` | float | None | Max requests per second |
| `client.max_retries` | int | 3 | Number of retry attempts |
| `client.verify_ssl` | bool | true | Verify SSL certificates |
| `client.pool_size` | int | 10 | Connection pool size |
| `client.user_agent` | string | Auto | Custom User-Agent header |

### **Authentication Options**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `wikijs.auth.method` | string | "api_key" | Auth method (api_key, jwt, none) |
| `wikijs.auth.api_key` | string | - | API key (for api_key method) |
| `wikijs.auth.jwt_token` | string | - | JWT token (for jwt method) |

### **Logging Options**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `logging.debug` | bool | false | Enable debug logging |
| `logging.level` | string | "INFO" | Log level (DEBUG, INFO, WARNING, ERROR) |
| `logging.format` | string | - | Custom log format string |

### **Metrics Options**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `metrics.enabled` | bool | true | Enable metrics collection |

---

## 💡 Examples

### **Example 1: Basic Connection**

```python
from examples.config_helper import create_client_from_config

# Auto-detect config file
client = create_client_from_config()

# List pages
pages = client.pages.list()
print(f"Found {len(pages)} pages")
```

### **Example 2: Multiple Environments**

**config.yaml**:
```yaml
environments:
  production:
    wikijs:
      url: "https://wiki.company.com"
    logging:
      level: "WARNING"

  staging:
    wikijs:
      url: "https://wiki-staging.company.com"
    logging:
      level: "INFO"

  development:
    wikijs:
      url: "http://localhost:3000"
    logging:
      level: "DEBUG"
```

**Code**:
```python
import os
from examples.config_helper import load_config, create_client_from_config

# Load config
config = load_config('config.yaml')

# Get environment
env = os.getenv('ENVIRONMENT', 'development')
env_config = config['environments'][env]

# Merge with base config
config.update(env_config)

# Create client
client = create_client_from_config(config)
```

### **Example 3: Override Configuration**

```python
from examples.config_helper import create_client_from_config

# Load from file but override specific values
client = create_client_from_config(
    'config.yaml',
    timeout=60.0,        # Override timeout
    rate_limit=20.0,     # Override rate limit
    log_level='DEBUG'    # Override log level
)
```

### **Example 4: Docker/Container Deployment**

**docker-compose.yml**:
```yaml
version: '3'
services:
  app:
    environment:
      - WIKIJS_URL=https://wiki.example.com
      - WIKIJS_API_KEY=${WIKIJS_API_KEY}
      - WIKIJS_TIMEOUT=30.0
      - WIKIJS_RATE_LIMIT=10.0
```

**Code** (loads from environment automatically):
```python
from examples.config_helper import create_client_from_config

client = create_client_from_config()  # Auto-loads from env vars
```

### **Example 5: Testing with Mock Config**

```python
# test_example.py
import pytest
from examples.config_helper import create_client_from_config

def test_client_creation():
    config = {
        'wikijs': {
            'url': 'http://test.example.com',
            'auth': {'api_key': 'test-key'}
        }
    }

    client = create_client_from_config(config)
    assert client.base_url == 'http://test.example.com'
```

---

## 🔒 Best Practices

### **1. Security**

#### ✅ **DO:**
- Store credentials in environment variables or secure vaults
- Use `.env` files for development (add to `.gitignore`)
- Rotate API keys regularly
- Use least-privilege API keys

#### ❌ **DON'T:**
- Hardcode credentials in source code
- Commit `.env` files to git
- Share API keys in public channels
- Use production keys in development

### **2. Configuration Management**

#### ✅ **DO:**
- Use different configs for each environment
- Version control config templates (`.example` files)
- Validate configuration on startup
- Document all configuration options

#### ❌ **DON'T:**
- Mix environments in the same config
- Leave sensitive data in example files
- Skip validation checks

### **3. File Structure**

Recommended project structure:

```
your-project/
├── .env                    # Local dev config (gitignored)
├── config.yaml.example     # Template (committed)
├── config/
│   ├── production.yaml     # Production config (no secrets)
│   ├── staging.yaml        # Staging config
│   └── development.yaml    # Dev config
├── src/
│   └── your_app.py
└── .gitignore             # Ignore .env and config with secrets
```

**.gitignore**:
```gitignore
.env
config.yaml
config.json
config.ini
*.local.yaml
*-secret.*
```

---

## 🔧 Troubleshooting

### **Issue: "No configuration file found"**

**Solution**: Create a config file from an example:
```bash
cp examples/config.env.example .env
# Edit .env with your settings
```

### **Issue: "WIKIJS_URL is required"**

**Solution**: Ensure URL is set in your config:
```bash
# .env file
WIKIJS_URL=https://wiki.example.com
```

### **Issue: "PyYAML is required"**

**Solution**: Install YAML support:
```bash
pip install pyyaml
```

### **Issue: "Authentication failed"**

**Solution**: Check your API key:
1. Log in to Wiki.js admin panel
2. Go to Administration → API Access
3. Create or copy an API key
4. Update your config with the correct key

### **Issue: SSL verification fails**

**Solution**: For self-signed certificates (development only):
```python
client = create_client_from_config(verify_ssl=False)
```

Or in `.env`:
```bash
WIKIJS_VERIFY_SSL=false
```

⚠️ **Never disable SSL verification in production!**

---

## 📚 Additional Resources

- **Config Examples**: See `examples/` directory for full examples
- **API Reference**: [docs/api_reference.md](api_reference.md)
- **User Guide**: [docs/user_guide.md](user_guide.md)
- **Security**: [docs/SECURITY.md](SECURITY.md)

---

## 🆘 Need Help?

- 📖 **Documentation**: Check [README.md](../README.md)
- 🐛 **Issues**: https://github.com/l3ocho/py-wikijs/issues
- 💬 **Discussions**: https://github.com/l3ocho/py-wikijs/discussions

---

**Last Updated**: 2025-10-25
**py-wikijs Version**: v0.1.0