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 codes 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.

Review the make targets in the Makefile!

#. ``make dev``
#. ``make test``
#. ``make wsl``
#. ``make prod``


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

To setup a "functional testing" environment on your personal workstation, open two 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 web server to serve index.html:

.. code-block:: bash

 make http

Now browse to http://127.0.0.1:8000 and index.html will load.
This has an embedded copy of Remarkbox which is also running on localhost.

If you attempt to log in, a verification one-time-password code will be sent over SMTP to log in!
If you do not have an SMTP server the socket error will log email to console when in development.


New Environments
================

If your deployment is brand new, you don't need to run any migrations.

To create all the schemas & tables in your database, run these steps:

Activate the virtual environment:

.. code-block:: bash

 source env/bin/activate
   
Create all the schemas & tables in your database

.. code-block:: bash

 env/bin/remarkbox_init_db development.ini

You should however run this to stamp the database as ready:

.. code-block:: bash

 alembic -c development.ini stamp head


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

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 indices."

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

Below is a brief README section that explains how to set up a virtual environment in `~/remarkbox-env`, create a data directory in `~/remarkbox-data` (for your `development.ini` and SQLite file), and then run the development server using Waitress. It also lists the additional meta packages for production and testing.


Operating a server with Python packages instead of source
==================================================================

1. **Create Your Virtual Environment and Data Directory:**

.. code-block:: bash

   python3 -m venv ~/remarkbox-env
   mkdir -p ~/remarkbox-data

2. **Create a config file**

.. code-block:: bash

   cd ~/remarkbox-data
   wget "https://git.unturf.com/engineering/remarkbox/remarkbox/-/raw/main/development.ini"

3. **Activate the Virtual Environment:**

.. code-block:: bash

   source ~/remarkbox-env/bin/activate

4. **Install remarkbox Core and Development Extras (waitress server):**

.. code-block:: bash

   pip install remarkbox
   pip install remarkbox[dev]

   # optional themes.
   pip install git+https://git.unturf.com/engineering/remarkbox/remarkbox-theme-meta.git
   pip install git+https://git.unturf.com/engineering/remarkbox/remarkbox-westworld.git

*Note: A plain `pip install remarkbox` automatically chooses between the Python‑3 or WSL requirements.*

5. **Create Database**

.. code-block:: bash

   remarkbox_init_db development.ini

.. code-block:: bash

   alembic -c development.ini stamp head

6. **Start the Development Server (Waitress):**

.. code-block:: bash

   pserve development.ini --reload

**Additional Meta Packages:**  
For production and testing, you can also install:

- ``pip install remarkbox[prod]``
- ``pip install remarkbox[test]``



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

Sometimes (all the times) it's nice to clear all the test comments from
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)

 # iterate 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 sqlalchemy session.
 request.dbsession.flush()

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

Contributing
===================

* Establish communication with Russell or another admin to bless your git.unturf.com gitlab account & put you into the proper roles.
* Russell should see your account request but due to spam you have to ask him directly for approval via email or some other means of comms.
* Clone repo & make commits
* Create merge requests, we automatically run the unit & headless functional tests on each commit
* On merge we release to the production site & see the change across users.

Optionally, format your code.

This is not set in stone, but if you want to use a formatter this is the path for now!

**Python**
  black (manual)

**Jinja2**
  None (not needed, neither is an HTML formatter)

**JavaScript**
  Prettier or biome (manual)

**CSS**
  Prettier or biome (manual)

Licence
=====================

All code contributed goes into the public domain.