From 8971d24b943a6e703c65cafd4fdc823118cad7b0 Mon Sep 17 00:00:00 2001 From: Nils Steinger <git@n-st.de> Date: Fri, 6 Nov 2020 18:12:22 +0100 Subject: [PATCH 1/3] Clarify instructions for development setup --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 691c0bb9..40b75a0f 100644 --- a/README.md +++ b/README.md @@ -60,10 +60,13 @@ Python requirements are listed in ``requirements.txt``. They can be installed wi **Development Server** -To start the application for development use ``python manage.py runserver 0:8000`` from the root directory. *Do not use this for deployment!* -In your browser, access ``http://127.0.0.1:8000/`` and continue from there. +To start the application for development, in the root directory, + +1. activate virtualenv ``source venv/bin/activate`` +1. start development server ``python manage.py runserver 0:8000`` +1. In your browser, access ``http://127.0.0.1:8000/admin/`` and continue from there. ### Deployment Setup -- GitLab From b5deebbc9a6b995f6f91c44b27288e2ec80f6b0c Mon Sep 17 00:00:00 2001 From: Nils Steinger <git@n-st.de> Date: Fri, 6 Nov 2020 18:38:19 +0100 Subject: [PATCH 2/3] Move setup instructions to separate file --- INSTALL.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 114 +++-------------------------------------------------- 2 files changed, 113 insertions(+), 109 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..040a5aa8 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,108 @@ +# AK Planning: Setup + +This repository contains a Django project with several apps. + + +## Requirements + +AKPlanning has two types of requirements: System requirements are dependent on operating system and need to be installed manually beforehand. Python requirements will be installed inside a virtual environment (strongly recommended) during setup. + + +### System Requirements + +* Python 3.7 incl. development tools +* Virtualenv +* for production using uwsgi: + * C compiler e.g. gcc + * uwsgi + * uwsgi Python3 plugin +* for production using Apache (in addition to uwsgi) + * the mod proxy uwsgi plugin for apache2 + + +### Python Requirements + +Python requirements are listed in ``requirements.txt``. They can be installed with pip using ``-r requirements.txt``. + + +## Development Setup + +* create a new directory that should contain the files in future, e.g. ``mkdir AKPlanning`` +* change into that directory ``cd AKPlanning`` +* clone this repository ``git clone URL .`` + + +### Automatic Setup + +1. execute the setup bash script ``Utils/setup.sh`` + + +### Manual Setup + +1. setup a virtual environment using the proper python version ``virtualenv venv -p python3.7`` +1. activate virtualenv ``source venv/bin/activate`` +1. install python requirements ``pip install -r requirements.txt`` +1. setup necessary database tables etc. ``python manage.py migrate`` +1. prepare static files (can be omitted for dev setups) ``python manage.py collectstatic`` +1. compile translations ``python manage.py compilemessages`` +1. create a priviledged user, credentials are entered interactively on CLI ``python manage.py createsuperuser`` +1. deactivate virtualenv ``deactivate`` + + +### Development Server + +**Do not use this for deployment!** + +To start the application for development, in the root directory, + +1. activate virtualenv ``source venv/bin/activate`` +1. start development server ``python manage.py runserver 0:8000`` +1. In your browser, access ``http://127.0.0.1:8000/admin/`` and continue from there. + + +## Deployment Setup + +This application can be deployed using a web server as any other Django application. +Remember to use a secret key that is not stored in any repository or similar, and disable DEBUG mode (``settings.py``). + +**Step-by-Step Instructions** + +1. log into your system with a sudo user +1. install system requirements +1. create a folder, e.g. ``mkdir /srv/AKPlanning/`` +1. change to the new directory ``cd /srv/AKPlanning/`` +1. clone this repository ``git clone URL .`` +1. setup a virtual environment using the proper python version ``virtualenv venv -p python3.7`` +1. activate virtualenv ``source venv/bin/activate`` +1. update tools ``pip install --upgrade setuptools pip wheel`` +1. install python requirements ``pip install -r requirements.txt`` +1. create the file ``AKPlanning/settings_secrets.py`` (copy from ``settings_secrets.py.sample``) and fill it with the necessary secrets (e.g. generated by ``tr -dc 'a-z0-9!@#$%^&*(-_=+)' < /dev/urandom | head -c50``) (it is a good idea to restrict read permissions from others) +1. if necessary enable uwsgi proxy plugin for Apache e.g.``a2enmod proxy_uwsgi`` +1. edit the apache config to serve the application and the static files, e.g. on a dedicated system in ``/etc/apache2/sites-enabled/000-default.conf`` within the ``VirtualHost`` tag add: + + ``` + Alias /static /srv/AKPlanning/static + <Directory /srv/AKPlanning/static> + Require all granted + </Directory> + + ProxyPassMatch ^/static/ ! + ProxyPass / uwsgi://127.0.0.1:3035/ + ``` + + or create a new config (.conf) file (similar to ``apache-akplanning.conf``) replacing $SUBDOMAIN with the subdomain the system should be available under, and $MAILADDRESS with the e-mail address of your administrator and $PATHTO with the appropriate paths. Copy or symlink it to ``/etc/apache2/sites-available``. Then symlink it to ``sites-enabled`` e.g. by using ``ln -s /etc/apache2/sites-available/akplanning.conf /etc/apache2/sites-enabled/akplanning.conf``. +1. restart Apache ``sudo systemctl restart apache2.service`` +1. create a dedicated user, e.g. ``adduser django`` +1. transfer ownership of the folder to the new user ``chown -R django:django /srv/AKPlanning`` +1. Copy or symlink the uwsgi config in ``uwsgi-akplanning.ini`` to ``/etc/uwsgi/apps-available/`` and then symlink it to ``/etc/uwsgi/apps-enabled/`` using e.g., ``ln -s /srv/AKPlanning/uwsgi-akplanning.ini /etc/uwsgi/apps-available/akplanning.ini`` and ``ln -s /etc/uwsgi/apps-available/akplanning.ini /etc/uwsgi/apps-enabled/akplanning.ini`` +start uwsgi using the configuration file ``uwsgi --ini uwsgi-akplanning.ini`` +1. restart uwsgi ``sudo systemctl restart uwsgi`` +1. execute the update script ``./Utils/update.sh --prod`` + + +## Updates + +To update the setup to the current version on the main branch of the repository use the update script ``Utils/update.sh`` or ``Utils/update.sh --prod`` in production. + +Afterwards, you may check your setup by executing ``Utils/check.sh`` or ``Utils/check.sh --prod`` in production. + diff --git a/README.md b/README.md index 40b75a0f..d60f9f73 100644 --- a/README.md +++ b/README.md @@ -7,115 +7,6 @@ AKPlanning is a tool used for modeling, submitting, scheduling and displaying AK It was built for KIF (German: Konferenz der deutschsprachigen Informatikfachschaften), refer to [the wiki](wiki.kif.rocks) for more Information. -## Setup - -This repository contains a Django project with several apps. - - -### Requirements - -AKPlanning has two types of requirements: System requirements are dependent on operating system and need to be installed manually beforehand. Python requirements will be installed inside a virtual environment (strongly recommended) during setup. - - -#### System Requirements - -* Python 3.7 incl. development tools -* Virtualenv -* for production using uwsgi: - * C compiler e.g. gcc - * uwsgi - * uwsgi Python3 plugin -* for production using Apache (in addition to uwsgi) - * the mod proxy uwsgi plugin for apache2 - - -#### Python Requirements - -Python requirements are listed in ``requirements.txt``. They can be installed with pip using ``-r requirements.txt``. - - -### Development Setup - -* create a new directory that should contain the files in future, e.g. ``mkdir AKPlanning`` -* change into that directory ``cd AKPlanning`` -* clone this repository ``git clone URL .`` - - -**Automatic Setup** - -1. execute the setup bash script ``Utils/setup.sh`` - - -**Manual Setup** - -1. setup a virtual environment using the proper python version ``virtualenv venv -p python3.7`` -1. activate virtualenv ``source venv/bin/activate`` -1. install python requirements ``pip install -r requirements.txt`` -1. setup necessary database tables etc. ``python manage.py migrate`` -1. prepare static files (can be omitted for dev setups) ``python manage.py collectstatic`` -1. compile translations ``python manage.py compilemessages`` -1. create a priviledged user, credentials are entered interactively on CLI ``python manage.py createsuperuser`` -1. deactivate virtualenv ``deactivate`` - - -**Development Server** - -*Do not use this for deployment!* - -To start the application for development, in the root directory, - -1. activate virtualenv ``source venv/bin/activate`` -1. start development server ``python manage.py runserver 0:8000`` -1. In your browser, access ``http://127.0.0.1:8000/admin/`` and continue from there. - - -### Deployment Setup - -This application can be deployed using a web server as any other Django application. -Remember to use a secret key that is not stored in any repository or similar, and disable DEBUG mode (``settings.py``). - -**Step-by-Step Instructions** - -1. log into your system with a sudo user -1. install system requirements -1. create a folder, e.g. ``mkdir /srv/AKPlanning/`` -1. change to the new directory ``cd /srv/AKPlanning/`` -1. clone this repository ``git clone URL .`` -1. setup a virtual environment using the proper python version ``virtualenv venv -p python3.7`` -1. activate virtualenv ``source venv/bin/activate`` -1. update tools ``pip install --upgrade setuptools pip wheel`` -1. install python requirements ``pip install -r requirements.txt`` -1. create the file ``AKPlanning/settings_secrets.py`` (copy from ``settings_secrets.py.sample``) and fill it with the necessary secrets (e.g. generated by ``tr -dc 'a-z0-9!@#$%^&*(-_=+)' < /dev/urandom | head -c50``) (it is a good idea to restrict read permissions from others) -1. if necessary enable uwsgi proxy plugin for Apache e.g.``a2enmod proxy_uwsgi`` -1. edit the apache config to serve the application and the static files, e.g. on a dedicated system in ``/etc/apache2/sites-enabled/000-default.conf`` within the ``VirtualHost`` tag add: - - ``` - Alias /static /srv/AKPlanning/static - <Directory /srv/AKPlanning/static> - Require all granted - </Directory> - - ProxyPassMatch ^/static/ ! - ProxyPass / uwsgi://127.0.0.1:3035/ - ``` - - or create a new config (.conf) file (similar to ``apache-akplanning.conf``) replacing $SUBDOMAIN with the subdomain the system should be available under, and $MAILADDRESS with the e-mail address of your administrator and $PATHTO with the appropriate paths. Copy or symlink it to ``/etc/apache2/sites-available``. Then symlink it to ``sites-enabled`` e.g. by using ``ln -s /etc/apache2/sites-available/akplanning.conf /etc/apache2/sites-enabled/akplanning.conf``. -1. restart Apache ``sudo systemctl restart apache2.service`` -1. create a dedicated user, e.g. ``adduser django`` -1. transfer ownership of the folder to the new user ``chown -R django:django /srv/AKPlanning`` -1. Copy or symlink the uwsgi config in ``uwsgi-akplanning.ini`` to ``/etc/uwsgi/apps-available/`` and then symlink it to ``/etc/uwsgi/apps-enabled/`` using e.g., ``ln -s /srv/AKPlanning/uwsgi-akplanning.ini /etc/uwsgi/apps-available/akplanning.ini`` and ``ln -s /etc/uwsgi/apps-available/akplanning.ini /etc/uwsgi/apps-enabled/akplanning.ini`` -start uwsgi using the configuration file ``uwsgi --ini uwsgi-akplanning.ini`` -1. restart uwsgi ``sudo systemctl restart uwsgi`` -1. execute the update script ``./Utils/update.sh --prod`` - - -### Updates - -To update the setup to the current version on the main branch of the repository use the update script ``Utils/update.sh`` or ``Utils/update.sh --prod`` in production. - -Afterwards, you may check your setup by executing ``Utils/check.sh`` or ``Utils/check.sh --prod`` in production. - - ## Structure This repository contains a Django project called AKPlanning. The functionality is encapsulated into Django apps: @@ -127,6 +18,11 @@ This repository contains a Django project called AKPlanning. The functionality i 1. **AKPlan**: This app displays AKs and where/when they will take place for each event. Views are optimised according to usage/purpose. +## Setup instructions + +See [INSTALL.md](INSTALL.md). + + ## Developer Notes * to regenerate translations use ````python manage.py makemessages -l de_DE --ignore venv```` * to create a data backup use ````python manage.py dumpdata --indent=2 > db.json --traceback```` \ No newline at end of file -- GitLab From 2c867a4b188b22d909957279f29188866074d62d Mon Sep 17 00:00:00 2001 From: Nadja Geisler <ngeisler@fachschaft.informatik.tu-darmstadt.de> Date: Fri, 6 Nov 2020 19:20:41 +0100 Subject: [PATCH 3/3] add remark for update and check script in README --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d60f9f73..7e70a955 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,14 @@ This repository contains a Django project called AKPlanning. The functionality i ## Setup instructions -See [INSTALL.md](INSTALL.md). +See [INSTALL.md](INSTALL.md) for detailed instructions on development and production setups. + +To update the setup to the current version on the main branch of the repository use the update script ``Utils/update.sh`` or ``Utils/update.sh --prod`` in production. + +Afterwards, you may check your setup by executing ``Utils/check.sh`` or ``Utils/check.sh --prod`` in production. + ## Developer Notes * to regenerate translations use ````python manage.py makemessages -l de_DE --ignore venv```` -* to create a data backup use ````python manage.py dumpdata --indent=2 > db.json --traceback```` \ No newline at end of file +* to create a data backup use ````python manage.py dumpdata --indent=2 > db.json --traceback```` -- GitLab