Wiki.js: A Beautiful Self-Hosted Wiki With Modern Features

Someone leaves the company. They take with them everything they knew about how the billing system actually works, why the staging environment is configured that way, and what that one cron job does at 3 AM on Sundays. The next person to touch any of it spends two weeks reverse-engineering tribal knowledge that should have been written down somewhere.

Photo by Markus Spiske on Unsplash

This is the institutional knowledge problem, and it is universal. Every team experiences it. The solution is always the same: a wiki. The challenge is finding one that people will actually use. A wiki that sits empty is worse than no wiki at all — it creates the illusion that documentation exists when it does not.

Wiki.js is a self-hosted wiki built on Node.js and PostgreSQL with a modern interface, multiple editor modes, Git-based sync, and one of the most comprehensive authentication systems of any open source wiki. It looks good, it is fast, and it has enough features to satisfy teams that need more than a basic Markdown note system.

Wiki.js vs BookStack vs Outline vs MediaWiki

Before committing to any wiki platform, you should understand the trade-offs. Here is an honest comparison of the four most popular self-hosted options.

When to choose Wiki.js

Pick Wiki.js if your team needs multiple editor modes. Some people prefer writing Markdown, others need a visual editor, and occasionally someone wants to drop in raw HTML. Wiki.js is the only self-hosted wiki that gives you all three on a per-page basis. The Git sync feature is also a significant differentiator — if you want your documentation backed up to a Git repository automatically, Wiki.js handles this natively.

Wiki.js is also the right choice when you need robust authentication. It supports more identity providers out of the box than any other self-hosted wiki, including Active Directory, Azure AD, Google, GitHub, Okta, Auth0, Keycloak, Authentik, and many more. If your organization has complex SSO requirements, Wiki.js will likely support them without custom configuration.

When to choose BookStack

BookStack is better if you want an opinionated organizational structure. Its Shelves > Books > Chapters > Pages hierarchy forces documentation into a navigable format. BookStack also uses fewer resources (it runs on PHP and MySQL, which are lighter than Node.js and PostgreSQL for this workload) and has an extremely straightforward setup. If your team is small and non-technical, BookStack's lower complexity is an advantage.

When to choose Outline

Outline is the right call if real-time collaboration is a requirement. Multiple people editing the same page simultaneously, seeing each other's cursors — Outline does this well. Its block-based editor also feels more like Notion, which many teams already know. The trade-off is that Outline's source-available license (BSL 1.1) is more restrictive than Wiki.js's AGPL, and it requires Redis in addition to PostgreSQL.

When to choose MediaWiki

MediaWiki powers Wikipedia, so it scales to millions of pages. Choose it if you have a massive, public-facing knowledge base with hundreds of contributors. For small-to-medium team wikis, MediaWiki is overkill — its extension-dependent architecture and wikitext markup create unnecessary friction.

Installation via Docker Compose

Wiki.js runs on Node.js with a PostgreSQL backend. The Docker Compose setup is straightforward.

# docker-compose.yml
services:
  wikijs:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: your-secure-password-here
      DB_NAME: wikijs
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    container_name: wikijs-db
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: your-secure-password-here
    volumes:
      - wikijs-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  wikijs-db:

Start it up:

docker compose up -d

Wiki.js is now available at http://your-server:3000. On first launch, you will see a setup wizard that walks you through creating your admin account and configuring the site URL.

Important: Set your site URL correctly during setup. Wiki.js uses this for generating links, handling redirects, and configuring authentication callbacks. Getting this wrong will cause SSO and navigation issues later.

HTTPS with a reverse proxy

For production, put Wiki.js behind a reverse proxy with TLS. Here is a minimal Caddy configuration:

wiki.yourdomain.com {
    reverse_proxy localhost:3000
}

For Nginx:

server {
    server_name wiki.yourdomain.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Core Features

Multiple editors

Wiki.js offers three editors, selectable per page when you create it:

Markdown editor — The default and most popular choice. Full Markdown support with a toolbar for formatting, a live preview panel, and keyboard shortcuts. If your team writes documentation in Markdown already (and most technical teams do), this is the natural choice.

Visual editor (WYSIWYG) — A rich text editor for people who prefer formatting with buttons rather than syntax. Supports headings, lists, tables, images, links, and code blocks. Useful for non-technical team members who need to contribute documentation without learning Markdown.

Raw HTML — For pages that need precise layout control, embedding widgets, or custom styling. This editor is a code editor with syntax highlighting. Most teams will never need it, but it is there when you do.

The editor choice is stored per-page, so your engineering team can write in Markdown while your HR team uses the visual editor. Pages render identically regardless of which editor created them.

Page trees and organization

Wiki.js uses a path-based page structure. Pages live at URL paths like /engineering/runbooks/deployment or /onboarding/first-week. You create folders implicitly by adding path segments. The sidebar shows a navigable tree of all pages.

This approach is more flexible than BookStack's rigid hierarchy but less structured. You can organize pages however you want, which means you can also create a disorganized mess. Establish naming conventions early:

/engineering/
  /architecture/
    /system-overview
    /database-design
  /runbooks/
    /deployment
    /incident-response
    /database-migrations
/operations/
  /infrastructure/
    /server-inventory
    /network-diagram
  /monitoring/
    /alerting-rules
    /dashboards
/onboarding/
  /engineering-setup
  /access-requests
  /first-week-checklist

Git sync for backup

This is one of Wiki.js's best features. You can configure Wiki.js to automatically sync all page content to a Git repository — GitHub, GitLab, Gitea, or any remote Git server.

To set it up:

1. Go to Administration > Storage
2. Enable the Git storage target
3. Configure the repository URL, branch, and authentication (SSH key or token)
4. Set the sync interval (default: 5 minutes)

Every page change is committed and pushed to the remote repository. This gives you:

• Automatic off-site backup of all wiki content
• Full version history through Git, independent of Wiki.js itself
• Disaster recovery — if your Wiki.js instance dies, all content exists as Markdown files in a Git repo
• Migration path — if you ever leave Wiki.js, your content is already in portable Markdown

The sync is bidirectional. You can edit files in the Git repository directly, and Wiki.js will pull the changes on the next sync cycle. This opens up workflows like editing documentation in your IDE and having it appear in the wiki automatically.

Full-text search

Wiki.js includes a built-in search engine based on PostgreSQL's full-text search capabilities. For most teams, this is sufficient — it indexes all page content and returns relevant results quickly.

If you have thousands of pages or need advanced search features (fuzzy matching, faceted search, weighted results), Wiki.js also supports Elasticsearch as an alternative search backend. Add it to your Docker Compose:

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.12.0
    container_name: wikijs-search
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    volumes:
      - wikijs-es:/usr/share/elasticsearch/data
    restart: unless-stopped

Then configure it under Administration > Search Engine and select Elasticsearch with the connection URL http://elasticsearch:9200. Be aware that Elasticsearch adds 500+ MB of RAM to your stack. Only add it if you genuinely need it.

Diagram support

Wiki.js supports three diagramming tools natively:

draw.io (diagrams.net) — Embed full draw.io diagrams directly in pages. The draw.io editor opens inline, and diagrams are stored as part of the page content. Ideal for architecture diagrams, network topology, and flowcharts.

Mermaid — Write diagrams as code using Mermaid syntax. Supports flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, and more. Insert a Mermaid code block in Markdown and it renders automatically.

```mermaid
graph TD
    A[Load Balancer] --> B[App Server 1]
    A --> C[App Server 2]
    B --> D[(PostgreSQL)]
    C --> D
    D --> E[Backup Storage]

**PlantUML** — For UML-specific diagrams (class diagrams, sequence diagrams, use case diagrams). Requires a PlantUML server, which you can self-host as an additional container.

### Page features

Beyond basic content, Wiki.js pages support:

- **Tags** — categorize pages with tags for cross-cutting concerns
- **Page aliases** — create alternative URLs that redirect to a page
- **Page relations** — link related pages together
- **Table of contents** — auto-generated from headings
- **Comments** — page-level discussion (when enabled)
- **Page rules** — restrict who can read, write, or manage specific pages or paths

## Advanced Configuration

### OIDC and SAML authentication

Wiki.js has one of the broadest authentication systems of any self-hosted wiki. Configuration happens in **Administration > Authentication**.

**OIDC example (works with Keycloak, Authentik, Authelia):**

1. Go to **Administration > Authentication**
2. Click **Add Strategy** and select **OpenID Connect / OAuth2**
3. Fill in:
   - **Client ID**: your registered client ID
   - **Client Secret**: your client secret
   - **Authorization URL**: `https://auth.yourdomain.com/realms/yourrealm/protocol/openid-connect/auth`
   - **Token URL**: `https://auth.yourdomain.com/realms/yourrealm/protocol/openid-connect/token`
   - **User Info URL**: `https://auth.yourdomain.com/realms/yourrealm/protocol/openid-connect/userinfo`
4. Map the email and display name claims
5. Set **Self-registration** to enabled if you want users auto-created on first login

**SAML2 example:**

1. Add a **SAML 2.0** strategy
2. Configure the **Entry Point URL** (your IdP's SSO URL)
3. Upload or paste the **IdP Certificate**
4. Set the **Audience** to your Wiki.js URL
5. Map attributes for email, display name, and optionally groups

You can enable multiple authentication strategies simultaneously. Wiki.js will show all enabled options on the login screen, letting users choose their preferred method.

### S3 storage backend

By default, Wiki.js stores uploaded assets (images, files) in the local filesystem. For production deployments, you can use S3-compatible storage instead:

1. Go to **Administration > Storage**
2. Enable **Amazon S3** (works with MinIO, Backblaze B2, Wasabi, and any S3-compatible service)
3. Configure bucket name, region, access key, and secret key
4. Set the schedule for sync

This separates your asset storage from the Wiki.js container, making deployments and migrations cleaner.

### Custom themes and branding

Wiki.js supports visual customization through **Administration > Theme**:

- **Dark mode** — built-in dark theme, switchable per-user or enforced globally
- **Custom CSS** — inject custom styles to match your organization's branding
- **Custom logo** — replace the Wiki.js logo with your own
- **Custom navigation** — configure the sidebar navigation links
- **Custom footer** — add links, legal notices, or version information

### Localization

Wiki.js supports over 40 languages out of the box. The admin panel lets you:

- Set the default language for the site
- Allow users to switch languages via the interface
- Configure namespaces per-language for multilingual content (e.g., `/en/page-name` and `/fr/page-name`)

This is a significant advantage if your organization operates across multiple languages.

## Resource Requirements

| Deployment size | CPU | RAM | Storage | Notes |
|----------------|-----|-----|---------|-------|
| Small (< 500 pages, < 20 users) | 1 core | 512 MB | 1 GB | PostgreSQL built-in search |
| Medium (500-5,000 pages, 20-100 users) | 2 cores | 1 GB | 5 GB | PostgreSQL built-in search |
| Large (5,000+ pages, 100+ users) | 4 cores | 2 GB + 1 GB for ES | 20 GB+ | Add Elasticsearch for search |

These numbers include both the Wiki.js application and PostgreSQL. Wiki.js itself is a Node.js application that uses roughly 200-300 MB of RAM at idle. PostgreSQL adds another 50-100 MB for a small deployment.

Storage grows primarily from uploaded assets (images, file attachments). Page content itself is lightweight — even thousands of pages occupy only tens of megabytes in the database.

## Honest Limitations

You should know what you are getting into before committing to Wiki.js.

**The v3 rewrite situation.** Wiki.js v3 has been in development for years. The project announced a ground-up rewrite with a new architecture, a new editor, and new features. As of early 2026, v3 is still not released. Wiki.js v2 is stable and works well, but it is aging. The project is not abandoned — development continues — but if you are evaluating Wiki.js, you are evaluating v2 with the understanding that v3 may eventually supersede it. Do not choose Wiki.js based on v3 feature promises.

**PostgreSQL is required.** Wiki.js v2 supports MySQL, MariaDB, PostgreSQL, MS SQL Server, and SQLite. However, the project recommends PostgreSQL, and several features (including the built-in search engine) work best with it. If you are a MySQL shop, this adds operational overhead.

**No real-time collaboration.** Unlike Outline and Docmost, Wiki.js does not support multiple people editing the same page simultaneously. It uses a lock-based approach — when someone is editing a page, others see a notice. For many teams this is not a problem, but it is worth knowing.

**Some features feel half-finished.** The comments system is basic. The visual editor is functional but not as polished as BookStack's WYSIWYG or Outline's block editor. The administration panel has many configuration options, but some of them (particularly around rendering and extensions) have sparse documentation. You may occasionally find yourself reading GitHub issues to figure out how something works.

**No built-in templates.** Wiki.js does not have a page template system. You can work around this by creating template pages that people duplicate, but it is not as smooth as BookStack's or Docmost's built-in template features.

**The GraphQL API is powerful but complex.** Wiki.js uses GraphQL instead of REST. This is more flexible for complex queries but adds a learning curve if your team is not familiar with GraphQL. Simple integrations (like creating a page from a script) require more boilerplate than a REST API would.

## Practical Tips for Operators

**Back up the database, not just the Git sync.** Git sync captures page content, but it does not capture user accounts, permissions, authentication settings, or configuration. Back up PostgreSQL separately:

```bash
docker exec wikijs-db pg_dump -U wikijs wikijs > wikijs-backup-$(date +%Y%m%d).sql

Run this daily via cron. Keep at least 7 days of backups.

Set up Git sync immediately. Even if you have database backups, Git sync gives you a human-readable copy of all documentation in Markdown format. If you ever need to migrate away from Wiki.js or recover from a catastrophic failure, having all your content as Markdown files in a Git repo is invaluable.

Establish page path conventions before your team starts writing. Once pages exist at specific paths, moving them is disruptive (bookmarks break, internal links may need updating). Decide on your top-level structure early: /engineering/, /operations/, /onboarding/, etc.

Use page rules for access control. Wiki.js's permission system is path-based. You can create rules like "members of the Engineering group can edit anything under /engineering/" or "only admins can edit pages under /policies/". Set these up before inviting your team.

Monitor disk usage if you allow file uploads. Wiki.js does not enforce upload size limits by default. If your team uploads large files (PDFs, videos, design assets), storage can grow quickly. Set limits in your reverse proxy's configuration (client_max_body_size in Nginx) and consider using S3 storage for assets.

Keep the container image pinned to a specific minor version. The ghcr.io/requarks/wiki:2 tag tracks the latest v2 release. For production, pin to a specific version like ghcr.io/requarks/wiki:2.5 and upgrade deliberately after reviewing the changelog.

Test authentication changes in a staging instance first. Misconfiguring SSO in Wiki.js can lock you out of the admin panel. Always test authentication changes on a copy of your instance. If you do get locked out, you can bypass authentication by setting the environment variable WIKI_ADMIN_PASS to reset the local admin password on startup.

Backup and Disaster Recovery

A complete Wiki.js backup includes three components:

#!/bin/bash
# wikijs-backup.sh
BACKUP_DIR="/backups/wikijs/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# 1. Database dump
docker exec wikijs-db pg_dump -U wikijs wikijs > "$BACKUP_DIR/database.sql"

# 2. Configuration (if using bind mounts instead of named volumes)
# docker cp wikijs:/wiki/data "$BACKUP_DIR/data"

# 3. Git sync already provides page content backup
# Verify the remote repo is up to date
echo "Backup completed: $BACKUP_DIR"

To restore:

# Restore database
docker exec -i wikijs-db psql -U wikijs wikijs < database.sql

# Pages will resync from Git on next sync cycle

Resources

• Official site: wiki.js.org
• Documentation: docs.requarks.io
• Source code: github.com/requarks/wiki
• Docker image: ghcr.io/requarks/wiki
• Community: Discord and GitHub Discussions
• v3 roadmap: blog.js.wiki for development updates

Wiki.js occupies a useful middle ground in the self-hosted wiki space. It is more feature-rich than BookStack, more mature than Docmost, and more approachable than MediaWiki. The Git sync feature alone makes it worth considering — having all your documentation version-controlled in a Git repository, automatically, is a genuinely useful capability that most wikis lack. The main risk is the uncertain timeline of the v3 rewrite, but v2 is stable, actively maintained, and handles the core job of team documentation well. If your team needs a wiki that supports multiple editors, strong authentication, and Git-based backup, Wiki.js is a solid choice.