remarkbox/README.rst

Remarkbox
#########

What is RemarkBox?:
  A stand alone question and answer site (forum) or an embedded comments or product reviews service.
  Works anywhere that supports HTML.

Original Developer:
 Russell Ballestrini (https://russell.ballestrini.net)

Project Goals
=============

Note:
 These goals are not in priority order.

#. To be a suitable for:

   * question and answer sites (StackOverflow)
   * embedded comment system for static sites
   * forums
   * product review sections of e-commerce sites

   |

#. To choose popular libraries instead of proper libraries, for example:

   * Github over Bitbucket (seriously considering GitLab)
   * Git over HG Mercurial
   * Jinja2 templates over Mako templates
   * Markdown over ReStructuredText
   * etc

   |

   Basically I have been burned too many times trying to pick the proper
   library or tool for the job, so this time around, I will make effort
   to choose solutions that the majority uses.

#. To be popular

#. To be safe from spammers

#. To be easy to manage and clean up spam if it happens

#. To be passwordless. Registration, verification and authentication happen via one-time-password links sent via email.

#. To scale horizontally

#. To be multitenant

#. To have low friction for new users to join (posters and commenters)

#. To be engaging for users (posters and commenters)

#. To be search engine optimized

#. To have great test coverage


Local Installation
==================

We utilize a ``Makefile`` to capture targets for building a local Remarkbox environment. Please make sure you have ``make`` installed.

#. ``make dev``
#. ``make test``


Functional testing environment
-------------------------------

To setup a "functional testing" environment on your personal workstation, open three terminal shells.

In the first shell, run a copy of remarkbox using:

.. code-block:: bash

 make serve

In the second shell, run a "mock" simple HTTP webserver to serve index.html:

.. code-block:: bash

 make http

In the third shell, run a "mock" SMTP server to catch log in emails:

.. code-block:: bash

 make smtp

Now browse to http://127.0.0.1:8000 and index.html will load and will have an embeded copy of Remarkbox which running on localhost. 
If you attempt to log in, your third shell will capture the email and you can copy / paste the verification link to log in!



SQL Migrations
===============

If your deployment is brand new, you don't need to run any migrations.
You should however run this to stamp the database as ready:

.. code-block:: bash

 alembic -c development.ini stamp head

Otherwise, it should be safe to run this at anytime to catch your database up:

.. code-block:: bash

 alembic -c development.ini upgrade head

To look at the current revision and the history run these:

.. code-block:: bash

 alembic -c development.ini history
 alembic -c development.ini current

If you ever want to cut a new migration script, you can run this:

.. code-block:: bash

 alembic -c development.ini revision -m "Added email_id column to User table."

Then you can edit / modify the generated ``.py`` file with your changes.

You can also autogenerate a new migration script using `--autogenerate`.
Alembic will prepare a migration script by comparing the state of the
database with the state of the model:

.. code-block:: bash

  alembic -c development.ini revision --autogenerate -m "autogenerated indicies."

You should review the recommended migration script before `upgrade`.


Cleaning the homepage
========================

Sometimes (all the times) it's nice to clear all the test comments from the
the homepage of our marketing site. Use this query.

.. code-block:: sql

  sqlite> UPDATE rb_uri SET data = "https://www.remarkbox.com/?cleaned=2018-09-28" WHERE data = "https://www.remarkbox.com/";
  
  sqlite> SELECT * FROM rb_uri WHERE data LIKE "%https://www.remarkbox.com/?cleaned%";
  1e631dd85d104555b41b300961d2f909|82008b2b178f4daab64c35ab5c5f9b56|https://www.remarkbox.com/?cleaned=2017-11-01
  6b2a4772679611e8ad95040140774501|6b2a42ae679611e8ad95040140774501|https://www.remarkbox.com/?cleaned=2018-09-28



Looking up paying customers
==============================

.. code-block:: sql


 SELECT * FROM rb_pay_what_you_can
     INNER JOIN rb_user ON rb_user.id = rb_pay_what_you_can.user_id
     WHERE amount > 0 and rb_user.stripe_id is not null;



Python Pyramid Shell
==========================

If you want to use an interactive Python interpreter to interact with the Remarkbox app/models and database:

.. code-block:: bash

 pshell development.ini

Here is a full `pshell` script to modify every `Node` who has a `Uri`:

.. code-block:: python

 # begin the database transaction.
 request.tm.begin()

 # get all Uri objects.
 uris = m.uri.get_all_uris(request.dbsession)

 # interate over all Uri objects.
 for uri in uris:
     # modify the Uri's related Node.
     uri.node.has_uri = True
     # add the related Node object to the sqlalchemy session.
     request.dbsession.add(uri.node)

 # flush / commit all changes stored the the sqlachemy session.
 request.dbsession.flush()

 # commit/close the database transaction to really make changes.
 request.tm.commit()