remarkbox 0.0.1111

remarkbox

This is the codebase that powers both self-hosted & SaaS Remarkbox!

SaaS sites:

• https://www.remarkbox.com

• https://faq.remarkbox.com

• https://meta.remarkbox.com

Self-hosted example running a custom theme:

• https://westworld2.com

What is RemarkBox?:

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

Project Goals

Note:

These goals are not in priority order.

1. To be a suitable for:

   • question and answer sites (StackOverflow)

   • embedded comment system for static sites

   • forums

   • product review sections of e-commerce sites

   
   

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

3. To be popular

4. To be safe from spammers

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

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

7. To scale horizontally

8. To be multitenant

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

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

11. To be search engine optimized

12. To have great test coverage

13. To be easy to create & load custom themes, similar to wordpress

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!

1. make dev

2. make test

3. make wsl

4. 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:

make serve

In the second shell, run a “mock” simple HTTP web server to serve index.html:

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:

source env/bin/activate

Create all the schemas & tables in your database

env/bin/remarkbox_init_db development.ini

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

alembic -c development.ini stamp head

SQL Migrations

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

alembic -c development.ini upgrade head

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

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

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

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:

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:

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

2. Create a config file

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

3. Activate the Virtual Environment:

source ~/remarkbox-env/bin/activate

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

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

remarkbox_init_db development.ini

alembic -c development.ini stamp head

6. Start the Development Server (Waitress):

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.

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

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:

pshell development.ini

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

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

Original Developer:

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