Deploying django-wiki

Introduction

django-wiki is a wiki application built on the Django web framework that provides a clean, modern approach to collaborative documentation. Unlike standalone wiki software, django-wiki is designed to integrate seamlessly into existing Django projects or run as a standalone application, offering flexibility for both simple documentation needs and complex enterprise deployments.

Built with Django’s “batteries included” philosophy, django-wiki leverages the framework’s robust authentication, admin interface, and ORM while adding wiki-specific features like article versioning, hierarchical organization, and Markdown editing. The result is a wiki system that feels native to Django while providing all the features expected from modern wiki software.

Key highlights of django-wiki:

• Django Integration: Seamlessly integrates with existing Django projects or runs standalone
• Markdown Editing: Rich Markdown editor with preview and formatting toolbar
• Article Versioning: Complete revision history with diff viewing and rollback
• Hierarchical Structure: Organize articles in a tree structure with parent-child relationships
• Plugin System: Extend functionality with plugins for images, attachments, and more
• Flexible Permissions: Per-article permissions for read, write, and administrative access
• Full-Text Search: Built-in search across all wiki content
• Responsive Design: Works on desktop and mobile devices
• Notification System: Email notifications for article changes
• 100% Open Source: GPLv3 licensed with active development

This guide walks through deploying django-wiki on Klutch.sh, configuring your wiki environment, and setting up a collaborative documentation platform.

Why Deploy django-wiki on Klutch.sh

Deploying django-wiki on Klutch.sh provides several advantages for your documentation platform:

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on content creation rather than infrastructure.

Persistent Storage: Attach volumes for your database, media files, and static assets that persist across updates.

HTTPS by Default: Automatic SSL certificates ensure secure access to your wiki.

GitHub Integration: Connect your configuration repository for automated deployments.

Custom Domains: Use your own domain for a professional wiki URL.

Scalable Resources: Allocate CPU and memory based on your wiki usage and user count.

Always-On Availability: Your documentation remains accessible 24/7.

Prerequisites

Before deploying django-wiki on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Django and Python web applications
• A plan for organizing your documentation structure
• (Optional) A PostgreSQL database service for production use

Understanding django-wiki Architecture

django-wiki follows standard Django application patterns:

Django Backend: The core application handles URL routing, template rendering, and business logic using Django’s MTV pattern.

Database Layer: Article content, revisions, permissions, and user data are stored in a relational database (PostgreSQL recommended for production).

Media Storage: Uploaded images and attachments are stored in the media directory.

Static Files: CSS, JavaScript, and other static assets are served from the static directory.

Plugin System: Optional plugins extend functionality for specific use cases like image handling, attachments, and notifications.

Preparing Your Repository

Create a GitHub repository with your django-wiki configuration.

Repository Structure

django-wiki-deploy/
├── Dockerfile
├── requirements.txt
├── wiki_project/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for your django-wiki deployment:

FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libpq-dev \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy project files
COPY . .

# Create necessary directories
RUN mkdir -p /app/staticfiles /app/media

# Collect static files
RUN python manage.py collectstatic --noinput

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1

# Start gunicorn
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "3", "wiki_project.wsgi:application"]

Creating requirements.txt

Create requirements.txt with dependencies:

Django>=4.2,<5.0
wiki>=0.10
gunicorn>=21.0
psycopg2-binary>=2.9
whitenoise>=6.0
python-dotenv>=1.0
Pillow>=10.0
django-nyt>=1.2
sorl-thumbnail>=12.9

Creating Django Settings

Create wiki_project/settings.py:

import os
from pathlib import Path
from dotenv import load_dotenv

load_dotenv()

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = os.environ.get('SECRET_KEY', 'change-me-in-production')
DEBUG = os.environ.get('DEBUG', 'False').lower() == 'true'
ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '*').split(',')

INSTALLED_APPS = [
    'django.contrib.humanize.apps.HumanizeConfig',
    'django.contrib.auth.apps.AuthConfig',
    'django.contrib.contenttypes.apps.ContentTypesConfig',
    'django.contrib.sessions.apps.SessionsConfig',
    'django.contrib.sites.apps.SitesConfig',
    'django.contrib.messages.apps.MessagesConfig',
    'django.contrib.staticfiles.apps.StaticFilesConfig',
    'django.contrib.admin.apps.AdminConfig',
    'django_nyt.apps.DjangoNytConfig',
    'mptt',
    'sorl.thumbnail',
    'wiki.apps.WikiConfig',
    'wiki.plugins.attachments.apps.AttachmentsConfig',
    'wiki.plugins.notifications.apps.NotificationsConfig',
    'wiki.plugins.images.apps.ImagesConfig',
    'wiki.plugins.macros.apps.MacrosConfig',
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

ROOT_URLCONF = 'wiki_project.urls'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
                'sekizai.context_processors.sekizai',
            ],
        },
    },
]

WSGI_APPLICATION = 'wiki_project.wsgi.application'

# Database
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DATABASE_NAME', 'wiki'),
        'USER': os.environ.get('DATABASE_USER', 'wiki'),
        'PASSWORD': os.environ.get('DATABASE_PASSWORD', ''),
        'HOST': os.environ.get('DATABASE_HOST', 'localhost'),
        'PORT': os.environ.get('DATABASE_PORT', '5432'),
    }
}

# Password validation
AUTH_PASSWORD_VALIDATORS = [
    {'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator'},
    {'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator'},
    {'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator'},
    {'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator'},
]

# Internationalization
LANGUAGE_CODE = 'en-us'
TIME_ZONE = 'UTC'
USE_I18N = True
USE_TZ = True

# Static files
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

# Media files
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

# Default primary key field type
DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

# Site ID for django.contrib.sites
SITE_ID = 1

# Wiki settings
WIKI_ACCOUNT_HANDLING = True
WIKI_ACCOUNT_SIGNUP_ALLOWED = True
WIKI_ANONYMOUS = True
WIKI_ANONYMOUS_WRITE = False
WIKI_ANONYMOUS_UPLOAD = False

# Login settings
LOGIN_REDIRECT_URL = '/wiki/'
LOGOUT_REDIRECT_URL = '/wiki/'
LOGIN_URL = '/wiki/login/'

Creating URL Configuration

Create wiki_project/urls.py:

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static
from django.http import HttpResponse

def health_check(request):
    return HttpResponse("OK")

urlpatterns = [
    path('admin/', admin.site.urls),
    path('notifications/', include('django_nyt.urls')),
    path('wiki/', include('wiki.urls')),
    path('health/', health_check),
    path('', include('wiki.urls')),
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Creating WSGI Configuration

Create wiki_project/wsgi.py:

import os
from django.core.wsgi import get_wsgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'wiki_project.settings')
application = get_wsgi_application()

Creating manage.py

Create manage.py:

#!/usr/bin/env python
import os
import sys

if __name__ == '__main__':
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'wiki_project.settings')
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django."
        ) from exc
    execute_from_command_line(sys.argv)

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
.DS_Store
__pycache__/
*.pyc
.env
*.sqlite3

Deploying django-wiki on Klutch.sh

Follow these steps to deploy your django-wiki instance:

Set Up a PostgreSQL Database

django-wiki requires a database. Set up PostgreSQL through a managed service or deploy it separately.

Generate a Secret Key

Generate a secure Django secret key:

python -c "import secrets; print(secrets.token_urlsafe(50))"

Push Your Repository to GitHub

Initialize and push your configuration:

git init
git add .
git commit -m "Initial django-wiki configuration"
git remote add origin https://github.com/yourusername/django-wiki-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project for your wiki.

Create a New App

Create a new app within your project and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8000

Set Environment Variables

Configure the following environment variables:

Variable	Value
SECRET_KEY	Your generated secret key
DATABASE_NAME	wiki
DATABASE_USER	Your database username
DATABASE_PASSWORD	Your database password
DATABASE_HOST	Your database host
DATABASE_PORT	5432
ALLOWED_HOSTS	your-app.klutch.sh
DEBUG	False

Attach Persistent Volumes

Add persistent volumes for your wiki:

Mount Path	Recommended Size	Purpose
/app/media	10 GB	Uploaded images and attachments

Deploy Your Application

Click Deploy to build and start django-wiki.

Run Initial Migrations

After deployment, run database migrations. Access your app’s console or use a one-time command:

python manage.py migrate
python manage.py createsuperuser

Access Your Wiki

Navigate to https://your-app-name.klutch.sh to access your wiki.

Initial Setup and Configuration

Creating the Admin User

Create a superuser for administrative access:

python manage.py createsuperuser

Access the Django admin at /admin/ to manage users and settings.

Creating the Root Article

The first article serves as your wiki’s home page:

1. Navigate to your wiki URL
2. You’ll be prompted to create the root article
3. Enter a title and content
4. Save to create your wiki’s starting point

Organizing Content

django-wiki uses a hierarchical structure:

Root Article
├── Getting Started
│   ├── Installation
│   └── Configuration
├── User Guide
│   ├── Basic Usage
│   └── Advanced Features
└── Reference
    └── API Documentation

Create child articles by clicking “Add child article” on any article page.

Managing Articles

Creating Articles

Create new articles by:

1. Navigating to the parent article
2. Clicking “Add child article”
3. Entering the article slug, title, and content
4. Setting permissions as needed

Editing with Markdown

django-wiki uses Markdown for article content:

# Heading 1
## Heading 2

**Bold text** and *italic text*

- Bullet point
- Another point

1. Numbered list
2. Second item

[Link text](https://example.com)

![Image alt text](/media/images/example.png)

`inline code`

    code block

Article History

View and manage article revisions:

1. Click “History” on any article
2. View all previous versions with timestamps and authors
3. Compare versions using the diff view
4. Revert to a previous version if needed

Attachments and Images

Upload files to articles:

1. Edit the article
2. Use the attachment or image plugin
3. Upload your file
4. Insert into content using provided markup

Permission Management

Permission Levels

django-wiki supports granular permissions:

Permission	Description
Read	View the article
Write	Edit the article
Delete	Remove the article
Lock	Prevent others from editing
Recursive	Apply to child articles

Setting Permissions

Configure permissions per article:

1. Edit the article settings
2. Navigate to the Permissions tab
3. Add users or groups
4. Select permission levels
5. Enable recursive if needed

Group-Based Permissions

Create groups for team-based access:

1. Access Django admin
2. Create groups (e.g., “Editors”, “Viewers”)
3. Assign users to groups
4. Set article permissions by group

Plugins and Extensions

Built-in Plugins

django-wiki includes several plugins:

Images Plugin: Upload and embed images in articles

[image:123]  # Embed image by ID
[image:123 align:right size:medium]  # With options

Attachments Plugin: Attach files to articles

[attachment:456]  # Link to attachment

Notifications Plugin: Email notifications for article changes

Macros Plugin: Add dynamic content with macros

Configuring Plugins

Enable or configure plugins in settings:

# Enable specific plugins
INSTALLED_APPS = [
    # ... other apps ...
    'wiki.plugins.attachments.apps.AttachmentsConfig',
    'wiki.plugins.notifications.apps.NotificationsConfig',
    'wiki.plugins.images.apps.ImagesConfig',
    'wiki.plugins.macros.apps.MacrosConfig',
]

# Plugin-specific settings
WIKI_ATTACHMENTS_MAX_SIZE = 10 * 1024 * 1024  # 10MB

Production Best Practices

Performance Optimization

• Database Indexing: Ensure proper indexes on frequently queried fields
• Caching: Enable Django caching for improved performance
• Static Files: Use WhiteNoise or a CDN for static assets
• Thumbnail Caching: Configure sorl-thumbnail caching

Security Recommendations

• Strong Secret Key: Use a cryptographically random secret key
• HTTPS Only: Ensure all traffic uses HTTPS
• CSRF Protection: Keep Django’s CSRF middleware enabled
• Regular Updates: Keep Django and django-wiki updated

Backup Strategy

Regular backups should include:

1. PostgreSQL database dump
2. Media files directory
3. Custom configurations

Troubleshooting Common Issues

Database Migration Errors

Symptoms: Migrations fail or produce errors.

Solutions:

• Ensure database connection settings are correct
• Check database user has CREATE/ALTER permissions
• Review migration logs for specific errors
• Try running migrations manually

Static Files Not Loading

Symptoms: CSS and JavaScript not appearing.

Solutions:

• Verify collectstatic ran successfully
• Check STATIC_URL and STATIC_ROOT settings
• Ensure WhiteNoise is configured correctly
• Clear browser cache

Permission Denied Errors

Symptoms: Users cannot access or edit articles.

Solutions:

• Review article-level permissions
• Check user group memberships
• Verify anonymous access settings
• Review Django auth middleware

Image Upload Failures

Symptoms: Images fail to upload or display.

Solutions:

• Check media directory permissions
• Verify Pillow is installed
• Ensure sufficient disk space
• Review media URL configuration

Additional Resources

• django-wiki Documentation
• django-wiki GitHub Repository
• Django Documentation
• Markdown Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying django-wiki on Klutch.sh gives you a powerful, flexible wiki platform built on Django’s solid foundation. The combination of django-wiki’s rich editing features and Klutch.sh’s container management means you can create and maintain comprehensive documentation without infrastructure complexity.

With hierarchical organization, version control, flexible permissions, and plugin extensibility, django-wiki handles everything from simple team documentation to complex knowledge bases. Whether you’re documenting internal processes, creating public guides, or building a collaborative knowledge repository, django-wiki on Klutch.sh provides a reliable, accessible platform for all your documentation needs.