obswiki/README.md

# 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](https://obsidian.md) 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**:
   ```bash
   cargo build --release
   ```

2. **Create configuration**:
   ```bash
   cp config.toml.example config.toml
   # Edit config.toml with your settings
   ```

3. **Point to your Obsidian vault**:
   ```bash
   ./target/release/obswiki --wiki-path /path/to/your/obsidian/vault
   ```

### Option 2: Create a New Vault

1. **Build the project**:
   ```bash
   cargo build --release
   ```

2. **Create configuration**:
   ```bash
   cp config.toml.example config.toml
   ```

3. **Create a new vault directory**:
   ```bash
   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**:
   ```bash
   ./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`:

```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:
   ```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:
   ```toml
   [auth.providers.oauth.google]
   client_id = "your_google_client_id"
   client_secret = "your_google_client_secret"
   ```

### LDAP Configuration

```toml
[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
  ```markdown
  ---
  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

```bash
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:

```nginx
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:
```bash
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.