Discover how to self-host Raneto, a lightweight, file-based knowledge base system using Docker.

This guide explores the architecture, configuration options, and deployment strategies for running your own documentation platform with complete control over your content.

Whether you’re managing internal documentation, creating a public wiki, or building a self-hosted alternative to commercial knowledge bases, Raneto offers a simple yet powerful solution built on open-source technologies.

Project Overview: Raneto

Raneto is a free, open-source Markdown-powered knowledge base system built for Node.js.

It provides a simple way to create and manage documentation through a file-based approach, where each page is a Markdown file stored in a content directory.

Why a SelfHosted Knowledge base Is Important

  • 🔒 Own your documentation with complete data sovereignty
  • 📝 Use familiar Markdown syntax for creating and editing content
  • 🔍 Built-in search functionality without complex database setup
  • 🛠️ Browser-based editor for quick content updates
  • 🚀 Lightweight and fast performance even on modest hardware
  • 🧩 Simple authentication system to protect sensitive content

Tech Overview: Raneto

At its core, Raneto is built with Node.js and Express, creating a lightweight server that processes Markdown files and serves them as HTML pages.

The system is designed to be modular, with a clear separation between content, themes, and functionality.

Raneto leverages a file-based approach rather than a database, making content management as simple as working with files in a directory. This design philosophy prioritizes simplicity and portability.

Module Descriptions

  • App Core: The main application module handles routing, file processing, and authentication.
  • Themes: Raneto supports theming through a simple templating system, with the default theme available as an NPM package.
  • Content Parser: Transforms Markdown files into HTML while processing metadata from YAML frontmatter.
  • Search Engine: Implements full-text search across all content files using lunr.js.
  • Authentication: Supports basic authentication, HTTP Basic Auth, and Google OAuth for content protection.
  • Internationalization: Multi-language support with translations for the interface.

Key Concepts and Algorithms: Raneto implements a lightweight search algorithm using lunr.js that creates indices of content for fast retrieval. The content organization follows a hierarchical structure where directories represent categories and Markdown files represent individual pages.

Dependencies:

  • Express (web framework)
  • Marked (Markdown parser)
  • Lunr (search engine)
  • Passport (authentication)
  • Hogan-Express (templating)
  • Node.js ecosystem utilities

Deployment Self-Hosting: Raneto

Self-hosting Raneto is straightforward with multiple deployment options available.

The simplest approach is using Docker, which encapsulates all dependencies and configurations.

Deploying Raneto with Docker

Raneto provides an official Docker image that makes deployment simple.

Here’s how to get started:

  1. Create a directory for your Raneto content:
mkdir -p raneto/content
  1. Create a docker-compose.yml file for easier management:
version: '3'
services:
  raneto:
    image: ryanlelek/raneto:latest
    container_name: raneto
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./content:/opt/raneto/content/pages
      - ./config.js:/opt/raneto/config/config.js
    restart: unless-stopped
  1. Create a custom config.js file to override default settings:
import path from 'node:path';

const __dirname = import.meta.dirname;
const theme_dir = path.join(
  __dirname,
  '..',
  'node_modules',
  '@raneto/theme-default',
);
const theme_name = 'dist';

const config = {
  // Your site title
  site_title: 'My Knowledge Base',
  
  // Base URL (if hosting at a subpath)
  base_url: '',
  
  // Theme configuration
  theme_dir,
  theme_name,
  
  // Content directory (Docker maps this to a volume)
  content_dir: path.join(__dirname, '..', 'content', 'pages'),
  
  // Enable editing through the web interface
  allow_editing: true,
  
  // Enable authentication
  authentication: true,
  authentication_for_edit: true,
  authentication_for_read: false,
  
  // User credentials
  credentials: [
    {
      username: 'admin',
      password: 'your-secure-password',
    },
  ],
  
  // Locale and datetime format
  locale: 'en',
  datetime_format: 'Do MMM YYYY',
  
  // Copyright notice
  copyright: `Copyright © ${new Date().getFullYear()} - My Knowledge Base`,
};

export default config;
  1. Start the Raneto container:
docker-compose up -d
  1. Access your Raneto instance at http://localhost:3000

Service Breakdown:

  • The Docker container runs a Node.js application serving Raneto on port 3000
  • Volumes map your local content directory to the container’s content directory
  • Configuration settings are externalized through the config.js file

Configuration: Raneto offers extensive configuration options through the config.js file. Key settings include:

  • Authentication methods (basic auth, Google OAuth)
  • Content directory path
  • Theme customization
  • Site title and branding
  • Search behavior and excerpt length
  • Locale and date formatting

The default login credentials for Raneto are:

Username: admin
Password: password

These should be changed immediately in your production deployment through the config.js file.

Conclusion

We’ve explored how to self-host Raneto, a lightweight Markdown-powered knowledge base system that offers simplicity and flexibility for documentation needs.

By deploying with Docker, you can quickly set up a powerful documentation platform without the complexity of traditional content management systems.

For organizations seeking alternatives to commercial knowledge base solutions, Raneto provides an excellent balance of features and simplicity. Other self-hosted alternatives worth considering include: BookStack, Wiki.js, DokuWiki, and MkDocs, each with their own approach to documentation management.

Latest Releases

  • v0.17.8: Fixed GitHub Actions for releases and improved CI/CD pipeline
  • v0.17.7: Upgraded to Node.js v22.13.1 and NPM v10.9.2 for improved performance
  • v0.17.6: Updated marked package to v15.0.5 for enhanced security
  • v0.17.5: Upgraded to latest Node.js v22.x LTS for better stability
  • v0.17.4: Improved Docker image with better caching and smaller footprint
  • v0.17.3: Enhanced search functionality with better language support
  • v0.17.2: Fixed authentication edge cases and improved security