From 932355bcba78e70366dd953a45dfcb6ccebc06de Mon Sep 17 00:00:00 2001
From: "Gallenkamp, Fabian (bax1489)"
<476-bax1489@users.noreply.gitlab.rrz.uni-hamburg.de>
Date: Fri, 4 Oct 2019 17:09:11 +0200
Subject: [PATCH] Updated Readme deploy and recommendations.
---
README.md | 59 ++++++++++++++++++++++++++++++++++++++++---------------
1 file changed, 43 insertions(+), 16 deletions(-)
diff --git a/README.md b/README.md
index 39a1468..9b8685e 100755
--- a/README.md
+++ b/README.md
@@ -1,8 +1,10 @@
# ansible script to setup multiple [otree](https://otree.readthedocs.io/en/latest/) instances with python env, gninx reverse proxy, supervisor and ufw
-## preparation
+## preparation/ server setup
-### request certificate (PKCS#10 method)
+### mount a different disk permanently, if you use home_folders not on your root disk
+
+### request certificate: PKCS#10-method
1. Establish a ssh connection onto your server.
2. Create empty folder ``mkdir /opt/otree/temp`` and switch into ``cd /opt/otree/temp``.
3. Adapt your config file ``request.conf``.
@@ -35,9 +37,12 @@ Note: Use ``scp mycert.crt user@host:/home/user/`` and ``scp mycert.key user@hos
``git clone https://gitlab.rrz.uni-hamburg.de/bax1489/otree-ansible.git /opt/otree/otree-ansible/``
-### configure playbook
-1. Copy the example config ``cp /opt/otree/otree-ansible/group_vars/otree_servers.yml.example /opt/otree/otree-ansible/group_vars/otree_servers.yml``
+### relocate postgres db, if you're not using your root disk
+
+## change the configuration of the desired otree server with all installed instances
+After setting your desired configuration you are ready to run the playbook.
+1. Only on first install: Copy the example-config-file ``cp /opt/otree/otree-ansible/group_vars/otree_servers.yml.example /opt/otree/otree-ansible/group_vars/otree_servers.yml``
2. Adapt your (inventory-)config with ``nano /opt/otree/otree-ansible/group_vars/otree_servers.yml`` from the provided example accordingly (press "Strg-x", then "j" to save):
```
@@ -74,24 +79,46 @@ otree_users:
### get the otree project on your server
-#### option A: upload otree project directly into ansible project
-1. If no git-repository ``app_repo``-value with your otree configuration is provided, you have to place a copy of the project files (with scp) in ``files/<otree_username>/``.
-
-#### option B: clone via git and provide ssh keys
+#### option A (recommended): clone via git from private repository and provide ssh keys
1. If git-repository ``app_repo`` is provided and the repo is private you have to setup key authentication.
-2. Generate a public-private key pair in the ansible project ``keys/<otree_instance_name>/`` with ``ssh-keygen -f id -t ed25519 -N '' -a 100``
+2. Generate a public-private key pair in the ansible project for **every** instance ``/opt/otree/otree-ansible/keys/<otree_instance_name>/`` with ``ssh-keygen -f id -t ed25519 -N '' -a 100``
3. Upload public key in your git provider (GitLab: User Settings->SSH Keys) and make sure you have access to the specified project in ``app_repo``
-Make sure your ``requirements.txt`` contains "otree==your_desired_version". And now you are ready to run the playbook.
+#### option B: upload otree project directly into ansible project
+1. If no git-repository ``app_repo``-value with your otree configuration is provided, you have to place a copy of the project files (with scp) in ``/opt/otree/otree-ansible/files/<otree_username>/``.
+
+
+## deploy otree instances
+> :zap: **Warning:** Make sure there the are **unique** name definitions in the variable ``otree_users`` for the corresponding subdomain (e.g otree5 for otree5.domain.de) in config-file ``group_vars/otree_servers.yml``. (If there are entries with the same key, the last one defined will be deployed!) Make also sure that there are different **secret-keys**, **redis-slots** and **ports** configured for each instance as described above!
+
+1. Change directory: ``cd /opt/otree/otree-ansible/``.
+2. Modify/verify your settings again: ``nano /opt/otree/otree-ansible/group_vars/otree_servers.yml``.
+3. Run: ``sudo ansible-playbook site.yml`` (with optionally ``-vvv`` to get more information on errors)
+
+> :zap: **Warning:** Set ``override: no`` if the otree_instance is finally deployed and will not change anymore. Remove it only, when you want to **change/delete** settings and deploy it again (Note: This will delete all the data, **always do a backup if you are unsure!**).
+
+## recommendations
+* Set a fixed otree-version in ``requirements_base.txt`` and include there all packages defined in variable ``INSTALLED_APPS `` in ``settings.py``.
+* Always set ``SECRET_KEY = environ.get('OTREE_SECRET_KEY')`` in ``settings.py``.
+* Always set ``ADMIN_PASSWORD = environ.get('OTREE_ADMIN_PASSWORD')``
+* Always set ``DEBUG = (environ.get('OTREE_PRODUCTION') in {None, '', '0'})`` in ``settings.py``.
+
+## FAQ/Troubleshooting
+
+### I see "TypeError: __init__() missing 1 required positional argument: 'on_delete'"?
+Most likely an older otree version needs to be configured. Set ``otree==<desired_version>`` in ``requirements_base.txt``.
+
+### I see "ModuleNotFoundError: No module named '<someexperimentname>'"?
+Remove definition in variable ``SESSION_CONFIGS`` from ``settings.py``.
-## change the configuration
-1. Adapt your inventory-config again with ``nano /opt/otree/otree-ansible/group_vars/otree_servers.yml`` and run the playbook.
+### I see "ModuleNotFoundError: No module named 'otree_tools'"?
+Add ``otree_tools`` in ``requirements_base.txt``.
-## run the playbook
-1. Change directory: ``cd /opt/otree/otree-ansible/``
-2. Run: ``ansible-playbook site.yml --ask-become-pass``
+### How can I restart an otree-instance? Where are the log files?
+Use supervisor: ``sudo supervisorctl restart <otree_instance_name>``. Log files are located in ``/var/log/supervisor/<otree_instance_name>``.
-## FAQ
+### How can I restart nginx? Where are the log files?
+Run: ``sudo systemctl restart nginx.service``. All log files are disabled by default due to data protection purposes. Adapt the ngninx template if logging is really necessary.
### For which operating system is this ansible script optimized?
Currently only Ubuntu 18.04.03 LTS with Python 3.6/3.7 is tested and targeted.
--
GitLab