improve documentation

CHANGELOG.rst

@@ -174,7 +174,7 @@ Current
 - Fix: issue `#99 <https://git.ziirish.me/ziirish/burp-ui/issues/99>`_
 - Fix: issue `#100 <https://git.ziirish.me/ziirish/burp-ui/issues/100>`_
 - Fix: issue `#101 <https://git.ziirish.me/ziirish/burp-ui/issues/101>`_
-- `demo <https://demo.ziirish.me/>`_
+- `demo <https://demo.burp-ui.org/>`_
 - API refactoring
 - Security fixes
 - Bugfixes

README.rst

@@ -29,7 +29,8 @@ Demo
 
 A screenshot is worth a thousand words, but a Demo is worth a thousand
 screenshots.
-You can now play with ``Burp-UI`` at `demo.ziirish.me <https://demo.ziirish.me>`_
+You can now play with ``Burp-UI`` at
+`demo.burp-ui.org <https://demo.burp-ui.org/>`_
 
 Credentials:
 
@@ -60,20 +61,17 @@ Documentation
 -------------
 
 The documentation is hosted on `readthedocs <https://readthedocs.org>`_ at the
-following address: `burp-ui.readthedocs.io
-<https://burp-ui.readthedocs.io/en/latest/>`_
+following address: `burp-ui.readthedocs.io`_
 
 FAQ
 ---
 
-A `FAQ <https://burp-ui.readthedocs.io/en/latest/faq.html>`_ is available with
-the documentation.
+A `FAQ`_ is available with the documentation.
 
 Community
 ---------
 
-Please refer to the `Contributing
-<https://burp-ui.readthedocs.io/en/latest/contributing.html>`_ page.
+Please refer to the `Contributing`_ page.
 
 Notes
 -----
@@ -83,10 +81,8 @@ Feel free to report any issues on my `gitlab
 
 I have closed the *github tracker* to have a unique tracker system.
 
-Also please, read the `Contributing
-<https://burp-ui.readthedocs.io/en/latest/contributing.html>`_
-page before reporting any issue to make sure we have all the informations to
-help you.
+Also please, read the `Contributing`_ page before reporting any issue to make
+sure we have all the informations to help you.
 
 See also
 --------
@@ -142,3 +138,6 @@ would not exist without `Burp`_.
 .. _License: https://git.ziirish.me/ziirish/burp-ui/blob/master/LICENSE
 .. _Burp: http://burp.grke.org/
 .. _burpui.cfg: https://git.ziirish.me/ziirish/burp-ui/blob/master/share/burpui/etc/burpui.sample.cfg
+.. _burp-ui.readthedocs.io: https://burp-ui.readthedocs.io/en/latest/
+.. _FAQ: https://burp-ui.readthedocs.io/en/latest/faq.html
+.. _Contributing: https://burp-ui.readthedocs.io/en/latest/contributing.html

docs/faq.rst

@@ -4,7 +4,7 @@ FAQ
 Is there a demo somewhere?
 --------------------------
 
-Yes, you can play with `Burp-UI`_ at `demo.ziirish.me`_. Credentials are:
+Yes, you can play with `Burp-UI`_ at `demo.burp-ui.org`_. Credentials are:
 
 - *admin* / *admin* to play with `Burp-UI`_ as an administrator
 - *demo* / *demo* to play with `Burp-UI`_ as a regular user
@@ -81,6 +81,9 @@ How can I start Burp-UI as a daemon?
 There are several *init scripts* provided by some users available
 `here <https://git.ziirish.me/ziirish/burp-ui/tree/master/contrib>`__.
 
+.. note:: I do not (and cannot) support these scripts. Only the `Gunicorn`_ way
+          is supported.
+
 The recommended way to run `Burp-UI`_ in production is to use `Gunicorn`_. You
 can refer to the `gunicorn <gunicorn.html#daemon>`__ section of this
 documentation for more details.
@@ -134,8 +137,18 @@ Why using SQL?
 --------------
 
 The SQL database is currently used to keep a track of several meta-data.
+Since *v0.5.0*, the SQL database is able to store user preferences.
 Again, it is totally optional to use it.
 
+Why using Celery?
+-----------------
+
+Celery is used to run some asynchronous jobs such as reports computations or
+online restorations.
+
+Computing reports asynchronously allows faster answer especially when you manage
+several dozens of clients.
+
 Burp-UI does not seem to understand the *bind* and *port* options anymore, what should I do?
 --------------------------------------------------------------------------------------------
 
@@ -160,6 +173,16 @@ section.
 Alternatively, you can choose an other compression module by selecting an other
 extension while proceeding the restoration.
 
+I see a lot of *cannot spawn burp process* errors, what can I do?
+-----------------------------------------------------------------
+
+This error means `Burp-UI`_ is not able to communicate with the burp server.
+You should check your logs (both `Burp-UI`_'s and burp server's) to understand
+what is wrong.
+If you are using `Gunicorn`_, it is possible you reached the limit of *status
+children*. You can safely increase the ``max_status_children`` setting in your
+*burp-server.conf* file to 15 (the default is 5).
+
 How can I contribute?
 ---------------------
 
@@ -172,4 +195,4 @@ documentation.
 .. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui
 .. _Gunicorn: http://gunicorn.org/
 .. _README: https://git.ziirish.me/ziirish/burp-ui/blob/master/README.rst
-.. _demo.ziirish.me: https://demo.ziirish.me/
+.. _demo.burp-ui.org: https://demo.burp-ui.org/

docs/gunicorn.rst

@@ -20,9 +20,16 @@ You will then be able to launch `Burp-UI`_ this way:
     gunicorn -k gevent -w 4 'burpui:create_app(conf="/path/to/burpui.cfg")'
 
 
+This will listen to 127.0.0.1:8000 by default. See the ``gunicorn``
+`documentation <http://docs.gunicorn.org/en/stable/settings.html>`__ for
+details.
+
+You will need to add the ``-b 0.0.0.0:5000`` option in order to listen on all
+interfaces on port 5000 for instance.
+
 When using ``gunicorn``, the command line options are not available. Instead,
-run the `Burp-UI`_ ``create_app`` method directly. Here are the parameters you
-can play with:
+you run the `Burp-UI`_ ``create_app`` method directly. Here are the parameters
+you can play with:
 
 - conf: Path to the `Burp-UI`_ configuration file
 - verbose: Verbosity level between 0 and 4
@@ -40,7 +47,7 @@ Advanced usage
 --------------
 
 `Gunicorn`_ supports further settings (see its `documentation
-<http://docs.gunicorn.org/en/stable/>`_ for details).
+<http://docs.gunicorn.org/en/stable/>`__ for details).
 For instance, you would probably like to use the ``-c`` flag with the sample
 configuration file bundled with `Burp-UI`_ in *contrib/gunicorn/burpui_gunicorn.py*.
 
@@ -113,6 +120,14 @@ Now you need to add the *bui-agent1* client to the authorized clients:
     echo "restore_client = bui-agent1" >>/etc/burp/burp-server.conf
 
 
+You will also need to increase the number of status clients by setting
+``max_status_children`` to 15:
+
+::
+
+    echo "max_status_children = 15" >>/etc/burp/burp-server.conf
+
+
 Finally, make sure you set ``bconfcli: /var/lib/burpui/burp.conf`` in your 
 `Burp-UI`_ configuration file (*/etc/burp/burpui.cfg*).
 
@@ -293,11 +308,20 @@ It is using `Gunicorn`_ along with Nginx as described above.
 
 In order to improve performances, `Redis`_ can be used to cache sessions and
 various API calls.
+You can also enable the `celery <celery.html>`_ worker for asynchronous jobs.
+Additionally, you can enable the `SQL <manage.html#database>`_ storage.
+
+The `FAQ <faq.html>`_ answers these questions:
+
+- `Why using redis? <faq.html#why-using-redis>`_
+- `Why using SQL? <faq.html#why-using-sql>`_
+- `Why using Celery? <faq.html#why-using-celery>`_
+
 
 See the `production <advanced_usage.html#production>`_ section of the
 `usage <advanced_usage.html>`_ page.
 
 .. _Gunicorn: http://gunicorn.org/
 .. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui
-.. _demo: https://demo.ziirish.me/
+.. _demo: https://demo.burp-ui.org/
 .. _Redis: http://redis.io/

docs/running.rst

@@ -6,7 +6,7 @@ Flask's `development server <http://flask.pocoo.org/docs/0.12/server/>`_ or you
 can use any of the `deployement options <http://flask.pocoo.org/docs/0.12/deploying/>`_
 provided by Flask.
 
-.. note:: I personaly focus on ``gunicorn`` support for production deployments
+.. note:: I personally focus on ``gunicorn`` support for production deployments
 
 
 Sandboxing

docs/step-by-step.rst

@@ -16,7 +16,6 @@ describe the steps to setup your server from Scratch.
 
 1. `Burp1 server`_ with `Burp-UI`_
 2. `Burp2 server`_ with `Burp-UI`_
-3. `Multiple servers`_ with `bui-agents <buiagent.html>`_
 
 
 Burp1 server