# ppf.webref
ppf.webref is a web app providing an interface to a [JabRef SQL
database](https://docs.jabref.org/collaborative-work/sqldatabase).
Access your references from anywhere in the world and from any device with a
web browser. You do not need to install Java, you do not need to install an
app. Any non-archaic phone, tablet, PC, Mac, or Raspberry Pi will do.
Create a JabRef database (using your normal JabRef) and point ppf.webref to
this database. Voila: Your references just became accessible worldwide.
Note: ppf.webref provides *read-only* access to your library. To add, edit, or
delete entries from your library, you still need a standard JabRef installation
somewhere.
# Installation
Prerequisite: You need JabRef to create, edit, and extend your library.
Install `ppf.webref` (or have a look at
[docker.webref](https://github.com/adrianschlatter/docker.webref) that provides
a docker container running `ppf.webref`):
```shell
pip install ppf.webref
```
Then, create the config file `~/.config/ppf.webref/ppf.webref.conf`:
```
[flask]
secret_key = <your secret key here>
[database]
server = <server>:<port>
databasename = <name of your jabref database>
username = <username ppf.webref should use to access db>
password = <password ppf.webref should use to access db>
```
`secret_key` is needed to encrypt cookies. Set it to a random string, e.g. by
running this snippet:
```shell
python -c 'import secrets; print(secrets.token_hex())'
```
You can now start the web server by
```shell
flask --app ppf.webref run
```
and point your webbrowser to http://localhost:5000.
[This will start ppf.webref on your local machine which is nice for testing.
To get the most out of ppf.webref, you will probably want to run ppf.webref on
a server.]
ppf.webref will present a login form. However, as we have not created any users
yet, we can't login. To create a user, run:
```shell
flask --app ppf.webref useradd <username>
```
This will:
* create a table 'user' in your db if it does not exist yet
* register user <username> in user table
To set a password for this new user or to change the password of an existing
user, do
```shell
flask --app ppf.webref passwd <username>
```
which will ask for and store (a salted hash of) the password in the
user table.
Now we are able to login, but the entry table will not provide clickable links
so you can easily open your documents. For `ppf.webref` to be able to serve the
documents themselves, we have to put them under `<app.root_path>/references`
(just place a symlink to your JabRef library there). The app's root path is
something like `/usr/local/lib/python3.11/site-packages/ppf/webref/`.
# Still reading?
If you read this far, you're probably not here for the first time. If you use
and like this project, would you consider giving it a Github Star? (The button
is at the top of this website.) If not, maybe you're interested in one of my
[my other
projects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_of_projects.md)?
# Contributing
Did you find a bug and would like to report it? Or maybe you've fixed it
already or want to help fixing it? That's great! Please read
[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed.
To help ascertain that contributing to this project is a pleasant experience,
we have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect
everyone to adhere to it, just make sure you do as well.
# Changelog
* 0.1.1: Fix problem with path handling. Improve docs.
* 0.1: Basic read-only functionality
Raw data
{
"_id": null,
"home_page": "https://github.com/adrianschlatter/ppf.webref/tree/master",
"name": "ppf.webref",
"maintainer": "",
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": "",
"keywords": "jabref,references,web,server,app",
"author": "Adrian Schlatter",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# ppf.webref\n\nppf.webref is a web app providing an interface to a [JabRef SQL\ndatabase](https://docs.jabref.org/collaborative-work/sqldatabase).\nAccess your references from anywhere in the world and from any device with a\nweb browser. You do not need to install Java, you do not need to install an\napp. Any non-archaic phone, tablet, PC, Mac, or Raspberry Pi will do.\n\nCreate a JabRef database (using your normal JabRef) and point ppf.webref to\nthis database. Voila: Your references just became accessible worldwide.\n\nNote: ppf.webref provides *read-only* access to your library. To add, edit, or\ndelete entries from your library, you still need a standard JabRef installation\nsomewhere.\n\n\n# Installation\n\nPrerequisite: You need JabRef to create, edit, and extend your library.\n\nInstall `ppf.webref` (or have a look at\n[docker.webref](https://github.com/adrianschlatter/docker.webref) that provides\na docker container running `ppf.webref`):\n\n```shell\npip install ppf.webref\n```\n\nThen, create the config file `~/.config/ppf.webref/ppf.webref.conf`:\n\n```\n[flask]\nsecret_key = <your secret key here>\n\n[database]\nserver = <server>:<port>\ndatabasename = <name of your jabref database>\nusername = <username ppf.webref should use to access db>\npassword = <password ppf.webref should use to access db>\n```\n\n`secret_key` is needed to encrypt cookies. Set it to a random string, e.g. by\nrunning this snippet:\n\n```shell\npython -c 'import secrets; print(secrets.token_hex())'\n```\n\nYou can now start the web server by\n\n```shell\nflask --app ppf.webref run\n```\n\nand point your webbrowser to http://localhost:5000.\n\n[This will start ppf.webref on your local machine which is nice for testing.\nTo get the most out of ppf.webref, you will probably want to run ppf.webref on\na server.]\n\nppf.webref will present a login form. However, as we have not created any users\nyet, we can't login. To create a user, run:\n\n```shell\nflask --app ppf.webref useradd <username>\n```\n\nThis will:\n\n* create a table 'user' in your db if it does not exist yet\n* register user <username> in user table\n\nTo set a password for this new user or to change the password of an existing\nuser, do\n\n```shell\nflask --app ppf.webref passwd <username>\n```\n\nwhich will ask for and store (a salted hash of) the password in the\nuser table.\n\nNow we are able to login, but the entry table will not provide clickable links\nso you can easily open your documents. For `ppf.webref` to be able to serve the\ndocuments themselves, we have to put them under `<app.root_path>/references`\n(just place a symlink to your JabRef library there). The app's root path is\nsomething like `/usr/local/lib/python3.11/site-packages/ppf/webref/`.\n\n\n# Still reading?\n\nIf you read this far, you're probably not here for the first time. If you use\nand like this project, would you consider giving it a Github Star? (The button\nis at the top of this website.) If not, maybe you're interested in one of my\n[my other\nprojects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_of_projects.md)?\n\n\n# Contributing\n\nDid you find a bug and would like to report it? Or maybe you've fixed it\nalready or want to help fixing it? That's great! Please read\n[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed.\n\nTo help ascertain that contributing to this project is a pleasant experience,\nwe have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect\neveryone to adhere to it, just make sure you do as well.\n\n\n# Changelog\n\n* 0.1.1: Fix problem with path handling. Improve docs.\n* 0.1: Basic read-only functionality\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flask app providing a web-interface to a JabRef database",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/adrianschlatter/ppf.webref/issues",
"Homepage": "https://github.com/adrianschlatter/ppf.webref/tree/master",
"Source": "https://github.com/adrianschlatter/ppf.webref"
},
"split_keywords": [
"jabref",
"references",
"web",
"server",
"app"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ef5c18adaa8c57842c240d015b629aea520b1b6fc97d40201a66f4f39626250",
"md5": "39474f208f9f77201185b7e701a7cd86",
"sha256": "fff09d5a9ffe1bd6672980d39dddd7f1e6a1cab157a42b593d606ec3cb6d2779"
},
"downloads": -1,
"filename": "ppf.webref-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39474f208f9f77201185b7e701a7cd86",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 10896,
"upload_time": "2024-01-01T22:27:43",
"upload_time_iso_8601": "2024-01-01T22:27:43.404878Z",
"url": "https://files.pythonhosted.org/packages/7e/f5/c18adaa8c57842c240d015b629aea520b1b6fc97d40201a66f4f39626250/ppf.webref-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-01 22:27:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adrianschlatter",
"github_project": "ppf.webref",
"github_not_found": true,
"lcname": "ppf.webref"
}
JSON
