Miguel Barão / perguntations

README.md 3.1 KB

README

  1. Installation
  2. Running a demo
  3. Troubleshooting

Installation

Requirements

The webserver is a python application and requires python3.5 and pip to be installed, plus the following additional packages:

  • CherryPy
  • Mako
  • Markdown
  • PyYAML
  • Pygments
  • SQLAlchemy
  • bcrypt

These can be installed for a single user (recommended), in a python virtual environment or system wide.

pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt

Installing packages in a virtual environment

pyvenv-3.5 venv/perguntations              # or other virtualenv directory
source venv/perguntations/bin/activate     # activate virtualenv

pip install cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt

Installing packages system wide

I personally prefer python packages to be installed for a single user, but if a system wide installation is required, it is probably better to use the operating system package manager instead of pip:

  • Linux: apt-get, etc
  • macOS: macports, etc

Installing perguntations

cd WHERE/TO/PUT/THE/SOFTWARE
git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git

where USERNAME is your account on bitbucket.

Running a demo

The following commands show how to run a demonstration test:

cd WHERE/YOU/INSTALLED/perguntations

# create and initialize database using one of the following methods:
./initdb.py students.csv    # from CSV file
./initdb.py --demo          # initialize with fake students
./initdb.py                 # empty

mv students.db demo/

# edit test configuration and check if everything looks right
vi demo/test.yaml

# edit server configuration and check if everything looks right
vi config/server.conf

We are now ready to run the server:

./serve.py --help            # get help
./serve.py demo/test.yaml    # run demo test

Open the browser at http://127.0.0.1:8080/ and login as user number 0 (administrator) and:

  1. Authorize students by clicking the checkboxes.
  2. Open a different browser at http://127.0.0.1:8080/ and login as one of the authorized students. Answer the questions and submit.

The server can be stoped from the terminal with C.

Troubleshooting

  • The server tries to run python3. If only a python3.5 command is available, you need to set the default python using the OS package manager or manually create a symbolic link:

    • macOS/macports: sudo port select --set python3 python35
    • FreeBSD 11: cd /usr/local/bin; ln -s python3.5 python3

  • If you are getting any UnicodeEncodeError type of errors that's because the terminal is not supporting UTF-8. Try running locale on the terminal and see if there is any error messages. Solutions:

    • debian: fix it with sudo dpkg-reconfigure locales, select your UTF-8 locales and try again.

Contribute

  • Writing questions in yaml format
  • Testing and reporting bugs
  • Code review
  • New features and ideas

Contacts