yeet
This commit is contained in:
286
README.md
Normal file
286
README.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user