added a bukuserver runner tool

1 files changed, 36 insertions, 0 deletions

diff --git a/bukuserver-runner/README.md b/bukuserver-runner/README.md
new file mode 100644
index 0000000..bc5b219
--- /dev/null
+++ b/bukuserver-runner/README.md
@@ -0,0 +1,36 @@
+# Bukuserver runner
+
+This tool can be used to run and restart Bukuserver, switching databases between runs. It has no third-party dependencies, allowing to run Bukuserver sandboxed in a virtualenv as easily as the system-wide install (which is especifally useful for development).
+
+I suggest installing/symlinking it system-wide (e.g. as an `/usr/local/bin/buku-server` executable). Either of the `*.desktop` files can be edited according to match your setup and installed in your `local/share/applications/` folder for access from system menu.
+
+On Windows, you can create a shortcut file pointing to any Python executable (`python.exe` for windowed mode, `pythonw.exe` for headless) with added CLI arguments: path to `buku-server.py` followed by `--stop-if-running`.
+
+Note that windowed mode may be necessary if you want to see Bukuserver logs, or use noGUI mode (see below). The terminal window can be minimized to tray when not in use, by a program like [KDocker](https://github.com/user-none/KDocker), [RBTray](https://github.com/benbuck/rbtray) or [SmartSystemMenu](https://github.com/AlexanderPro/SmartSystemMenu).
+
+## Usage
+
+When running `buku-server.py` without arguments, it will prompt for database file, then start the Bukuserver. These actions will be repeated once Bukuserver stops running (e.g. after hitting `Ctrl+C`). The script will quit if you cancel the prompt.
+
+In GUI mode, the prompt is implemented as 2 dialogs; a list of databases to choose from, and a text input for creating a new DB. In the shell mode, you can type in DB number from the list, or a new DB name. Note that DB names must be valid filenames in your system (sans the `.db` extension). These files are located in your Buku settings folder (along with the default `bookmarks.db` file).
+
+Running `buku-server.py --stop` will kill the currently running Bukuserver process (thus allowing to restart it in the background, like a daemon). `buku-server.py --stop-if-running` will either start the script or kill Bukuserver if it's running already.
+
+## Environment variables
+
+The script behaviour can be configured by setting the following environment variables:
+* `BUKUSERVER` specifies path to your Bukuserver executable or Buku source directory.
+* `BUKU_DEVMODE` – if not empty, Bukuserver will be run in development mode. Normally used with source directory in `BUKUSERVER`.
+* `BUKU_VENV` overrides path to your virtualenv sandbox (default depends on whether `BUKU_DEVMODE` is set):
+  - when devmode is off, the virtualenv location defaults to a `venv/` folder in your Buku settings directory;
+  - when devmode is on, the virtualenv location defaults to a `venv/` folder in the source directory.
+* `BUKU_NOGUI` – if not empty, fallback shell prompt will be used (also happens if Tkinter is not present in your Python installation).
+
+Default values for all of these (as well as for `BUKUSERVER_` options) can be specified in a `bukuserver.env` file in your Buku settings folder:
+```sh
+# ~/.local/share/buku/bukuserver.env
+BUKUSERVER='~/Sources/buku/'  # when running from sources
+BUKUSERVER_THEME=slate
+BUKUSERVER_DISABLE_FAVICON=false
+BUKUSERVER_OPEN_IN_NEW_TAB=true
+```