diff --git a/README.md b/README.md
index 4dad047..a4ae322 100644
--- a/README.md
+++ b/README.md
@@ -18,16 +18,25 @@ This can be done using the system package management, downloaded from [http://ww
     - `./configure --prefix=$HOME/.local/bin`
     - `make && make install`
 
+This will install python locally under `~/.local/bin`. Make sure to add it to your `PATH` (edit `~/.profile` in OSX or FreeBSD).
+
 Next install pip (if not yet installed):
 
-    python36 -m ensurepip --user
+    python3.6 -m ensurepip --user
 
 This will install pip in your account under `~/.local/bin`.
 In the end you should be able to run `pip3 --version` and `python3 -c "import sqlite3"` without errors (sometimes `pip3` is `pip`, `pip3.6` or `pip-3.6`).
 
 Install additional python packages locally on the user area:
 
-    pip install --user tornado sqlalchemy pyyaml pygments markdown bcrypt networkx
+    pip3 install --user \
+        tornado \
+        sqlalchemy \
+        pyyaml \
+        pygments \
+        markdown \
+        bcrypt \
+        networkx
 
 These are usually installed under
 
@@ -46,23 +55,71 @@ Replace USER by your bitbucket username:
     cd path/to/some/directory
     git clone https://USER@bitbucket.org/USER/aprendizations.git
 
-A directory aprendizations will be created with the software:
+A directory `aprendizations` will be created with the software:
 
     cd aprendizations
 
 ## Configuration
 
+### Database
+
 First we need to create a database:
 
-    ./initdb.py                 # initialize with a single user `0`  and empty password
+    ./initdb.py                 # initialize user `0` and empty password
+    ./initdb.py --pw alibaba    # initialize user `0` and given password
     ./initdb.py --help          # for the available options
 
+### SSL Certificates
+
 We also need certificates for https. Generate selfsigned certificates using openssl:
 
-    cd certs
     openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
-    cd ..
+
+and place them in `aprendizations/certs`.
+
+### Testing
 
 Run a demonstration:
 
-    ./serve.py
+    ./serve.py demo/demo.yaml
+
+and open a browser at `https://127.0.0.1:8443`.
+
+### Firewall configuration
+
+Ports 80 and 443 are only usable by root. For security reasons it is better to run the server as a regular user on higher ports like 8080 for http and 8443 for https. In this case, we should configure port forwarding in the firewall to redirect incoming tcp traffic from 80 to 8080 and 443 to 8443.
+
+#### FreeBSD and pf
+
+Edit `/etc/pf.conf`:
+
+    ext_if="em0"
+    rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
+    rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443
+
+or `ext_if="vtnet0"` for guest additions under virtual box.
+
+Edit `rc.conf`
+
+    pf_enable="YES"
+    pf_flags=""
+    pf_rules="/etc/pf.conf"
+
+    # optional logging:
+    pflog_enable="YES"
+    pflog_flags=""
+    pflog_logfile="/var/log/pflog"
+
+Reboot.
+
+## Troubleshooting
+
+#### 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 exception.
+
+To correct in FreeBSD, edit `~/.login_conf` to use UTF-8, for example:
+
+    me:\
+            :charset=UTF-8:\
+            :lang=en_US.UTF-8:
diff --git a/app.py b/app.py
index ac9284c..be8bfe6 100644
--- a/app.py
+++ b/app.py
@@ -178,14 +178,14 @@ class LearnApp(object):
 
         # Builds factories for each node
         for n in g.nodes_iter():
-            fullpath = path.join(prefix, n)
-            # if name is directory defaults to "prefix/questions.yaml"
+            fullpath = path.expanduser(path.join(prefix, n))
             if path.isdir(fullpath):
-                filename = path.join(fullpath, "questions.yaml")
+                # if directory defaults to "prefix/questions.yaml"
+                fullpath = path.join(fullpath, "questions.yaml")
 
-            if path.isfile(filename):
-                logger.info(f'Loading questions from "{filename}"')
-                questions = load_yaml(filename, default=[])
+            if path.isfile(fullpath):
+                logger.info(f'Loading questions from "{fullpath}"')
+                questions = load_yaml(fullpath, default=[])
                 for q in questions:
                     q['path'] = fullpath
 
diff --git a/questions.py b/questions.py
index bbbbe24..0b7559f 100644
--- a/questions.py
+++ b/questions.py
@@ -406,7 +406,7 @@ class QFactory(object):
     # i.e. a question object (radio, checkbox, ...).
     # -----------------------------------------------------------------------
     def generate(self):
-        logger.debug(f'generate "{self.question["ref"]}"')
+        logger.debug(f'Generating "{self.question["ref"]}"')
         # Shallow copy so that script generated questions will not replace
         # the original generators
         q = self.question.copy()
--
libgit2 0.21.2