ObsWiki

A secure web server for serving Obsidian vaults as online wikis. Transform your Obsidian notes into a beautiful, searchable web wiki with authentication and access control.

Obsidian is a powerful note-taking application that stores notes in "vaults" - folders containing markdown files with special linking features. ObsWiki lets you share these vaults online while preserving all the Obsidian-specific markdown features you love.

Features

• Full Obsidian vault compatibility - Point to any existing Obsidian vault
• Native Obsidian markdown support including:
  • Wiki links ([[Page Name]] and [[Page Name|Display Text]])
  • Tags (#tag and nested tags #category/subtag)
  • Block references and embeds
  • Frontmatter metadata
• Multi-provider authentication:
  • Local username/password
  • GitHub OAuth
  • Google OAuth (configurable)
  • LDAP (configurable)
• Role-based access control with path-specific permissions
• Real-time search with live search results
• Responsive design with dark/light mode support
• SQLite database for user management and access rules

Quick Start

Option 1: Use an Existing Obsidian Vault

1. Build the project:

   cargo build --release
   

2. Create configuration:

   cp config.toml.example config.toml
   # Edit config.toml with your settings
   

3. Point to your Obsidian vault:

   ./target/release/obswiki --wiki-path /path/to/your/obsidian/vault
   

Option 2: Create a New Vault

1. Build the project:

   cargo build --release
   

2. Create configuration:

   cp config.toml.example config.toml
   

3. Create a new vault directory:

   mkdir my-vault
   echo "# Welcome to My Vault\n\nThis is your home page! Try creating [[Another Page]] with wiki links." > my-vault/index.md
   

4. Run the server:

   ./target/release/obswiki --wiki-path my-vault
   # Or use default port and path:
   ./target/release/obswiki
   

5. Access your wiki:

   • Open http://localhost:3000
   • Default admin login: admin / admin123

Obsidian Vault Compatibility

What Works Out of the Box

• ✅ All markdown files in your vault
• ✅ Folder structure preserved exactly as in Obsidian
• ✅ Wiki links [[Page Name]] and [[Page|Display]]
• ✅ Tags #tag and #category/subtag
• ✅ Frontmatter YAML metadata
• ✅ Standard markdown formatting
• ✅ Images and attachments (if in vault)
• ✅ Daily notes and template structures

Obsidian Features with Limitations

• ⚠️ Block references [[Page#^blockid]] - basic support
• ⚠️ Embeds ![[Page]] - partial support for images
• ⚠️ Dataview queries - not supported (shows as code blocks)
• ⚠️ Canvas files - not displayed (Obsidian-specific)
• ⚠️ Plugin-specific syntax - may not render correctly

Required Obsidian Settings

For optimal compatibility, configure these settings in your Obsidian vault:

Files & Links Settings:

• New link format: Set to "Absolute path in vault"
• Use Wikilinks: Set to false (unchecked)

These settings ensure that links work correctly when served through ObsWiki.

Vault Setup Tips

1. Point to your existing vault: ObsWiki works with any Obsidian vault
2. Configure Obsidian settings: Use the required settings above for best compatibility
3. No vault modification needed: Your Obsidian vault remains untouched
4. Real-time updates: Changes to files are reflected immediately
5. Access control: Add authentication without changing your vault structure

Configuration

Basic Configuration

Edit config.toml:

[server]
host = "127.0.0.1"
port = 3000
static_dir = "static"

[auth]
jwt_secret = "your-secure-secret-key"
session_timeout = 86400  # 24 hours

[auth.providers]
local = true  # Enable username/password auth

OAuth Configuration

GitHub OAuth

1. Create a GitHub OAuth App:

   • Go to GitHub Settings > Developer settings > OAuth Apps
   • New OAuth App with callback URL: http://localhost:3000/auth/github/callback

2. Add to config.toml:

   [auth.providers.oauth.github]
   client_id = "your_github_client_id"
   client_secret = "your_github_client_secret"
   

Google OAuth

1. Create Google OAuth credentials in Google Cloud Console
2. Add to config.toml:

   [auth.providers.oauth.google]
   client_id = "your_google_client_id"
   client_secret = "your_google_client_secret"
   

LDAP Configuration

[auth.providers.ldap]
server = "ldap://your-ldap-server:389"
bind_dn = "cn=admin,dc=example,dc=com"
bind_password = "admin_password"
user_base = "ou=users,dc=example,dc=com"
user_filter = "(uid={})"

User Management

User Roles

• Admin: Full access, can manage users and access rules
• Editor: Can edit and create pages (subject to access rules)
• Viewer: Read-only access (subject to access rules)

Access Rules

Access rules control which users can access specific paths:

• Path patterns:

  • * - matches everything (default rule)
  • admin/* - matches all pages under admin/
  • private/secrets - matches exact path

• Rule priority: More specific patterns take precedence

Example access rules (automatically created):

• admin/* requires admin role
• private/* requires editor role
• * allows viewer role (public access)

Default Users

The system creates a default admin user:

• Username: admin
• Password: admin123
• ⚠️ Change this password immediately in production!

Obsidian Vault Features

Full Obsidian Markdown Compatibility

ObsWiki supports all the markdown features that make Obsidian special:

• Wiki links:
  • [[Page Name]] - links to pages
  • [[Page Name|Display Text]] - links with custom text
  • [[Folder/Page Name]] - links to pages in subfolders
• Tags:
  • #programming - simple tags
  • #category/subcategory - nested tags
  • Tags are clickable and searchable
• Frontmatter: Full YAML metadata support

  ---
  title: "My Research Note"
  author: "John Doe"
  tags: [research, obsidian, markdown]
  created: 2024-01-15
  ---
  
  # Page Content
  

• Block references: Reference specific paragraphs and sections
• Embeds: Include content from other pages (partially supported)

Vault Structure Compatibility

ObsWiki works with any Obsidian vault structure:

vault/
├── index.md                    # Home page (or README.md)
├── Daily Notes/
│   ├── 2024-01-15.md
│   └── 2024-01-16.md
├── Projects/
│   ├── ObsWiki.md
│   └── Personal Website.md
├── Areas/
│   ├── Programming/
│   │   ├── Rust.md
│   │   └── Web Development.md
│   └── Research/
│       └── Literature Review.md
├── Resources/
│   └── References.md
└── Archive/
    └── Old Notes.md           # Can be restricted by access rules

Note: ObsWiki respects your existing Obsidian vault organization and folder structure.

Obsidian-Aware Search

• Live search: Search as you type, just like Obsidian
• Content search: Searches through all your note content
• Tag search: Use #tagname to find all notes with specific tags
• Link-aware: Understands your wiki link connections
• Metadata search: Searches through frontmatter properties

API Endpoints

Authentication

• POST /auth/login - Local login
• POST /auth/register - Register new user
• GET /auth/github - GitHub OAuth
• GET /auth/github/callback - GitHub OAuth callback

Wiki

• GET /wiki/:path - View page
• GET /api/wiki/:path - Get page JSON
• GET /api/search?q=query - Search pages

Development

Project Structure

src/
├── main.rs           # Entry point
├── auth/             # Authentication & authorization
├── config/           # Configuration management
├── markdown/         # Markdown parsing & rendering
├── models/           # Data models
├── server/           # Web server & routes
└── wiki/             # Wiki service & file management

Running Tests

cargo test

Database Migrations

Migrations run automatically on startup. Database schema:

• users - User accounts and profiles
• sessions - Session management
• access_rules - Path-based access control

Security Features

• JWT-based authentication with configurable expiration
• bcrypt password hashing for local accounts
• HTTPS ready (configure reverse proxy)
• Role-based access control with path-specific rules
• Session management with automatic expiration
• CSRF protection (built into authentication flow)

Production Deployment

Using a Reverse Proxy

Example Nginx configuration:

server {
    listen 80;
    server_name wiki.example.com;
    
    location / {
        proxy_pass http://127.0.0.1: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;
    }
}

Security Checklist

• Change default admin password
• Set secure JWT secret key
• Use HTTPS in production
• Configure proper OAuth callback URLs
• Set appropriate file permissions on wiki directory
• Regular database backups
• Monitor access logs

Troubleshooting

Common Issues

1. "Permission denied" errors:

   • Check user roles and access rules
   • Verify file system permissions

2. OAuth not working:

   • Verify callback URLs match OAuth app configuration
   • Check client ID and secret

3. Pages not loading:

   • Ensure wiki directory exists and is readable
   • Check file extensions (.md required)

Logs

Enable debug logging:

RUST_LOG=debug ./obswiki

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

License

MIT License - see LICENSE file for details.