From 03bdcdf9b455a150a958ddccb3bfcdff6dbc6795 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20L=C3=A9vy?= Date: Tue, 18 Aug 2020 16:32:00 -0400 Subject: [PATCH 1/4] Fix markdown rules --- README.md | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 29d665f5c..d96a5d4de 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,17 @@ # Recipes ![CI](https://github.com/vabene1111/recipes/workflows/Continous%20Integration/badge.svg?branch=develop) + Recipes is a Django application to manage, tag and search recipes using either built in models or external storage providers hosting PDF's, Images or other files. ![Preview](docs/preview.png) [More Screenshots](https://imgur.com/a/V01151p) -### Features +## Features - :package: **Sync** files with Dropbox and Nextcloud (more can easily be added) - :mag: Powerful **search** with Djangos [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity) - :label: Create and search for **tags**, assign them in batch to all files matching certain filters -- :page_facing_up: **Create recipes** locally within a nice, standardized web interface +- :page_facing_up: **Create recipes** locally within a nice, standardized web interface - :arrow_down: **Import recipes** from thousands of websites supporting [ld+json or microdata](https://schema.org/Recipe) - :iphone: Optimized for use on **mobile** devices like phones and tablets - :shopping_cart: Generate **shopping** lists from recipes @@ -21,22 +22,24 @@ Recipes is a Django application to manage, tag and search recipes using either b - :envelope: Export and import recipes from other users - :heavy_plus_sign: Many more like recipe scaling, image compression, cookbooks, printing views, ... -This application is meant for people with a collection of recipes they want to share with family and friends or simply +This application is meant for people with a collection of recipes they want to share with family and friends or simply store them in a nicely organized way. A basic permission system exists but this application is not meant to be run as a public page. Some Documentation can be found [here](https://github.com/vabene1111/recipes/wiki) -# Installation + +## Installation The docker image (`vabene1111/recipes`) simply exposes the application on port `8080`. You may choose any preferred installation method, the following are just examples to make it easier. ### Docker-Compose -2. Choose one of the included configurations [here](docs/docker). -2. Download the environment (config) file template and fill it out `wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env ` +1. Choose one of the included configurations [here](docs/docker). +2. Download the environment (config) file template and fill it out `wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env` 3. Start the container `docker-compose up -d` -4. Open the page to create the first user. Alternatively use `docker-compose exec web_recipes createsuperuser` +4. Open the page to create the first user. Alternatively use `docker-compose exec web_recipes createsuperuser` ### Manual -**Python >= 3.8** is required to run this! + +**Python >= 3.8** is required to run this! Copy `.env.template` to `.env` and fill in the missing values accordingly. Make sure all variables are available to whatever serves your application. @@ -45,6 +48,7 @@ Otherwise simply follow the instructions for any django based deployment (for example [this one](http://uwsgi-docs.readthedocs.io/en/latest/tutorials/Django_and_nginx.html)). ## Updating + While intermediate updates can be skipped when updating please make sure to **read the release notes** in case some special action is required to update. 0. Before updating it is recommended to **create a backup!** @@ -57,25 +61,27 @@ While intermediate updates can be skipped when updating please make sure to **re You can find a basic kubernetes setup [here](docs/k8s/). Please see the README in the folder for more detail. ## Contributing + Pull Requests and ideas are welcome, feel free to contribute in any way. For any questions on how to work with django please refer to their excellent [documentation](https://www.djangoproject.com/start/). ### Translating + There is a [transifex project](https://www.transifex.com/django-recipes/django-cookbook/) project to enable community driven translations. If you want to contribute a new language or help maintain an already existing one feel free to create a transifex account (using the link above) and request to join the project. It is also possible to provide the translations directly by creating a new language using `manage.py makemessages -l -i venv`. Once finished simply open a PR with the changed files. ## License + Beginning with version 0.10.0 the code in this repository is licensed under the [GNU AGPL v3](https://www.gnu.org/licenses/agpl-3.0.de.html) license with an [common clause](https://commonsclause.com/) selling exception. See [LICENSE.md](https://github.com/vabene1111/recipes/blob/develop/LICENSE.md) for details. **Reasoning** +**This software and *all* its features are and will always be free for everyone to use and enjoy.** -#### This software and **all** its features are and will always be free for everyone to use and enjoy. - -The reason for the selling exception is that a significant amount of time was spend over multiple years to develop this software. +The reason for the selling exception is that a significant amount of time was spend over multiple years to develop this software. A payed hosted version which will be identical in features and code base to the software offered in this repository will likely be released in the future (including all features needed to sell a hosted version as they might also be useful for personal use). -This will not only benefit me personally but also everyone who self-hosts this software as any profits made trough selling the hosted option +This will not only benefit me personally but also everyone who self-hosts this software as any profits made trough selling the hosted option allow me to spend more time developing and improving the software for everyone. Selling exceptions are [approved by Richard Stallman](http://www.gnu.org/philosophy/selling-exceptions.en.html) and the -common clause license is very permissive (see the [FAQ](https://commonsclause.com/)). \ No newline at end of file +common clause license is very permissive (see the [FAQ](https://commonsclause.com/)). From 5d5c5a8597d29d820c7740f279a2abf1fe3fa3d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20L=C3=A9vy?= Date: Wed, 19 Aug 2020 17:32:28 -0400 Subject: [PATCH 2/4] Instructions for manual installation --- README.md | 6 +- docs/manual_install/Readme.md | 143 ++++++++++++++++++++++++++++++++++ 2 files changed, 144 insertions(+), 5 deletions(-) create mode 100644 docs/manual_install/Readme.md diff --git a/README.md b/README.md index d96a5d4de..bad3bec07 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,7 @@ The docker image (`vabene1111/recipes`) simply exposes the application on port ` **Python >= 3.8** is required to run this! -Copy `.env.template` to `.env` and fill in the missing values accordingly. -Make sure all variables are available to whatever serves your application. - -Otherwise simply follow the instructions for any django based deployment -(for example [this one](http://uwsgi-docs.readthedocs.io/en/latest/tutorials/Django_and_nginx.html)). +Refer to [manual install](docs/manual_install) for detailled instructions. ## Updating diff --git a/docs/manual_install/Readme.md b/docs/manual_install/Readme.md new file mode 100644 index 000000000..f80dc0cbb --- /dev/null +++ b/docs/manual_install/Readme.md @@ -0,0 +1,143 @@ +# Manual installation instructions + +These intructions are inspired from a standard django/gunicorn/postgresql instructions ([for example](https://www.digitalocean.com/community/tutorials/how-to-set-up-django-with-postgres-nginx-and-gunicorn-on-ubuntu-16-04)) + +**Important note:** Be sure to use pyton3.8 and pip related to python 3.8. Depending on your distribution calling `python` or `pip` will use python2 instead of pyton 3.8. + +## Prerequisites + +*Optional*: create a virtual env and activate it + +Download the latest release from + +Install postgresql requirements: `sudo apt install libpq-dev postgresql` +Install project requirements: `pip3.8 install -r requirements.txt` + +## Setup postgresql + +Run `sudo -u postgres psql` + +In the psql console: + +```sql +CREATE DATABASE djangodb; +CREATE USER djangouser WITH PASSWORD 'password'; +GRANT ALL PRIVILEGES ON DATABASE djangodb TO djangouser; +ALTER DATABASE djangodb OWNER TO djangouser; + +--Maybe not necessary, but should be faster: +ALTER ROLE djangouser SET client_encoding TO 'utf8'; +ALTER ROLE djangouser SET default_transaction_isolation TO 'read committed'; +ALTER ROLE djangouser SET timezone TO 'UTC'; + +--Grant superuser right to your new user, it will be removed later +ALTER USER djangouser WITH SUPERUSER; +``` + +Move or copy `.env.template` to `.env` and update it with relevent values. For example: + +```env +# only set this to true when testing/debugging +# when unset: 1 (true) - dont unset this, just for development +DEBUG=0 + +# hosts the application can run under e.g. recipes.mydomain.com,cooking.mydomain.com,... +#ALLOWED_HOSTS=* + +# random secret key, use for example base64 /dev/urandom | head -c50 to generate one +SECRET_KEY=TOGENERATE + +# add only a database password if you want to run with the default postgres, otherwise change settings accordingly +DB_ENGINE=django.db.backends.postgresql_psycopg2 +POSTGRES_HOST=localhost +POSTGRES_PORT=5432 +POSTGRES_USER=djangouser +POSTGRES_PASSWORD=password +POSTGRES_DB=djangodb + +# Serve mediafiles directly using gunicorn. Basically everyone recommends not doing this. Please use any of the examples +# provided that include an additional nxginx container to handle media file serving. +# If you know what you are doing turn this back on (1) to serve media files using djangos serve() method. +# when unset: 1 (true) - this is temporary until an appropriate amount of time has passed for everyone to migrate +GUNICORN_MEDIA=0 + + +# allow authentication via reverse proxy (e.g. authelia), leave of if you dont know what you are doing +# docs: https://github.com/vabene1111/recipes/tree/develop/docs/docker/nginx-proxy%20with%20proxy%20authentication +# when unset: 0 (false) +REVERSE_PROXY_AUTH=0 + + +# the default value for the user preference 'comments' (enable/disable commenting system) +# when unset: 1 (true) +COMMENT_PREF_DEFAULT=1 +``` + +## Initialize the application + +Execute `export $(cat .env |grep "^[^#]" | xargs)` to load variables from `.env` + +Execute `/python3.8 manage.py migrate` + +And revert superuser from postgres: `sudo -u postgres psql` and `ALTER USER djangouser WITH NOSUPERUSER;` + +Generate static files: `python3.8 manage.py collectstatic` and remember the folder where files have been copied. + +## Setup web services + +### gunicorn + +Create a service that will start gunicorn at boot: `sudo nano /etc/systemd/system/gunicorn_recipes.service` + +And enter these lines: + +```service +[Unit] +Description=gunicorn daemon for recipes +After=network.target + +[Service] +Type=simple +Restart=always +RestartSec=3 +Group=www-data +WorkingDirectory=/media/data/recipes +EnvironmentFile=/media/data/recipes/.env +ExecStart=/opt/.pyenv/versions/3.8.5/bin/gunicorn --error-logfile /tmp/gunicorn_err.log --log-level debug --capture-output --bind unix:/media/data/recipes/recipes.sock recipes.wsgi:application + +[Install] +WantedBy=multi-user.target +``` + +*Note*: `-error-logfile /tmp/gunicorn_err.log --log-level debug --capture-output` are usefull for debugging and can be removed later + +*Note2*: Fix the path in the `ExecStart` line to where you gunicorn and recipes are + +Finally, run `sudo systemctl enable gunicorn_recipes.service` and `sudo systemctl start gunicorn_recipes.service`. You can check that the service is correctly started with `systemctl status gunicorn_recipes.service` + +### nginx + +Now we tell nginx to listen to a new port and forward that to gunicorn. `sudo nano /etc/nginx/sites-available/recipes.conf` + +And enter these lines: + +```nginx +server { + listen 8002; + #access_log /var/log/nginx/access.log; + #error_log /var/log/nginx/error.log; + + # serve media files + location /static { + alias /media/data/recipes/staticfiles; + } + + location / { + proxy_pass http://unix:/media/data/recipes/recipes.sock; + } +} +``` + +*Note*: Enter the correct path in static and proxy_pass lines. + +Enable the website `sudo ln -s /etc/nginx/sites-available/recipes.conf /etc/nginx/sites-enabled` and restart nginx : `sudo systemctl restart nginx.service` From c5edeb7e8f78c7968194ab976c9cd0032dbaeed8 Mon Sep 17 00:00:00 2001 From: Mwoua Date: Wed, 19 Aug 2020 18:09:23 -0400 Subject: [PATCH 3/4] Missing alias for media files --- docs/manual_install/Readme.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/manual_install/Readme.md b/docs/manual_install/Readme.md index f80dc0cbb..d5138ca6e 100644 --- a/docs/manual_install/Readme.md +++ b/docs/manual_install/Readme.md @@ -131,6 +131,10 @@ server { location /static { alias /media/data/recipes/staticfiles; } + + location /media { + alias /media/data/recipes/mediafiles; + } location / { proxy_pass http://unix:/media/data/recipes/recipes.sock; From 7acd72ff3a9126eec41b21995285ce0893044aa6 Mon Sep 17 00:00:00 2001 From: Mwoua Date: Fri, 21 Aug 2020 09:12:57 -0400 Subject: [PATCH 4/4] Clone master instead of getting release --- docs/manual_install/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual_install/Readme.md b/docs/manual_install/Readme.md index d5138ca6e..0781fbc0c 100644 --- a/docs/manual_install/Readme.md +++ b/docs/manual_install/Readme.md @@ -8,7 +8,7 @@ These intructions are inspired from a standard django/gunicorn/postgresql instru *Optional*: create a virtual env and activate it -Download the latest release from +Get the last version from the repository: `git clone https://github.com/vabene1111/recipes.git -b master` Install postgresql requirements: `sudo apt install libpq-dev postgresql` Install project requirements: `pip3.8 install -r requirements.txt`