286 lines
6.5 KiB
Markdown
286 lines
6.5 KiB
Markdown
# ObsWiki
|
|
|
|
A secure, Obsidian-style markdown wiki server built with Rust. Features authentication, role-based access control, and Obsidian-compatible markdown rendering.
|
|
|
|
## Features
|
|
|
|
- **Obsidian-style markdown rendering** with wiki links (`[[Page Name]]`) and tags (`#tag`)
|
|
- **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
|
|
|
|
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. **Create wiki directory**:
|
|
```bash
|
|
mkdir wiki
|
|
echo "# Welcome to ObsWiki\n\nThis is your home page!" > wiki/index.md
|
|
```
|
|
|
|
4. **Run the server**:
|
|
```bash
|
|
./target/release/obswiki
|
|
# Or with custom settings:
|
|
./target/release/obswiki --port 8080 --wiki-path my-wiki
|
|
```
|
|
|
|
5. **Access your wiki**:
|
|
- Open http://localhost:3000
|
|
- Default admin login: `admin` / `admin123`
|
|
|
|
## 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!**
|
|
|
|
## Wiki Features
|
|
|
|
### Obsidian-Style Markdown
|
|
|
|
- **Wiki links**: `[[Page Name]]` creates links to other pages
|
|
- **Tags**: `#programming #rust` creates clickable tags
|
|
- **Frontmatter**: YAML metadata support
|
|
```markdown
|
|
---
|
|
title: "My Page"
|
|
author: "John Doe"
|
|
tags: "example, test"
|
|
---
|
|
|
|
# Page Content
|
|
```
|
|
|
|
### File Organization
|
|
|
|
```
|
|
wiki/
|
|
├── index.md # Home page
|
|
├── projects/
|
|
│ ├── project1.md
|
|
│ └── project2.md
|
|
└── private/
|
|
└── secrets.md # Restricted by access rules
|
|
```
|
|
|
|
### Search
|
|
|
|
- **Live search**: Search as you type
|
|
- **Title and content search**: Finds matches in both
|
|
- **Tag search**: Use `#tagname` to search by tags
|
|
|
|
## 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. |