Skip to content
Klutch.sh Docs

Deploying Oddmuse

Introduction

Oddmuse is a minimalist wiki engine written in Perl that emphasizes simplicity and ease of use. Unlike complex wiki platforms, Oddmuse is a single CGI script that requires no database, making it incredibly easy to deploy and maintain.

Born from the philosophy that wikis should be simple tools for collaboration, Oddmuse uses flat files for storage and offers a clean, readable interface. Despite its simplicity, it includes powerful features like version control, recent changes tracking, and extensibility through modules.

Key highlights of Oddmuse:

  • Single Script: Entire wiki in one Perl script
  • No Database: File-based storage for simplicity
  • Version Control: Built-in page history and diffs
  • Extensibility: Module system for additional features
  • WikiCreole Support: Standard wiki markup
  • Markdown Support: Optional Markdown formatting
  • File Uploads: Support for images and attachments
  • Full-Text Search: Search across all pages
  • Recent Changes: Track wiki activity
  • RSS Feeds: Subscribe to updates
  • Multi-Language: Interface in multiple languages
  • Open Source: GPL license with active maintenance

This guide walks through deploying Oddmuse on Klutch.sh using Docker.

Why Deploy Oddmuse on Klutch.sh

Deploying Oddmuse on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the CGI/Perl deployment automatically.

Persistent Storage: Attach persistent volumes for wiki data.

HTTPS by Default: Automatic SSL certificates for secure access.

GitHub Integration: Version-controlled deployments through your repository.

Lightweight: Minimal resource requirements.

Custom Domains: Use your own domain for your wiki.

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

Prerequisites

Before deploying Oddmuse on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic understanding of wiki concepts
  • (Optional) A custom domain for your Oddmuse instance

Understanding Oddmuse Architecture

Oddmuse has an elegantly simple architecture:

CGI Script: Single Perl script handling all requests.

Data Directory: Flat files storing pages and metadata.

Page Files: Each page stored as a separate file.

Keep Files: Version history stored as diffs.

Modules: Optional Perl modules for extensions.

Deploying Oddmuse on Klutch.sh

    Create Your GitHub Repository

    Create a new GitHub repository for your Oddmuse deployment configuration.

    Create the Dockerfile

    Create a Dockerfile in your repository root:

    FROM perl:5.36-slim
    

    # Install dependencies
    RUN apt-get update && apt-get install -y \
        apache2 \
        libcgi-pm-perl \
        curl \
        && rm -rf /var/lib/apt/lists/*
    

    # Enable CGI module
    RUN a2enmod cgid
    

    # Download Oddmuse
    WORKDIR /var/www/cgi-bin
    RUN curl -L https://oddmuse.org/releases/oddmuse-2.3.7.tar.gz | tar xz
    RUN mv oddmuse-* oddmuse && \
        cp oddmuse/wiki.pl . && \
        chmod +x wiki.pl
    

    # Create data directory
    RUN mkdir -p /var/oddmuse && \
        chown -R www-data:www-data /var/oddmuse
    

    # Configure Apache
    RUN echo '<VirtualHost *:80>\n\
        DocumentRoot /var/www/html\n\
        ScriptAlias /wiki /var/www/cgi-bin/wiki.pl\n\
        <Directory /var/www/cgi-bin>\n\
            Options +ExecCGI\n\
            AddHandler cgi-script .pl\n\
        </Directory>\n\
    </VirtualHost>' > /etc/apache2/sites-available/000-default.conf
    

    # Configure Oddmuse
    RUN echo '\
    $DataDir = "/var/oddmuse";\n\
    $SiteName = "My Wiki";\n\
    $WikiDescription = "A simple wiki powered by Oddmuse";\n\
    ' > /var/www/cgi-bin/config
    

    EXPOSE 80
    

    CMD ["apachectl", "-D", "FOREGROUND"]

    Create a New Project on Klutch.sh

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

    Create a New App

    Within your project, create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    In the deployment settings:

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

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /var/oddmuse10 GBWiki pages and data

    Deploy Your Application

    Click Deploy to start the build process.

    Access Your Wiki

    Once deployed, access your wiki at https://your-app.klutch.sh/wiki.

Initial Configuration

Basic Configuration

Create a configuration file:

/var/www/cgi-bin/config
# Site settings
$SiteName = "My Wiki";
$WikiDescription = "Documentation and Knowledge Base";


# Data directory
$DataDir = "/var/oddmuse";


# Allow editing (remove for read-only)
$EditAllowed = 1;


# Admin password (change this!)
$AdminPass = "your-secure-password";


# Time zone
$TZ = "America/New_York";

Password Protection

Require passwords for editing:

# Require password for editing
$EditPass = "edit-password";


# Admin password for maintenance
$AdminPass = "admin-password";

Custom Styling

Add custom CSS:

$StyleSheet = "/wiki-style.css";

Using Oddmuse

Creating Pages

Create and edit pages:

  1. Navigate to a page name (e.g., /wiki/NewPage)
  2. Click “Edit this page”
  3. Write content using wiki markup
  4. Save the page

Wiki Markup

Format content with wiki markup:

= Heading 1 =
== Heading 2 ==
=== Heading 3 ===


**bold text**
''italic text''


* Bullet list
** Nested item


# Numbered list
## Nested number


[[PageName]] - internal link
[[PageName|Display Text]]
[http://example.com External Link]

Page History

View page history:

  1. Click “History” on any page
  2. View all revisions
  3. Compare differences
  4. Rollback if needed

Recent Changes

Track wiki activity:

  1. Click “RecentChanges”
  2. View all recent edits
  3. See who made changes
  4. Subscribe via RSS

Extending Oddmuse

Installing Modules

Add functionality with modules:

# In config file
$ModuleDir = "/var/oddmuse/modules";

Download modules to the modules directory:

  1. Markdown support
  2. Table of contents
  3. Syntax highlighting
  4. Image galleries

Enhance your wiki:

  • Markdown: Write in Markdown syntax
  • TOC: Automatic table of contents
  • Creole: WikiCreole markup support
  • Calendar: Calendar functionality
  • Blog: Blogging features

Security Configuration

Read-Only Mode

Make wiki read-only:

$EditAllowed = 0;

IP Banning

Block problematic IPs:

@BannedHosts = ('192.168.1.100', '10.0.0.*');

CAPTCHA

Enable spam protection:

# Use Question CAPTCHA module
require "$ModuleDir/question-asker.pl";

Production Best Practices

Backup Strategy

Protect your wiki data:

  1. Regular Backups: Back up /var/oddmuse directory
  2. Version Control: Keep pages in git (optional)
  3. Off-site Copies: Store backups externally

Performance

Optimize for larger wikis:

  1. Enable caching
  2. Use keep-months setting
  3. Regular maintenance

Security Recommendations

  • Change default passwords
  • Enable HTTPS (automatic on Klutch.sh)
  • Regular updates
  • Monitor for spam

Troubleshooting Common Issues

Pages Not Saving

  • Check file permissions
  • Verify data directory exists
  • Review error logs
  • Check disk space

500 Errors

  • Check Perl syntax
  • Verify CGI configuration
  • Review Apache error logs
  • Check module compatibility

Search Not Working

  • Verify data directory path
  • Check file permissions
  • Ensure pages exist

Additional Resources

Conclusion

Deploying Oddmuse on Klutch.sh provides a lightweight, maintainable wiki solution that proves simplicity can be powerful. With its single-script design and file-based storage, Oddmuse offers an alternative to database-heavy wiki systems while still providing essential collaboration features. Perfect for documentation, knowledge bases, or any collaborative writing project.