Deploying Feather Wiki

Introduction

Feather Wiki is an incredibly lightweight, self-contained wiki application that challenges everything you thought you knew about web applications. At under 50KB in size, Feather Wiki delivers a complete wiki experience in a single HTML file—no database, no complex installation, no dependencies. Just pure, efficient knowledge management.

Unlike traditional wikis that require servers, databases, and complicated setups, Feather Wiki uses a revolutionary approach: everything—the application code, your content, settings, and even uploaded images—lives in one portable HTML file. You can save it, back it up with a simple file copy, version it with Git, or share it via email. It’s wiki software that fits on a floppy disk yet delivers modern functionality.

Key Features

Single File Architecture - Entire wiki (app + content) in one HTML file under 50KB
No Database Required - All content stored directly in the HTML file
Zero Dependencies - No external libraries, frameworks, or build tools needed
Instant Backup - Copy the file to create a complete backup
Version Control Friendly - Track changes with Git like any other file
Portable - Run locally in a browser or host on any web server
Markdown Support - Write content in familiar Markdown syntax
Custom Styling - Built-in themes and custom CSS support
Image Embedding - Base64-encoded images stored in the file itself
Full-Text Search - Fast client-side search across all pages
Page Linking - Wiki-style internal page links
Export/Import - Easy content migration and sharing
Offline Capable - Works completely offline after initial load
Password Protection - Optional password-based access control
Mobile Responsive - Clean interface on any device
Open Source - AGPLv3 licensed with active development

Why Deploy Feather Wiki on Klutch.sh?

While Feather Wiki can run anywhere, deploying it on Klutch.sh provides significant advantages:

Always Available - Access your wiki from anywhere with an internet connection
Automatic HTTPS - Secure access with built-in SSL certificates
Team Collaboration - Share a single wiki instance with your team
Persistent Storage - Automatic backups through persistent volumes
Custom Domains - Professional access at your own domain
Version History - Combined with Git, track every change to your wiki
Fast Deployment - Running in production in under 5 minutes
No Maintenance - No database updates, no security patches for complex systems
Cost Effective - Minimal resource requirements mean low hosting costs
Scalable Serving - Handle traffic spikes without performance degradation

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Feather Wiki project
Basic understanding of Docker and HTML
Optional: Familiarity with Markdown for content creation

Understanding Feather Wiki Architecture

Feather Wiki’s unique architecture deserves explanation before deployment:

Single File Storage: Everything lives in one HTML file. When you edit content, the JavaScript application modifies the HTML file’s data structures and saves it back. No external database, no configuration files.

Client-Side Processing: All wiki operations happen in the browser. The server simply delivers the HTML file; JavaScript handles rendering, editing, searching, and saving.

Persistence Strategy: For deployment, we’ll serve Feather Wiki through Nginx and use persistent volumes to maintain the HTML file across container restarts. This gives you the simplicity of Feather Wiki with the reliability of cloud hosting.

Preparing Your Repository

Create a new directory for your Feather Wiki deployment:

mkdir feather-wiki-deployment
cd feather-wiki-deployment

Downloading Feather Wiki

Download the latest Feather Wiki HTML file:

# Download the latest release
curl -L -o featherwiki.html https://feather.wiki/featherwiki.html

# Or download a specific version
# curl -L -o featherwiki.html https://codeberg.org/Alamantus/FeatherWiki/releases/download/v1.7.0/featherwiki.html

Alternatively, create your own customized version by visiting feather.wiki and downloading the customized file.

Creating the Dockerfile

Create a Dockerfile that serves Feather Wiki through Nginx:

# Use Nginx Alpine for minimal footprint
FROM nginx:alpine

# Remove default Nginx configuration
RUN rm -rf /usr/share/nginx/html/*

# Copy Feather Wiki HTML file
COPY featherwiki.html /usr/share/nginx/html/index.html

# Create directory for persistent wiki data
RUN mkdir -p /usr/share/nginx/html/data

# Copy custom Nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf

# Set proper permissions
RUN chown -R nginx:nginx /usr/share/nginx/html

# Expose port 80
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1

# Start Nginx
CMD ["nginx", "-g", "daemon off;"]

Creating Nginx Configuration

Create nginx.conf for optimized Feather Wiki serving:

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # Logging
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/html text/css text/javascript application/javascript;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;

    # Cache control for HTML (no cache to always get latest)
    location / {
        try_files $uri $uri/ /index.html;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
        add_header Pragma "no-cache";
        add_header Expires "0";
    }

    # Cache static assets (if you add any)
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Error pages
    error_page 404 /index.html;
    error_page 500 502 503 504 /index.html;
}

Alternative: Advanced Setup with Auto-Save

For automatic persistence of wiki changes, create a more advanced setup:

Create entrypoint.sh:

#!/bin/sh

# Create data directory if it doesn't exist
mkdir -p /data

# Copy default wiki if no saved version exists
if [ ! -f /data/featherwiki.html ]; then
    echo "Initializing new Feather Wiki..."
    cp /usr/share/nginx/html/index.html /data/featherwiki.html
fi

# Link the persistent wiki to the web root
ln -sf /data/featherwiki.html /usr/share/nginx/html/index.html

# Start Nginx
exec nginx -g "daemon off;"

Update your Dockerfile for the advanced setup:

FROM nginx:alpine

# Install required tools
RUN apk add --no-cache bash

# Remove default Nginx content
RUN rm -rf /usr/share/nginx/html/*

# Copy Feather Wiki
COPY featherwiki.html /usr/share/nginx/html/featherwiki.html

# Copy Nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf

# Copy entrypoint script
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

# Expose port
EXPOSE 80

# Use custom entrypoint
ENTRYPOINT ["/entrypoint.sh"]

Creating a README

Create README.md with usage instructions:

# Feather Wiki Deployment

This repository contains the deployment configuration for Feather Wiki on Klutch.sh.

## Local Development

```bash
# Build the Docker image
docker build -t feather-wiki .

# Run locally
docker run -d -p 8080:80 -v $(pwd)/data:/data feather-wiki

# Access at http://localhost:8080

Deployment

Deploy to Klutch.sh by connecting this repository. The platform will automatically detect the Dockerfile and deploy your wiki.

Backing Up

With persistent volumes attached, your wiki content is automatically preserved. For additional safety:

# Download your wiki file from the container
docker cp <container-id>:/data/featherwiki.html ./backup-$(date +%Y%m%d).html

Customization

Edit featherwiki.html locally, commit changes, and redeploy to update your wiki’s appearance or initial content.

### Initialize Git Repository

Set up version control:

```bash
git init
git add Dockerfile nginx.conf featherwiki.html entrypoint.sh README.md
git commit -m "Initial Feather Wiki deployment setup"
git branch -M main
git remote add origin https://github.com/yourusername/feather-wiki-deployment.git
git push -u origin main

Deploying on Klutch.sh

Navigate to Klutch.sh Dashboard

Go to klutch.sh/app and sign in.
Create a New Project

Click “New Project” and name it something like knowledge-base or team-wiki.
Create a New App

Inside your project, click “New App” and select your GitHub repository containing the Feather Wiki configuration.
Configure Build Settings

Klutch.sh will automatically detect your Dockerfile. No additional build configuration is needed.
Configure Traffic Settings

Set the traffic type to HTTP and specify the internal port as 80 (Nginx’s default port).
Attach Persistent Volume (Recommended)

To preserve your wiki content across deployments:
- Click “Add Volume”
- Set mount path: /data
- Set size: 1GB (Feather Wiki is tiny; this is more than enough)
This ensures your wiki content persists even when the container restarts.
Deploy the Application

Click “Deploy” to start the deployment. Klutch.sh will build your Docker image and launch Feather Wiki.
Access Your Wiki

Once deployed, your Feather Wiki will be accessible at https://your-app-name.klutch.sh.

Initial Setup and Configuration

First Access

When you first open your Feather Wiki:

Click the **menu icon** (☰) in the top-right corner
Select **"Settings"** to configure your wiki
Set your wiki name, description, and other preferences
Choose a theme or customize CSS for your preferred appearance

Setting a Password

To protect your wiki with a password:

Open the menu (☰) and go to **"Settings"**
Scroll to the **"Password"** section
Enter a strong password
Click **"Set Password"**

Important: Password protection in Feather Wiki is basic authentication. For sensitive content, combine it with additional security measures at the infrastructure level.

Creating Your First Page

Click the **"+ New Page"** button
Enter a page title (e.g., "Home" or "Getting Started")
Write content using Markdown syntax
Click **"Save"** to create the page

Content Management

Markdown Syntax Guide

Feather Wiki supports standard Markdown:

# Heading 1
## Heading 2
### Heading 3

**Bold text** and *italic text*

- Bullet list item
- Another item
  - Nested item

1. Numbered list
2. Second item

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

[[Internal Page Link]]

![Image description](https://example.com/image.jpg)

`Inline code` and code blocks:

Code block content

> Blockquote text

---

Horizontal rule

Linking Between Pages

Create wiki-style links to other pages:

[[Page Title]]  <!-- Links to a page named "Page Title" -->
[[Custom Text|Page Title]]  <!-- Custom link text -->

Embedding Images

Feather Wiki stores images as base64-encoded data in the HTML file:

Click the **image icon** in the editor toolbar
Upload an image file (JPG, PNG, GIF)
The image is automatically embedded in your page

Note: Since images are embedded in the HTML file, keep individual images under 1MB for best performance. The entire wiki file grows with each embedded image.

Organizing Content

Categories and Tags: While Feather Wiki doesn’t have built-in categories, you can organize content through:

Creating index pages with links to related content
Using consistent heading structures
Naming pages with prefixes (e.g., “Project-Overview”, “Project-Tasks”)

Navigation Structure:

# Main Index

## Documentation
- [[Getting Started]]
- [[User Guide]]
- [[API Reference]]

## Projects
- [[Project Alpha]]
- [[Project Beta]]

## Resources
- [[Links]]
- [[FAQs]]

Search Functionality

Feather Wiki includes built-in full-text search:

Click the **search icon** (🔍) in the menu
Type your search query
Results appear instantly as you type
Click a result to navigate to that page

Customization

Changing Themes

Feather Wiki includes several built-in themes:

Open **Settings** from the menu
Go to the **"Appearance"** section
Select from available themes: - **Light** (default) - **Dark** - **Sepia** - **High Contrast**
Changes apply immediately

Custom CSS

Add your own styling:

Navigate to **Settings** → **"Custom CSS"**
Enter CSS rules:

/* Custom color scheme */
:root {
    --primary-color: #2563eb;
    --background-color: #f8fafc;
    --text-color: #1e293b;
}

/* Custom font */
body {
    font-family: 'Georgia', serif;
    font-size: 18px;
    line-height: 1.6;
}

/* Styled links */
a {
    color: var(--primary-color);
    text-decoration: none;
    border-bottom: 2px solid transparent;
    transition: border-color 0.2s;
}

a:hover {
    border-bottom-color: var(--primary-color);
}

/* Custom heading styles */
h1 {
    border-bottom: 3px solid var(--primary-color);
    padding-bottom: 0.5rem;
}

/* Code blocks */
pre {
    background: #1e293b;
    color: #e2e8f0;
    padding: 1rem;
    border-radius: 0.5rem;
    overflow-x: auto;
}

Wiki Metadata

Configure wiki-wide settings:

**Wiki Name**: My Knowledge Base
**Description**: Centralized documentation for our team
**Author**: Your Name
**Created**: 2025-12-20
**Version**: 1.0

These appear in the wiki’s settings and can be referenced in your pages.

Backup and Version Control

Manual Backup

The beauty of Feather Wiki is backup simplicity:

**Download Current State**: - Open the wiki in your browser - Right-click → "Save Page As" - Save the complete HTML file

**Automated Backup** (from server):

# Access your container
docker exec -it <container-id> sh

# Copy wiki file
cp /data/featherwiki.html /data/backup-$(date +%Y%m%d-%H%M%S).html

**Periodic Backups**:

Create a backup script on your local machine:

#!/bin/bash
WIKI_URL="https://your-wiki.klutch.sh"
BACKUP_DIR="$HOME/wiki-backups"
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p "$BACKUP_DIR"
curl -o "$BACKUP_DIR/featherwiki-$DATE.html" "$WIKI_URL"

# Keep only last 30 backups
ls -t "$BACKUP_DIR" | tail -n +31 | xargs -I {} rm "$BACKUP_DIR/{}"

echo "Backup completed: featherwiki-$DATE.html"

Run via cron:

# Backup wiki daily at 2 AM
0 2 * * * /path/to/backup-wiki.sh

Version Control with Git

Track your wiki changes in Git:

**Store Wiki in Repository**:

# Clone your deployment repo
git clone https://github.com/yourusername/feather-wiki-deployment.git
cd feather-wiki-deployment

# Download current wiki state
curl -o featherwiki.html https://your-wiki.klutch.sh

# Commit changes
git add featherwiki.html
git commit -m "Update wiki content - $(date +%Y-%m-%d)"
git push

**Automated Git Tracking**:

Create a sync script:

#!/bin/bash
WIKI_URL="https://your-wiki.klutch.sh"
REPO_DIR="$HOME/feather-wiki-deployment"

cd "$REPO_DIR"

# Download current wiki
curl -o featherwiki.html "$WIKI_URL"

# Check for changes
if git diff --quiet featherwiki.html; then
    echo "No changes detected"
    exit 0
fi

# Commit and push changes
git add featherwiki.html
git commit -m "Auto-update wiki - $(date +'%Y-%m-%d %H:%M:%S')"
git push

echo "Wiki changes committed to Git"

Run periodically:

# Sync every 6 hours
0 */6 * * * /path/to/sync-wiki.sh

Restoring from Backup

To restore a previous version:

**From Local Backup**: - Stop your running wiki container - Replace `/data/featherwiki.html` with your backup file - Restart the container

**From Git**:

# Checkout previous version
git checkout <commit-hash> featherwiki.html

# Deploy the restored version
git add featherwiki.html
git commit -m "Restore wiki to previous state"
git push

# Redeploy on Klutch.sh

Advanced Usage

Multiple Wiki Instances

Deploy separate wikis for different purposes:

Personal Wiki:

personal-wiki.klutch.sh - Private notes and ideas

Team Documentation:

team-docs.klutch.sh - Shared project documentation

Public Knowledge Base:

kb.yourdomain.com - Public-facing documentation

Each instance is completely independent with its own content and styling.

Wiki Templates

Create template pages for consistent documentation:

Project Template:

# Project: [Project Name]

## Overview
Brief description of the project

## Goals
- Goal 1
- Goal 2

## Timeline
| Phase | Description | Due Date |
|-------|-------------|----------|
| Phase 1 | Setup | YYYY-MM-DD |

## Resources
- [[Related Document]]
- [External Link](https://example.com)

## Status
Current status and updates

## Notes
Additional information

Meeting Notes Template:

# Meeting: [Topic] - [Date]

## Attendees
- Person 1
- Person 2

## Agenda
1. Topic 1
2. Topic 2

## Discussion
Notes from the meeting

## Action Items
- [ ] Task 1 - Assigned to [Name]
- [ ] Task 2 - Assigned to [Name]

## Next Meeting
Date and tentative topics

Embedding in Other Applications

Since Feather Wiki is a single HTML file, you can embed it in iframes:

<iframe
    src="https://your-wiki.klutch.sh"
    width="100%"
    height="800px"
    frameborder="0"
    title="Team Wiki">
</iframe>

API Access via JavaScript

While Feather Wiki doesn’t have a traditional API, you can interact with it programmatically:

// Fetch wiki content
async function fetchWikiContent() {
    const response = await fetch('https://your-wiki.klutch.sh');
    const html = await response.text();

    // Parse HTML to extract content
    const parser = new DOMParser();
    const doc = parser.parseFromString(html, 'text/html');

    // Extract pages (structure depends on Feather Wiki version)
    const pages = extractPages(doc);
    return pages;
}

// Example: Search wiki content
async function searchWiki(query) {
    const content = await fetchWikiContent();
    return content.filter(page =>
        page.title.includes(query) ||
        page.body.includes(query)
    );
}

Production Best Practices

Performance Optimization

Keep File Size Manageable:

Compress images before embedding (use tools like TinyPNG)
Archive old content to separate wiki instances
Aim to keep the wiki file under 5MB for optimal performance

Optimize Nginx:

# Enable HTTP/2 for better performance
listen 80 http2;

# Increase client body size for image uploads
client_max_body_size 10M;

# Add browser caching
location ~* \.(html)$ {
    add_header Cache-Control "no-cache, must-revalidate";
}

Security Hardening

Content Security Policy:

add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob:; img-src 'self' data: https:; font-src 'self' data:;" always;

Rate Limiting:

limit_req_zone $binary_remote_addr zone=wiki:10m rate=10r/s;

server {
    location / {
        limit_req zone=wiki burst=20 nodelay;
    }
}

Authentication Options:

For additional security beyond Feather Wiki’s built-in password:

Nginx Basic Auth:

# Generate password file
htpasswd -c /etc/nginx/.htpasswd username

Update nginx.conf:

location / {
    auth_basic "Restricted Wiki";
    auth_basic_user_file /etc/nginx/.htpasswd;
    try_files $uri $uri/ /index.html;
}

IP Whitelisting:

location / {
    allow 203.0.113.0/24;  # Office IP range
    allow 198.51.100.5;     # VPN IP
    deny all;

    try_files $uri $uri/ /index.html;
}

Monitoring

Access Logs:

# View real-time access logs
docker logs -f <container-id>

# Parse access patterns
docker exec <container-id> tail -f /var/log/nginx/access.log | grep -E "(GET|POST)"

Health Checks:

The Dockerfile includes a health check, but you can also monitor externally:

#!/bin/bash
WIKI_URL="https://your-wiki.klutch.sh"
ALERT_EMAIL="admin@example.com"

if ! curl -f -s -o /dev/null "$WIKI_URL"; then
    echo "Wiki is down!" | mail -s "Wiki Alert" "$ALERT_EMAIL"
fi

Resource Monitoring:

# Check container resource usage
docker stats <container-id>

# Memory usage
docker exec <container-id> free -m

# Disk usage
docker exec <container-id> df -h

Scaling Considerations

While Feather Wiki is designed for small to medium knowledge bases, you can scale it:

Horizontal Scaling:

Deploy multiple wiki instances for different teams/projects
Use Klutch.sh’s routing to manage multiple deployments

Content Organization:

Split large wikis into topic-specific instances
Use index pages to link between related wikis
Archive historical content to separate wikis

Performance at Scale:

Keep individual wikis under 10MB
Use image compression aggressively
Consider external image hosting for large visual content

Troubleshooting

Wiki Not Loading

Problem: Blank page or errors when accessing the wiki

Solutions:

Check container logs:
Terminal window
```
docker logs <container-id>
```

Verify Nginx is running:

docker exec <container-id> ps aux | grep nginx

Test file access:

docker exec <container-id> ls -la /usr/share/nginx/html/

Check file permissions:

docker exec <container-id> chmod 644 /usr/share/nginx/html/index.html

Changes Not Persisting

Problem: Edits disappear after container restart

Solutions:

Verify persistent volume is attached: - Check Klutch.sh dashboard - Confirm mount path is `/data`

Check symbolic link:

docker exec <container-id> ls -la /usr/share/nginx/html/index.html
# Should show symlink to /data/featherwiki.html

Verify write permissions:

docker exec <container-id> touch /data/test.txt

Password Not Working

Problem: Password set but not being requested or not accepting correct password

Solutions:

Clear browser cache and cookies for the wiki domain
Try password reset: - Download the wiki HTML file - Open locally in a browser - Go to Settings → Clear password - Save and re-upload
Check browser console for JavaScript errors: - Press F12 to open developer tools - Look for errors in the Console tab

Images Not Displaying

Problem: Uploaded images show as broken

Solutions:

Check image size - keep under 1MB per image
Verify image format - use JPG, PNG, or GIF
Check browser console for errors
Try re-uploading the image: - Delete the broken image - Upload again with a smaller file size

Slow Performance

Problem: Wiki loads slowly or feels sluggish

Solutions:

Check wiki file size:
Terminal window
```
docker exec <container-id> ls -lh /data/featherwiki.html
```
If over 5MB, consider:
- Compressing images
- Archiving old content
- Splitting into multiple wikis
Enable Gzip compression (already in our nginx.conf)
Clear browser cache
Check server resources:
Terminal window
```
docker stats <container-id>
```

Cannot Save Changes

Problem: Edit functionality not working

Solutions:

Check JavaScript is enabled in browser

Verify file permissions allow writes:

docker exec <container-id> chmod 644 /data/featherwiki.html
docker exec <container-id> chown nginx:nginx /data/featherwiki.html

Check browser console for errors
Try accessing wiki in incognito mode

Migration and Import

Importing from Other Wikis

From Markdown Files:

Collect all your Markdown files
For each file, create a page in Feather Wiki: - Copy the Markdown content - Paste into a new Feather Wiki page - Adjust internal links to use wiki syntax: `[[Page Name]]`
Update cross-references between pages

From Other Wiki Systems:

Export content from your current wiki (usually as Markdown or HTML), then import into Feather Wiki following the Markdown import process.

Exporting Content

Complete Wiki Export: Simply download the HTML file—it contains everything.

Individual Pages: Copy the Markdown content from each page and save to separate .md files for use elsewhere.

Automated Export Script:

// Run in browser console while viewing Feather Wiki
function exportAllPages() {
    const pages = getAllPages(); // Feather Wiki internal function
    const exports = pages.map(page => ({
        title: page.title,
        content: page.content,
        created: page.created,
        modified: page.modified
    }));

    console.log(JSON.stringify(exports, null, 2));

    // Download as JSON
    const blob = new Blob([JSON.stringify(exports, null, 2)],
        { type: 'application/json' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'featherwiki-export.json';
    a.click();
}

exportAllPages();

Use Cases and Examples

Personal Knowledge Base

Perfect for individual note-taking and knowledge management:

Daily Journal: Track thoughts, learnings, and experiences
Project Notes: Document personal projects and ideas
Learning Resources: Organize tutorials, guides, and references
Recipe Collection: Store and organize cooking recipes
Book Notes: Summarize and review books you’ve read

Team Documentation

Lightweight documentation for small teams:

Project Wiki: Centralize project information and decisions
Onboarding Guide: Help new team members get up to speed
Process Documentation: Document team workflows and procedures
Meeting Notes: Maintain searchable meeting history
Resource Directory: Links to tools, services, and contacts

Technical Documentation

Developer-friendly documentation solution:

API Documentation: Document endpoints, parameters, and examples
Code Snippets: Maintain a library of reusable code
Troubleshooting Guide: Common issues and solutions
Architecture Docs: System design and component documentation
Deployment Guides: Step-by-step deployment instructions

Education

Simple learning management:

Course Materials: Organize lectures, readings, and assignments
Student Portfolios: Showcase projects and achievements
Study Guides: Collaborative exam preparation resources
Research Notes: Manage research findings and citations

Additional Resources

With Feather Wiki deployed on Klutch.sh, you have an incredibly lightweight yet powerful knowledge management system. Its single-file architecture means simple backups, easy version control, and zero database complexity. Whether you’re building a personal knowledge base, team documentation hub, or technical wiki, Feather Wiki delivers modern functionality in a refreshingly minimal package.