Deploying Gitit

Introduction

Gitit is a wiki program written in Haskell that uses Git (or Darcs, or Mercurial) as a backend for version control. Pages and uploaded files are stored in a repository and can be modified either through the wiki’s web interface or by using the version control system’s command-line tools.

Built on the powerful Pandoc library, Gitit supports multiple markup formats including Markdown, reStructuredText, LaTeX, and MediaWiki syntax. Every change is automatically committed to the repository, providing complete revision history and the ability to revert changes.

Key highlights of Gitit:

• Git Backend: Full version control for all wiki content
• Multiple Markup Formats: Markdown, RST, LaTeX, MediaWiki, and more
• Pandoc Integration: Powerful document conversion capabilities
• Math Support: Render LaTeX math equations
• File Uploads: Upload and manage files through the web interface
• Full-Text Search: Search across all wiki pages
• User Authentication: Optional user accounts and access control
• Categories: Organize pages with categories
• Page History: View and compare revisions
• Export Options: Export pages to various formats (PDF, EPUB, etc.)
• Open Source: Licensed under GPL

This guide walks through deploying Gitit on Klutch.sh using Docker, configuring the wiki, and managing content.

Why Deploy Gitit on Klutch.sh

Deploying Gitit on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gitit. Push to GitHub, and your wiki deploys automatically.

Persistent Storage: Attach persistent volumes for your wiki repository. Content and history survive container restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub for automatic updates.

Custom Domains: Assign a custom domain for your wiki.

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

Git Portability: Clone and backup your wiki using standard Git tools.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Gitit configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your wiki

Understanding Gitit Architecture

Gitit uses a straightforward architecture:

Haskell Backend: The wiki server is written in Haskell using the Happstack web framework.

Git Repository: All wiki content is stored in a Git repository, providing version control.

Pandoc: Document conversion and rendering handled by the Pandoc library.

Static Files: Templates, CSS, and JavaScript for the web interface.

Configuration File: YAML or command-line configuration for server settings.

Preparing Your Repository

To deploy Gitit on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

gitit-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM hyzual/gitit:latest

# Set working directory
WORKDIR /data

# Create wiki directories
RUN mkdir -p /data/wikidata /data/static /data/templates

# Expose the web interface port
EXPOSE 5001

# Start Gitit
CMD ["gitit", "-f", "gitit.conf"]

Alternative Dockerfile with Configuration

For more customization:

FROM hyzual/gitit:latest

WORKDIR /data

# Create directories
RUN mkdir -p /data/wikidata /data/static /data/templates

# Create default configuration
RUN echo 'port: 5001' > /data/gitit.conf && \
    echo 'wiki-title: My Wiki' >> /data/gitit.conf && \
    echo 'repository-type: Git' >> /data/gitit.conf && \
    echo 'repository-path: wikidata' >> /data/gitit.conf && \
    echo 'require-authentication: modify' >> /data/gitit.conf && \
    echo 'authentication-method: form' >> /data/gitit.conf

# Initialize Git repository
RUN cd /data/wikidata && git init

EXPOSE 5001

CMD ["gitit", "-f", "/data/gitit.conf"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Deploying Gitit on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gitit:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Gitit deployment configuration"
git remote add origin https://github.com/yourusername/gitit-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. Give it a descriptive name like “gitit” or “wiki”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gitit Dockerfile.

Configure HTTP Traffic

Gitit serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 5001 (Gitit’s default port)

Attach Persistent Volumes

Persistent storage preserves your wiki content:

Mount Path	Recommended Size	Purpose
/data	5 GB	Wiki repository, templates, and configuration

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Gitit container
• Provision an HTTPS certificate

Access Gitit

Once deployment completes, access your Gitit wiki at https://your-app-name.klutch.sh. You’ll see the front page ready for editing.

Initial Configuration

Configuration Options

Create or modify gitit.conf:

# Basic settings
port: 5001
wiki-title: My Wiki
repository-type: Git
repository-path: wikidata

# Authentication
require-authentication: modify
authentication-method: form

# Access control
access-question: What is 2+2?
access-question-answers: 4, four, Four

# Appearance
default-page-type: markdown
math: mathjax
use-cache: yes

# File uploads
max-upload-size: 10M
max-page-size: 1M

Authentication Modes

Configure access control:

Mode	Description
none	No authentication required
modify	Authentication required for editing
read	Authentication required for reading

Registration

Enable user registration:

use-recaptcha: no
recaptcha-public-key:
recaptcha-private-key:

Creating Content

Creating Pages

Create a new page:

1. Navigate to a non-existent page URL (e.g., /NewPage)
2. Click “Create this page”
3. Enter content in Markdown
4. Save to commit

Markdown Syntax

Gitit supports extended 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 text](/images/photo.jpg)

`inline code`

    code block
    indented

> Blockquote

| Table | Header |
|-------|--------|
| Cell  | Cell   |

Math Equations

Insert LaTeX math:

Inline: $E = mc^2$

Display:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Internal Links

Link between wiki pages:

[Home](/)
[Another Page](/AnotherPage)
[Section](/Page#section)

File Management

Uploading Files

1. Navigate to Upload file in the tools menu
2. Select a file
3. Upload and get the path
4. Reference in pages: ![](/uploaded/filename.jpg)

File Organization

Organize uploads:

/uploaded/
├── images/
│   ├── logo.png
│   └── photo.jpg
├── documents/
│   └── report.pdf
└── attachments/

Categories

Adding Categories

Add categories to pages:

---
categories: Documentation, Tutorials
---

# Page Content

Your content here...

Viewing Categories

• Browse /categories for all categories
• Click a category to see all pages

Revision History

Viewing History

1. Click History on any page
2. View all revisions
3. Compare versions
4. Revert if needed

Reverting Changes

1. View the history
2. Select a previous version
3. Create a new revision with old content

Exporting Content

Export Formats

Gitit supports multiple export formats via Pandoc:

Format	URL suffix
PDF	?format=pdf
EPUB	?format=epub
DocX	?format=docx
ODT	?format=odt
Plain Text	?format=plain

Backup via Git

Clone your entire wiki:

git clone your-server:/data/wikidata wiki-backup

Customization

Templates

Customize templates in /data/templates/:

• page.st - Page layout
• footer.st - Footer content
• sidebar.st - Sidebar content

CSS Styling

Add custom CSS in /data/static/css/custom.css:

body {
  font-family: Georgia, serif;
}

.page {
  max-width: 800px;
  margin: 0 auto;
}

Production Best Practices

Security Recommendations

• Enable Authentication: Require login for modifications
• Access Questions: Add verification for registration
• HTTPS: Always use HTTPS (provided by Klutch.sh)
• Regular Backups: Clone repository regularly

Backup Strategy

Protect your wiki content:

1. Git Clone: Clone repository for backup
2. Scheduled Backups: Automate with cron
3. Off-site Storage: Store backups remotely

Performance Tips

• Enable caching in configuration
• Optimize images before upload
• Use appropriate page sizes

Troubleshooting Common Issues

Pages Not Saving

Solutions:

• Check Git repository permissions
• Verify disk space
• Review Gitit logs

Formatting Issues

Solutions:

• Verify Markdown syntax
• Check Pandoc compatibility
• Review page metadata

Authentication Problems

Solutions:

• Check configuration file
• Verify user database
• Clear browser cookies

Additional Resources

• Gitit GitHub Repository
• Pandoc Documentation
• Gitit Docker Hub
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Gitit on Klutch.sh gives you a powerful, version-controlled wiki with automatic builds and secure HTTPS access. The combination of Gitit’s Git backend and Klutch.sh’s deployment simplicity means you can focus on content rather than infrastructure.

With support for multiple markup formats, math rendering, and complete revision history, Gitit provides everything you need for collaborative documentation. Whether you’re building a personal knowledge base or team documentation, Gitit on Klutch.sh delivers reliable wiki functionality with the power of Git version control.