From f3969f9418c94e3ef8458dcbd746de9a9c810974 Mon Sep 17 00:00:00 2001 From: Miguel Barão Date: Thu, 5 Nov 2020 16:21:29 +0000 Subject: [PATCH] add troubleshooting instructions to fix animation issues related to "show animations" or "reduced motion" in Windows and MacOS. --- README.md | 55 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index bb4c947..345ded3 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ sudo port install python37 npm6 # MacOS ``` #### Installing from source - + Make sure that the build tools and libraries are installed: ```sh @@ -54,7 +54,7 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo ### Install pip -Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal. +Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal. To install `pip` from the system package manager: ```sh @@ -70,12 +70,12 @@ python3.7 -m pip install pip # install in user area ``` The latter will install `pip` in your user account under `~/.local/bin`. -In the end you should be able to run `pip --version` and +In the end you should be able to run `pip --version` and `python3 -c "import sqlite3"` without errors. -Sometimes the `pip` command is named `pip3`, +Sometimes the `pip` command is named `pip3`, `pip3.7` or `pip-3.7`. -Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or +Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or `Library/Application Support/pip/pip.conf` (MacOS) and add the lines ```ini @@ -121,7 +121,7 @@ aprendizations --help We need certificates for https. Certificates can be self-signed or validated by a trusted authority. -Self-signed can be used locally for development and testing, but browsers will +Self-signed can be used locally for development and testing, but browsers will complain. LetsEncrypt issues trusted and free certificates, but the server must have a registered publicly accessible domain name. #### Generating selfsigned certificates @@ -141,7 +141,7 @@ sudo pkg install py36-certbot # FreeBSD sudo apt install certbot # Ubuntu ``` -To generate or renew the certificates, ports 80 and 443 have to be accessible. **The firewall and webserver have to be stopped**. +To generate or renew the certificates, ports 80 and 443 have to be accessible. **The firewall and webserver have to be stopped**. ```sh sudo certbot certonly --standalone -d www.example.com # first time @@ -163,7 +163,7 @@ chmod 400 cert.pem privkey.pem ### Database User data is maintained in a sqlite3 database which has to be created manually using the `initdb-aprendizations` command. -The database file should be located in the same directory as the main +The database file should be located in the same directory as the main YAML configuration file. For example, to run the included demo do: @@ -190,16 +190,16 @@ cd demo aprendizations demo.yaml ``` -Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443). -If everything looks good, check at the correct address +Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443). +If everything looks good, check at the correct address `https://www.example.com:8443`. -The option `--debug` provides more verbose logging and might +The option `--debug` provides more verbose logging and might be useful during testing. ### Firewall configuration -Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https. -To access the server in the default https port (443), port forwarding can be configured in the firewall. +Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https. +To access the server in the default https port (443), port forwarding can be configured in the firewall. #### FreeBSD and pf @@ -254,20 +254,20 @@ pip install -U . # updates installed version to latest ## Troubleshooting -To help with troubleshooting, use the option `--debug` when running the server. -This will increase logs in the terminal and will present the python exception +To help with troubleshooting, use the option `--debug` when running the server. +This will increase logs in the terminal and will present the python exception errors in the browser. -Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and +Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and `~/.config/aprendizations/logger-debug.yaml`. If these files do not yet exist, there are examples in `aprendizations/config` that can be copied to `~/.config/aprendizations`. #### UnicodeEncodeError -The server should not generate this error, but when using external scripts to -generate questions or to correct, these scripts can print unicode strings to -stdout. If the terminal does not support unicode, python will generate this +The server should not generate this error, but when using external scripts to +generate questions or to correct, these scripts can print unicode strings to +stdout. If the terminal does not support unicode, python will generate this exception. - FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example: @@ -280,6 +280,22 @@ me:\ - Debian fix: check `locale`... + +#### The application runs but questions do not show up + +Some operating systems have an option to disable animations to try to avoid +motion sickness in some people. Browsers will check this option with the OS and +prevent animate.css library to work. Since questions have several animations, +these will will not work and nothing is shown on the page. + +To fix this issue you need to allow animations in the Operating System: + +- On windows 10, go to System Preferences, search for "Show animations in + windows" and turn it **ON**. +- On MacOS or iOS search for reduced motion and switch it **OFF** + (Preferences -> Acessibility -> Display -> Reduce motion). + + ## FAQ Common database manipulations: @@ -301,4 +317,3 @@ sqlite3 students.db "select student_id, count(topic_id) from studenttopic group # Which questions have more wrong answers? sqlite3 students.db "select count(ref), ref from answers where grade<1.0 group by ref order by count(ref) desc" ``` - -- libgit2 0.21.2