Merge pull request #2 from adrianschlatter/develop

Dockerize `ppf.webref-0.1.1`

.github/workflows/docker-image.yml

@@ -0,0 +1,14 @@
+name: Docker Image CI
+
+on:
+  pull_request:
+  workflow_dispatch:  # you can trigger this workflow manually
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v3
+    - name: Build the Docker image
+      run: make

.gitignore

@@ -0,0 +1,37 @@
+# to avoid leaking credentials to github:
+secret_key
+sqldatabasename
+sqlpassword
+sqlserver
+sqlusername
+secrets/
+docker-compose.yml
+hash_password.py
+
+# to avoid leaking references to github:
+references
+references/
+
+# because this relates to my personal config:
+config/www.webref.conf
+
+# general things to ignore:
+build/
+dist/
+*.egg-info/
+*.egg
+*.py[cod]
+__pycache__/
+*.so
+*~
+*.tar
+*.tar.gz
+
+# due to using tox, pytest, vscode:
+.tox
+.cache
+.eggs/
+.vscode/
+
+# due to Mac:
+**/.DS_Store

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+RUN apt update
+
+RUN useradd -ms /bin/bash webref
+WORKDIR /home/webref
+
+COPY config/requirements.txt .
+
+RUN chown -R webref:webref .
+
+# install web app and wsgi server:
+USER root
+RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache ppf.webref==0.1.1
+
+# run wsgi server:
+USER webref
+CMD ["waitress-serve", "--call", "ppf.webref:create_app"]

Makefile

@@ -0,0 +1,12 @@
+VERSION := 0.1
+
+webref-$(VERSION).tar.gz: Dockerfile config/requirements.txt Makefile
+	docker build -t webref:$(VERSION) .
+	docker save webref:$(VERSION) | gzip > webref-$(VERSION).tar.gz
+
+up: webref-$(VERSION).tar.gz
+	VERSION=$(VERSION) docker compose up --detach
+
+clean:
+	VERSION=$(VERSION) docker-compose down --rmi all --volumes --remove-orphans
+	rm -f webref-$(VERSION).tar.gz

config/requirements.txt

@@ -0,0 +1,21 @@
+bcrypt==4.1.2
+blinker==1.7.0
+click==8.1.7
+Flask==3.0.0
+Flask-Bcrypt==1.0.1
+Flask-Login==0.6.3
+Flask-SQLAlchemy==3.1.1
+flask-talisman==1.1.0
+Flask-WTF==1.2.1
+greenlet==3.0.3
+itsdangerous==2.1.2
+Jinja2==3.1.2
+MarkupSafe==2.1.3
+plumbum==1.8.2
+ppf-jabref==0.1.0
+PyMySQL==1.1.0
+SQLAlchemy==2.0.24
+typing_extensions==4.9.0
+Werkzeug==3.0.1
+WTForms==3.1.1
+waitress==2.1.2

docker-compose_templ.yml

@@ -0,0 +1,24 @@
+services:
+    webref:
+        image: webref:${VERSION}
+        ports:
+            - "7000:8080"
+        volumes:
+            - <path to refs>:/usr/local/lib/python3.11/site-packages/ppf/webref/references
+        secrets:
+            - secret_key
+            - sqlusername
+            - sqlpassword
+            - sqlserver
+            - sqldatabasename
+secrets:
+    secret_key:
+        file: ./secrets/secret_key
+    sqlusername:
+        file: ./secrets/sqlusername
+    sqlpassword:
+        file: ./secrets/sqlpassword
+    sqlserver:
+        file: ./secrets/sqlserver
+    sqldatabasename:
+        file: ./secrets/sqldatabasename

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+Everyone interacting in this project is expected to follow the [PSF Code of
+Conduct]. This includes all infrastructure used in the development, such as
+codebases, issue trackers, chat rooms, and mailing lists.
+
+In general, this means that everyone is expected to be **open**,
+**considerate**, and **respectful** of others no matter what their position is
+within the project.
+
+
+## Reporting
+
+All incidents should be reported by emailing [email protected].
+
+[PSF Code of Conduct]: https://www.python.org/psf/conduct/

docs/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# How to contribute
+
+Thank for considering a contribution! Any help is greatly appreciated.
+
+
+## Did you find an issue?
+
+* Check whether your issue has already been reported by searching under
+  [existing issues](https://github.com/adrianschlatter/docker.webref/issues).
+
+* If don't find an issue addressing the problem, open a new issue.
+
+* Choose a meaningful title, describe clearly what you consider to be a
+  problem.
+
+* If possible, provide example code or other means to make it easy for a
+  maintainer to reproduce your problem.
+
+
+## Contributing Code
+
+You want to help with a bug or contribute a feature? The [development
+docs](./dev/DEVDOCS.md) might help you along. 
+
+You already have a solution for an issue or a new feature? All the better! A
+pull request ("PR") is what you want to do.
+
+* Open a new
+  [pull-request](https://github.com/adrianschlatter/docker.webref/pulls)
+  with your patch.
+
+* Try to create PRs that address a specific issue/feature/topic.
+
+* Avoid PRs containing an assortment of unrelated fixes and features. Better
+  split it into separate PRs for each topic.
+
+* Clean up your code before creating a pull request: Remove code that you have
+  commented out for debugging, remove test code you have added.
+
+* Make sure the PR's description clearly describes the problem and your
+  solution. Include relevant issue numbers if appropriate.
+
+* You increase the chances of quick acceptance of your PR significantly if you
+  have taken measures to assure quality (such as writing and passing tests).
+
+
+## Final remarks
+
+Currently, docker.webref is maintained in the spare time of a single person
+having a family and a job. If you do not get immediate feedback to your issue
+or pull request, please have some patience.

docs/README.md

@@ -0,0 +1,114 @@
+# docker.webref
+
+docker.webref packs [ppf.webref](https://github.com/adrianschlatter/ppf.webref)
+into a Docker container. `ppf.webref` is a web interface to your JabRef
+database (see [ppf.webref](https://github.com/adrianschlatter/ppf.webref) for
+details).
+
+Create a JabRef database (using your normal JabRef) and configure
+`docker.webref` to point to this database. Voila: Your references just became
+accessible worldwide.
+
+Note: `ppf.webref` and therefore `docker.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.
+
+<p align="middle">
+<img alt="Screenshot" src="imgs/webref_screenshot.png" height=180>
+</p>
+
+
+# Installation
+
+You need:
+
+* JabRef: To create, edit, and extend your library
+* Docker: To create and run docker images
+
+
+Steps:
+
+* Clone this repo
+* Create a suitable docker-compose.yml (use
+  [docker-compose_templ.yml](../docker-compose_templ.yml) as a starting point)
+* run (in the directory of your `docker-compose.yml`
+```shell
+make
+```
+* generate a secret_key for you web app (required to encrypt cookies):
+ ```shell
+ python -c 'import secrets; print(secrets.token_hex())'
+ ```
+* Create the following text files (assuming you did not change the paths
+  from the template docker-compose.yml):
+  - ./secrets/sqlserver: The sql server holding your JabRef database
+  - ./secrets/sqldatabasename: The name of your JabRef database 
+  - ./secrets/sqlusername: Username used to access your JabRef database
+  - ./secrets/sqlpassword: Password for that username
+  - ./secrets/secret_key: Your secret key generated above
+* Run
+```make up```
+* Point your webbrowser to localhost:7000 (or where you configured your
+  `docker.webref` to be)
+
+This will start the `docker.webref` container on your local machine which is
+nice for testing. To get the most out of `docker.webref`, you will probably
+want to run this docker container on a web server.
+
+The website will present a login form. However, as we have not created any
+users yet, we can't login. We have to create a user first. This is currently a
+bit awkward - don't complain, have a look at the version number, instead. Begin
+by starting a shell inside your running docker container:
+
+```shell
+docker exec -it <container_id> '/bin/bash'
+```
+
+(Find your container_id using ```docker container ls```.) Then, inside that
+shell, 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. To get out of the container-shell, type <Ctrl-D>.
+
+Now we are able to log in.
+
+
+# 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: Dockerizes `ppf.webref-0.1.1`.