builderadmin
/
NoteDiscovery
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

updated screenshot and docs

This commit is contained in:
Gamosoft 2025-11-15 18:42:56 +01:00
parent b03138c3d4
commit 248b54b556
6 changed files with 11 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -48,11 +48,11 @@ NoteDiscovery is a **lightweight, self-hosted note-taking application** that put
Use the pre-built image directly from GHCR - no building required!
> **💡 Tip**: Always use `ghcr.io/gamosoft/notediscovery:latest` to get the newest features and fixes. Images are automatically built when PRs are merged to main.
> **💡 Tip**: Always use `ghcr.io/gamosoft/notediscovery:latest` to get the newest features and fixes.
> **📁 Important - Volume Mapping**: The container needs local folders/files to work:
> - **Required**: `data` folder - **Your personal notes** will be stored here (create an empty folder)
> - **Required**: `themes` folder with theme `.css` files (at least light.css and dark.css)
> - **Required**: `themes` folder with theme `.css` files (at least a single theme must exist)
> - **Required**: `plugins` folder (can be empty for basic functionality)
> - **Required**: `config.yaml` file (needed for the app to run)
> - **Optional**: `documentation` folder - If you cloned the repo, mount this to view app docs inside NoteDiscovery
@ -86,7 +86,7 @@ Use the pre-built image directly from GHCR - no building required!
> # The documentation/ folder has app docs you can optionally mount
> ```
> **🔐 Security Note**: Authentication is **enabled by default** with password `admin`. For testing/local use, this is fine. If exposing to a network, **change the password immediately** - see [AUTHENTICATION.md](documentation/AUTHENTICATION.md) for instructions.
> **🔐 Security Note**: Authentication is **disabled by default** with password `admin`. For testing/local use, this is fine. If exposing to a network, **change the password immediately** - see [AUTHENTICATION.md](documentation/AUTHENTICATION.md) for instructions on how to enable it.
**Option 1: Docker Compose (Recommended)**
@ -218,7 +218,7 @@ Once you've started NoteDiscovery, you'll find comprehensive guides on:
# In your docker-compose.yml
volumes:
- ./data:/app/data # Your personal notes
- ./documentation:/app/docs:ro # Mount docs (read-only)
- ./documentation:/app/data/docs:ro # Mount docs subfolder inside the data folder (read-only)
```
Then access them at `http://localhost:8000` - the docs will appear as a `docs/` folder in the file browser!

19
config.yaml
View File

@ -21,30 +21,13 @@ search:
security:
# Authentication settings
# Set enabled to true to require login
enabled: true
enabled: false
# Session secret key - CHANGE THIS TO A RANDOM STRING!
# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
secret_key: "change_this_to_a_random_secret_key_in_production"
# Password hash - Generate with: python generate_password.py
# ⚠️ WARNING: The default hash below corresponds to password "admin"
# ⚠️ CHANGE THIS IMMEDIATELY in production!
#
# INSTRUCTIONS (Local):
# 1. Run: pip install bcrypt
# 2. Run: python generate_password.py
# 3. Enter your desired password
# 4. Copy the generated hash below
# 5. ALSO change secret_key above
# 6. Restart the application
#
# INSTRUCTIONS (Docker):
# 1. Run: docker-compose exec notediscovery python generate_password.py
# 2. Enter your desired password
# 3. Copy the generated hash below
# 4. ALSO change secret_key above
# 5. Restart: docker-compose restart
password_hash: "$2b$12$t/6PGExFzdpU2PUta0iVY.eDQwvu63kH.c/d4bEnnHaQ5CspH1yrG" # Default: "admin"
# Session expiry in seconds (default: 7 days)

BIN
docs/screenshot.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 363 KiB

After

Width:  |  Height:  |  Size: 338 KiB

7
documentation/API.md
View File

@ -46,7 +46,7 @@ Content-Type: application/json
}
```
**Note:** When creating a new note, the `on_note_create` hook is triggered, allowing plugins (like Template Generator) to modify the initial content. The response includes the potentially modified content.
**Note:** When creating a new note, the `on_note_create` hook is triggered, allowing plugins to modify the initial content. The response includes the potentially modified content.
**Linux/Mac:**
```bash
@ -241,11 +241,6 @@ All endpoints return JSON responses:
"detail": "Error message"
}
```
## 🔑 Authentication
Currently, no authentication is required. Suitable for self-hosted local environments.
---
💡 **Tip:** Use the `/api` endpoint to get a live, self-documented list of all available endpoints!

173
documentation/AUTHENTICATION.md
View File

@ -2,9 +2,9 @@
## ⚠️ **IMPORTANT: Default Password Warning**
> **The default `config.yaml` includes authentication enabled with password: `admin`**
> **The default `config.yaml` includes authentication disabled by default, with password: `admin`**
>
> 🔴 **CHANGE THIS IMMEDIATELY if you're exposing NoteDiscovery to a network!**
> 🔴 **CHANGE THIS if you're exposing NoteDiscovery to a network!**
>
> The default configuration is provided for **quick testing only**. Follow the setup guide below to set your own secure password and secret key.
@ -19,8 +19,6 @@ NoteDiscovery includes a simple, secure authentication system for single-user de
- ✅ **Single User** - Perfect for personal/self-hosted use
- ✅ **Secure** - Passwords hashed with bcrypt
- ✅ **Session-based** - Stay logged in for 7 days (configurable)
- ✅ **Theme-aware** - Login page matches your selected theme
- ✅ **Simple Setup** - Just 3 steps to enable
---
@ -31,7 +29,7 @@ NoteDiscovery includes a simple, secure authentication system for single-user de
- Default password is `admin`
- Default secret key is insecure
**⚠️ IMPORTANT:** For production or network-exposed deployments, **change both the password and secret key immediately**. Follow these steps:
**⚠️ IMPORTANT:** For production or network-exposed deployments, **change both the password and secret key immediately**.
---
@ -142,56 +140,6 @@ Enter the password you chose in Step 2.
---
## 🔐 Usage
### Logging In
1. Navigate to `http://localhost:8000`
2. You'll be **automatically redirected** to the login page if not authenticated
3. Enter your password (the one you generated in setup)
4. Click "🔓 Unlock"
5. You'll be redirected back to the main app
**Note:** The login page **automatically inherits the theme** you selected in the main app. It uses the same theme loading system as the main app (fetches CSS from `/api/themes` and stores preference in localStorage as `noteDiscoveryTheme`).
**What happens if I'm not logged in?**
- 🌐 **Page requests** (like `/`, `/MATHJAX`, etc.) → **Automatically redirected to login page**
- 🔌 **API requests** (like `/api/notes`) → **Return JSON error** `{"detail": "Not authenticated"}`
This smart routing ensures:
- ✅ Users always see the login page (never a JSON error)
- ✅ API calls get proper JSON errors (for programmatic access)
- ✅ No broken page loads or error messages
### Logging Out
**Option 1: Use the built-in logout button**
A logout button (🔒 Logout) automatically appears in the sidebar header when authentication is enabled. Simply click it to log out.
**Option 2: Navigate directly**
Visit `http://localhost:8000/logout` in your browser.
### Changing Password
1. Generate a new password hash:
- **Docker**: `docker-compose exec notediscovery python generate_password.py`
- **Local**: `python generate_password.py`
2. Update `password_hash` in `config.yaml` with the new hash
3. Restart the application:
- **Docker**: `docker-compose restart`
- **Local**: Restart uvicorn
4. All existing sessions will remain valid until they expire
### Session Expiry
- **Default**: 7 days (604800 seconds)
- **Custom**: Change `session_max_age` in `config.yaml`
- Sessions are cleared when you log out
---
## 🔒 Security Considerations
### ✅ What This Protects
@ -211,7 +159,7 @@ This is a **simple authentication system** designed for **self-hosted, single-us
### 🛡️ Best Practices
1. **Use HTTPS** - Always run behind a reverse proxy (nginx, Caddy) with SSL/TLS
1. **Use HTTPS** - Always run behind a reverse proxy (Traefik, nginx, Caddy) with SSL/TLS
2. **Strong Password** - Use at least 12 characters with mixed case, numbers, and symbols
3. **Unique Secret Key** - Never reuse secret keys across applications
4. **Keep Config Secure** - Don't commit `config.yaml` with real credentials to version control
@ -228,115 +176,4 @@ security:
enabled: false
```
Restart the application, and authentication will be bypassed.
---
## 🐛 Troubleshooting
### "Invalid Password" Error
- **Check password hash**: Ensure the hash in `config.yaml` matches your password
- **Regenerate hash**: Run `python generate_password.py` again
- **Check encoding**: Password must be UTF-8 encoded
### "Not authenticated" Error
- **Check session**: Your session may have expired (default: 7 days)
- **Clear cookies**: Clear your browser cookies and log in again
- **Check config**: Ensure `enabled: true` in `config.yaml`
### Login Page Not Showing
- **Check config**: Verify `enabled: true` in `config.yaml`
- **Check routes**: Visit `/login` directly
- **Check logs**: Look for errors in the console
### Can't Access `/logout`
- You must be logged in to access `/logout`
- Clear your browser cookies manually if needed
---
## 🎨 Customizing Login Page
The login page (`frontend/login.html`) can be customized:
- **Theme**: Automatically inherits the theme you selected in the main app (from localStorage)
- **Logo**: Uses `/static/logo.svg`
- **Styling**: Edit the CSS in the `<style>` section
- **Content**: Modify the HTML directly
- **Error Messages**: Displayed inline in red when login fails (no separate error page)
**Note:** The theme selector is intentionally hidden on the login page to keep it clean. Users will see the theme they selected in the main app.
---
## 📦 Docker Deployment
When using Docker, mount your `config.yaml` with credentials:
```yaml
services:
notediscovery:
image: ghcr.io/yourusername/notediscovery:latest
volumes:
- ./config.yaml:/app/config.yaml
- ./data:/app/data
ports:
- "8000:8000"
```
**Security Note**: Don't build credentials into the Docker image. Always mount them as a volume.
---
## 🤝 Multi-User Support
This authentication system is designed for **single-user** deployments. If you need multi-user support:
1. Run separate instances (one per user)
2. Use Docker containers with different ports
3. Use a reverse proxy for routing
For enterprise/multi-user needs, consider:
- OAuth 2.0 / OpenID Connect
- Database-backed user management
- Role-based access control (RBAC)
---
## 📝 Technical Details
### Password Hashing
- **Algorithm**: bcrypt
- **Rounds**: 12 (default)
- **Salt**: Automatically generated per password
### Session Management
- **Storage**: Server-side session cookies
- **Signing**: HMAC with secret key
- **Security**: HttpOnly, SameSite=Lax
- **Expiry**: Configurable (default 7 days)
### Dependencies
- `bcrypt` - Password hashing
- `itsdangerous` - Session signing
- `starlette` - Session middleware
---
## 📚 Additional Resources
- [bcrypt Documentation](https://github.com/pyca/bcrypt/)
- [FastAPI Security](https://fastapi.tiangolo.com/tutorial/security/)
- [OWASP Authentication Cheatsheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
---
**Need Help?** Open an issue on [GitHub](https://github.com/yourusername/notediscovery/issues) or consult the [README.md](README.md).
Restart the application, and authentication will be bypassed.

8
documentation/FEATURES.md
View File

@ -67,14 +67,6 @@
- **Event hooks** - React to note saves, deletes, searches
- **API access** - Full access to backend functionality
### Example Use Cases
- Git auto-sync
- Note encryption
- Export to PDF
- Daily note creation
- Backlinks tracking
- Tag management
## 🔍 Search
- **Full-text search** - Find notes by content