Skip to content
Klutch.sh Docs

Deploying Otter Wiki

Introduction

Otter Wiki is a simple, beautiful wiki application that stores all content in Markdown files backed by Git. Written in Python with Flask, Otter Wiki provides an intuitive editing experience while leveraging Git’s powerful version control for complete page history, branching, and collaboration.

Unlike database-backed wikis, Otter Wiki stores pages as plain Markdown files in a Git repository. This approach makes content portable, version-controlled, and easily backed up. You can edit pages through the web interface or directly in the Git repository, making it perfect for developers who want to integrate documentation workflows with their existing Git-based processes.

Key highlights of Otter Wiki:

  • Git-Backed Storage: All pages stored as Markdown files with full version history
  • Beautiful Interface: Clean, responsive design that works on all devices
  • Markdown Support: Full Markdown with syntax highlighting and tables
  • Full-Text Search: Fast search across all wiki content
  • File Attachments: Upload and embed images and other files
  • Page History: View diffs and revert to previous versions
  • Authentication: Optional user accounts with different permission levels
  • No Database Required: Everything stored in files and Git
  • Easy Backup: Clone the Git repository to back up everything
  • Lightweight: Minimal resource requirements

This guide walks through deploying Otter Wiki on Klutch.sh using Docker, configuring user access, and setting up your wiki for production use.

Why Deploy Otter Wiki on Klutch.sh

Deploying Otter Wiki on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys your wiki. Push to GitHub, and your wiki deploys without manual intervention.

Persistent Storage: Attach persistent volumes for your Git repository and uploads. Your wiki content survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure wiki access.

GitHub Integration: Store configuration in Git for version-controlled infrastructure.

Always-On Availability: Your wiki runs 24/7, providing constant access to documentation.

Custom Domains: Use your organization’s domain for professional wiki URLs.

Lightweight: Otter Wiki’s minimal requirements mean efficient resource usage.

Prerequisites

Before deploying Otter Wiki on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Otter Wiki configuration
  • Basic familiarity with Docker and containerization concepts
  • (Optional) Existing Git repository with Markdown content

Understanding Otter Wiki Architecture

Otter Wiki has a simple architecture:

Flask Application: Python-based web application handling HTTP requests and page rendering.

Git Repository: Stores all wiki pages as Markdown files with full version history.

File Storage: Attachments and uploads stored alongside wiki content.

SQLite Database: Optional, stores user accounts and sessions when authentication is enabled.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

otter-wiki-deploy/
├── Dockerfile
├── config.py
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile for Otter Wiki:

FROM redimp/otterwiki:latest


# Create directories for persistent data
RUN mkdir -p /app-data/repository
RUN mkdir -p /app-data/uploads


# Environment configuration
ENV OTTERWIKI_SETTINGS=/app-data/config.py


# Expose the application port
EXPOSE 8080


# Use default entrypoint

Configuration File

Create a config.py for customization:

# Site configuration
SITE_NAME = "My Wiki"
SITE_DESCRIPTION = "Documentation and knowledge base"


# Repository path
REPOSITORY = "/app-data/repository"


# Upload directory
UPLOAD_FOLDER = "/app-data/uploads"


# Security
SECRET_KEY = "change-this-to-a-random-secret-key"


# Authentication (optional)
# Set to True to require login for editing
READ_ACCESS = "anonymous"
WRITE_ACCESS = "registered"


# Enable user registration
REGISTRATION = True

Environment Variables Reference

VariableDefaultDescription
OTTERWIKI_SETTINGS-Path to configuration file
SECRET_KEY-Flask secret key for sessions
SITE_NAMEOtter WikiDisplay name for the wiki
READ_ACCESSanonymousWho can read (anonymous, registered)
WRITE_ACCESSregisteredWho can edit (anonymous, registered, admin)
REGISTRATIONTrueAllow new user registration

Deploying Otter Wiki on Klutch.sh

Follow these steps to deploy your wiki:

    Generate a Secret Key

    Generate a secure secret key:

    Terminal window
    python -c "import secrets; print(secrets.token_hex(32))"

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile config.py .dockerignore README.md
    git commit -m "Initial Otter Wiki configuration"
    git remote add origin https://github.com/yourusername/otter-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 named “otter-wiki” or “wiki”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    Configure your wiki instance:

    VariableValue
    SECRET_KEYYour generated secret key
    OTTERWIKI_SETTINGS/app-data/config.py

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /app-data/repository10 GBGit repository with wiki pages
    /app-data/uploads10 GBUploaded files and images

    Deploy Your Application

    Click Deploy to start the build process.

    Access Otter Wiki

    Once deployment completes, access your wiki at https://your-app-name.klutch.sh. Create your first page to get started.

Initial Setup

Creating the First Page

On first access:

  1. Navigate to your wiki URL
  2. Click “Edit” or create a new page
  3. Write content in Markdown
  4. Click “Save” to commit to Git

Setting Up Authentication

If you enabled authentication:

  1. Click “Register” to create an admin account
  2. The first user typically gets admin privileges
  3. Configure additional users as needed

Importing Existing Content

If you have existing Markdown files:

  1. Clone your wiki repository locally
  2. Add Markdown files to the repository
  3. Push changes to update the wiki

Writing Wiki Content

Markdown Syntax

Otter Wiki supports standard Markdown:

# Heading 1
## Heading 2


**Bold** and *italic* text


- Bullet list
- Another item


1. Numbered list
2. Second item


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


![Image alt](image.png)


`inline code`


​```python
def hello():
    print("Hello, World!")
​```

Creating Pages

Create new pages by:

  1. Clicking “New Page” in the interface
  2. Entering the page name
  3. Writing content in Markdown
  4. Saving the page

Or link to non-existent pages:

Check out the [[NewPage]] for more info.

Clicking the link creates the new page.

Organizing Content

Structure your wiki with:

  • Subpages: Use paths like topic/subtopic
  • Categories: Group related pages together
  • Navigation: Create index pages with links

File Attachments

Upload and embed files:

  1. Click the attachment button while editing
  2. Upload your file
  3. Insert the reference in your page
![Screenshot](uploads/screenshot.png)
[Download PDF](uploads/document.pdf)

Version Control Features

Viewing History

See page history:

  1. Open any page
  2. Click “History”
  3. View list of revisions with dates and authors
  4. Click any revision to view its content

Comparing Versions

See what changed:

  1. Open page history
  2. Select two revisions
  3. View the diff showing additions and deletions

Reverting Changes

Restore previous versions:

  1. Open page history
  2. Find the version to restore
  3. Click “Revert to this version”
  4. Confirm the revert

Git Repository Access

Access the underlying Git repository:

Terminal window
# Clone the wiki repository
git clone https://your-wiki-url/git/repository.git


# Make changes locally
cd repository
echo "# New Page" > new-page.md
git add new-page.md
git commit -m "Add new page"
git push

User Management

User Roles

Otter Wiki supports different access levels:

  • Anonymous: Public access without login
  • Registered: Authenticated users
  • Admin: Full administrative access

Access Configuration

Configure in config.py:

# Public read, registered write
READ_ACCESS = "anonymous"
WRITE_ACCESS = "registered"


# Fully private wiki
READ_ACCESS = "registered"
WRITE_ACCESS = "registered"


# Public read and write
READ_ACCESS = "anonymous"
WRITE_ACCESS = "anonymous"

User Registration

Control registration:

# Allow registration
REGISTRATION = True


# Disable registration (admin creates accounts)
REGISTRATION = False

Customization

Site Branding

Customize the wiki appearance:

SITE_NAME = "Company Wiki"
SITE_DESCRIPTION = "Internal documentation and knowledge base"
SITE_ICON = "/static/custom/logo.png"

Custom CSS

Add custom styles:

  1. Create a custom CSS file
  2. Mount it in the container
  3. Reference in configuration

Create a sidebar or navigation page:

  1. Create a special navigation page
  2. Add links to important sections
  3. Configure as the default sidebar

Backup and Sync

Backing Up

The wiki repository contains everything:

Terminal window
# Clone for backup
git clone https://your-wiki-url/git/repository.git wiki-backup


# Or if you have volume access
cp -r /app-data/repository /backup/

Syncing with External Git

Sync wiki content with GitHub:

  1. Configure remote repository
  2. Set up push/pull hooks
  3. Changes sync automatically

Disaster Recovery

To restore from backup:

  1. Stop the wiki container
  2. Replace the repository directory with backup
  3. Restart the container

Troubleshooting Common Issues

Pages Not Saving

Symptoms: Edits fail or are lost.

Solutions:

  • Check Git repository permissions
  • Verify disk space on volume
  • Review application logs for Git errors
  • Ensure repository is properly initialized

Search Not Working

Symptoms: Search returns no results.

Solutions:

  • Verify search index is built
  • Rebuild the search index
  • Check content encoding is UTF-8

Authentication Issues

Symptoms: Cannot log in or register.

Solutions:

  • Verify SECRET_KEY is set
  • Check authentication configuration
  • Clear browser cookies
  • Review session storage

Images Not Loading

Symptoms: Uploaded images display as broken.

Solutions:

  • Check upload directory permissions
  • Verify upload volume is mounted
  • Check file path references
  • Review allowed file types

Additional Resources

Conclusion

Deploying Otter Wiki on Klutch.sh provides a simple, elegant wiki solution with Git-powered version control. With Markdown editing, full-text search, and complete page history, Otter Wiki delivers documentation capabilities without the complexity of database-backed alternatives.

The combination of persistent storage for your Git repository, reliable uptime, and HTTPS security makes Klutch.sh an excellent platform for hosting Otter Wiki. Whether documenting a project, creating a knowledge base, or sharing notes with a team, your self-hosted wiki provides the simplicity and control you need.

Start documenting today with the confidence that every change is tracked and your content is always under your control.