mirror of
https://github.com/Nystik-gh/ignis.git
synced 2026-06-17 04:35:53 +00:00
update documentation
This commit is contained in:
Nystik
129
README.md
129
README.md
@@ -1,19 +1,128 @@
|
||||
# Ignis
|
||||
<section>
|
||||
<p align="center">
|
||||
<img src="images/ignis.png" alt="Ignis logo" width="200" height="200">
|
||||
</p>
|
||||
|
||||
An Electron shim and server bridge for running Obsidian in a browser. No VNC required.
|
||||
<h3 align="center">Ignis</h3>
|
||||
|
||||
# Why
|
||||
<p align="center">
|
||||
Run Obsidian in the browser. No VNC required.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
Obsidian is built on Electron but lacks browser access. Existing solutions rely on VNC/remote desktop, which provides a poor user experience. Since Electron is essentially a browser with Node.js integration, it should be possible to create a shim that routes Electron/Node APIs to a server, allowing Obsidian to run as a true web application.
|
||||
## What is this
|
||||
|
||||
Ignis is a proof of concept testing this approach.
|
||||
Ignis is a javascript shim that replaces the Electron APIs used by Obsidian and allows Obsidian to be run in the browser while keeping your vault on the server. As an alternative to sync based solutions, this lets you access your notes without installing an app on your device. Obsidian is not included in this repository, the Docker container downloads Obsidian directly from its official source on first run.
|
||||
|
||||
## How it works
|
||||
## Why
|
||||
|
||||
Ignis replaces the electron backend of Obsidian with a browser-compatible 'shim' that intercepts calls to Node.js and Electron APIs and routes them to a server.
|
||||
Obsidian's local first approach may not be the preference of some users, and while synchroniztion between devices is a perfectly good way to access your notes on multiple devices, options for accessing Obsidian remotely has been limited to VNC based solutions that have rather poor user experience. Ignis is an alternative for people who want to self-host a copy of Obsidian for easy access, in a (close-to) native format.
|
||||
|
||||
An in-memory metadata cache is built on page load so that sync filesystem calls (`existsSync`, `statSync`, etc.) work without round-tripping to the server every time. Async reads and writes go over HTTP. IPC channels like `ipcRenderer.sendSync("vault")` are faked with a dispatcher that returns what Obsidian expects. Native stuff like clipboard, menus, and dialogs have minimal stubs.
|
||||
## Project Status
|
||||
|
||||
## Status
|
||||
Ignis is **experimental**. Core functionality works, and some browser specific enhancements have been added, like file upload and download. Plugin support is an ongoing process of trying out plugins and finding what gaps in the shim still need to be plugged, but if a plugin uses primarily Obsidian's plugin API chances are it will work just fine.
|
||||
|
||||
Ignis is in an experimental state. Basic functionality works but no guarantee of stability or feature completeness. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
|
||||
## What works
|
||||
|
||||
- Creating, opening, and switching between multiple vaults
|
||||
- Editing notes (markdown, canvas, bases, all core editor features)
|
||||
- Community plugins to some degree (anything that doesn't need native Node modules, hopefully).
|
||||
- File upload and download from the browser
|
||||
- Live sync of external file changes via WebSocket
|
||||
- Obsidian Sync has been tested and seems to be working fine, as long as the tab remains open obviously.
|
||||
- Obsidian Headless has been integrated and can be used for continous synchronization. Can't be used alongside Obsidian Sycn in the browser, you can only pick one sync solution in order to avoid conflicts.
|
||||
|
||||
## Plugin Compatibility
|
||||
|
||||
Plugin support depends on what APIs a plugin uses. Anything built on Obsidian's plugin API generally works. Plugins that depend on Node.js modules might work depending on which are used.
|
||||
|
||||
Compatibility is currently tracked in [Issue #9](https://github.com/Nystik-gh/ignis/issues/9).
|
||||
|
||||
## Caveats
|
||||
|
||||
_This section will be expanded as issues are documented._
|
||||
|
||||
- Community plugins that rely on `child_process` or native Node addons will not work at the moment.
|
||||
- Mobile browser support is not a priority. It works, but the UX is not great. But I have ideas.
|
||||
- File picker has a workaround to deal with synchronous file selection issues. Usable, a bit hacky.
|
||||
|
||||
## Authentication
|
||||
|
||||
Ignis has **no built-in authentication**. The server is completely open by default.
|
||||
|
||||
If you are exposing Ignis to the internet, **you should really** put an authentication layer in front of it. Options include:
|
||||
|
||||
- A reverse proxy with basic auth (nginx, Caddy, Traefik)
|
||||
- An SSO proxy like Authelia, Authentik, or OAuth2 Proxy
|
||||
- A VPN (Tailscale, WireGuard)
|
||||
- Cloudflare Application Tunnel
|
||||
|
||||
> [!CAUTION]
|
||||
> Do not run Ignis on a public network without auth. Anyone with the url can read and write your vault files.
|
||||
|
||||
|
||||
|
||||
## Setup with Docker Compose
|
||||
|
||||
Ignis is not published to a registry yet. You need to build the image locally.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/user/obsidian-bridge.git
|
||||
cd obsidian-bridge
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
On first start, the container will download Obsidian from the official servers and set everything up, and also install Obsidian Headless CLI. This takes a minute or two.
|
||||
|
||||
Example `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
ignis:
|
||||
build: .
|
||||
ports:
|
||||
- "8080:8080"
|
||||
environment:
|
||||
- OBSIDIAN_VERSION=1.12.4
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
volumes:
|
||||
- ./vaults:/vaults
|
||||
- ./data:/app/data
|
||||
- obsidian-app:/app/obsidian-app
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
obsidian-app:
|
||||
```
|
||||
|
||||
### Volumes
|
||||
|
||||
| Mount | Description |
|
||||
| ----- | ----------- |
|
||||
| `/vaults` | Vault storage. Each subdirectory is a vault. |
|
||||
| `/data` | state persistence for various ignis specific functionality, plugin management, headless sync config, etc |
|
||||
| `/app/obsidian-app` | Cached Obsidian assets. Persisting this avoids re-downloading on container recreate. |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
| -------- | ----------- | ------- |
|
||||
| `PORT` | Server listen port | `8080` |
|
||||
| `VAULT_ROOT` | Path to vault storage inside the container | `/vaults` |
|
||||
| `DATA_ROOT` | Path to persistent data (plugin config, sync state, auth tokens) | `/app/data` |
|
||||
| `OBSIDIAN_VERSION` | Obsidian version to download | `1.12.4` |
|
||||
| `PUID` | User ID for file ownership | `1000` |
|
||||
| `PGID` | Group ID for file ownership | `1000` |
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, especially on how to report plugin compatibility issues. Check the [open issues](https://github.com/Nystik-gh/ignis/issues) for things to work on.
|
||||
|
||||
## Architecture
|
||||
|
||||
See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for details on the shim layer, plugin system, and server internals.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [GNU Affero General Public License v3.0](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user