feat: Add comprehensive configuration system and examples
Added complete configuration support with multiple formats and examples to help users easily configure py-wikijs for their projects. New Features: - Configuration file templates for ENV, YAML, JSON, and INI formats - config_helper.py: Universal configuration loader and client factory * Auto-detects and loads configs from multiple formats * Supports environment variables, YAML, JSON, and INI files * Provides create_client_from_config() for easy client creation * Validates configuration and provides helpful error messages Configuration Templates: - config.env.example: Environment variables (Docker, 12-factor apps) - config.yaml.example: YAML with multi-environment support - config.json.example: JSON for programmatic configuration - config.ini.example: INI for traditional setups Usage Examples: - using_env_config.py: Complete example using .env files - using_yaml_config.py: Complete example using YAML configuration - using_json_config.py: Complete example using JSON configuration Documentation: - docs/CONFIGURATION_GUIDE.md: Comprehensive configuration guide * All configuration methods explained * Security best practices * Environment-specific configurations * Troubleshooting guide Benefits: ✅ Flexible configuration (choose your preferred format) ✅ Keep credentials secure (no hardcoding) ✅ Environment-specific configs (dev/staging/prod) ✅ Docker/container-ready ✅ Full validation and error handling ✅ Comprehensive documentation and examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
545
docs/CONFIGURATION_GUIDE.md
Normal file
545
docs/CONFIGURATION_GUIDE.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user