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
• Configuration Methods
• Configuration Options
• Examples
• Best Practices
• Troubleshooting

---

🚀 Quick Start

Simplest Method (Hardcoded)

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)

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

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):

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:

   cp examples/config.env.example .env
   

2. Edit .env with your settings:

   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:

   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:

pip install python-dotenv

---

Method 2: YAML Configuration

Best for: Complex configurations, multiple environments

Setup:

1. Copy the example file:

   cp examples/config.yaml.example config.yaml
   

2. Edit config.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:

   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:

pip install pyyaml

---

Method 3: JSON Configuration

Best for: Programmatic configuration, API-driven setups

Setup:

1. Copy the example file:

   cp examples/config.json.example config.json
   

2. Edit config.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:

   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:

   cp examples/config.ini.example config.ini
   

2. Edit config.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:

   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

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

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:

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:

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

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:

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):

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

# 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:

.env
config.yaml
config.json
config.ini
*.local.yaml
*-secret.*

---

🔧 Troubleshooting

Issue: "No configuration file found"

Solution: Create a config file from an example:

cp examples/config.env.example .env
# Edit .env with your settings

Issue: "WIKIJS_URL is required"

Solution: Ensure URL is set in your config:

# .env file
WIKIJS_URL=https://wiki.example.com

Issue: "PyYAML is required"

Solution: Install YAML support:

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):

client = create_client_from_config(verify_ssl=False)

Or in .env:

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
• User Guide: docs/user_guide.md
• Security: docs/SECURITY.md

---

🆘 Need Help?

• 📖 Documentation: Check 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