remarkbox 1.0.0

remarkbox

Quick Start: Operating a Server with PyPI or Source Code

This Makefile‑based workflow lets you choose between installing Remarkbox from PyPI packages or directly from the source code (editable mode). Both flows create a virtual environment in ./env and store configuration and SQLite data in the persistent ./data directory.

1. Install Remarkbox

   • For a PyPI Installation, run:

     make install-from-pypi

   • For a Source Installation (editable mode), run:

     make install-from-source

2. Activate the Virtual Environment

   Before running any subsequent commands or scripts (including starting the server or running tests), activate the virtual environment with:

   source env/bin/activate

   Activating the virtual environment ensures that all Python commands (such as pip or pshell) use the packages and settings in ./env rather than your system-wide Python installation. This is crucial for consistency throughout the rest of this document.

3. Start the Development Server

   Once the virtual environment is active, run:

   make serve

Other commands—such as make test, and make http operate within this environment.

For a production installation, additional meta packages are available, for example:

..code-block:: bash

pip install remarkbox[prod]

Remarkbox

This is the codebase that powers both self‑hosted and 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?

Remarkbox is a standalone question and answer site (forum) or an embedded comments/product reviews service that works anywhere HTML is supported.

Project Goals

Note: These goals are not in priority order.

1. Support Multiple Use Cases: - Q&A sites (e.g. StackOverflow) - Embedded comment systems for static sites - Forums - Product review sections on e‑commerce sites

2. Adopt Widely Used Tools: - GitHub (with GitLab under consideration) over Bitbucket - Git instead of Mercurial - Jinja2 templates instead of Mako - Markdown rather than reStructuredText - …and more, choosing solutions trusted by the majority.

3. To be popular

4. To be safe from spammers

5. To be easy to manage and clean up spam

6. To be passwordless – using one‑time-password codes via email for registration and authentication

7. To scale horizontally

8. To be multitenant

9. To minimize friction for new users

10. To be engaging for users

11. To be search engine optimized

12. To have great test coverage

13. To be easy to create and load custom themes (similar to WordPress)

Local Installation

This repository includes a Makefile that automates your local Remarkbox environment setup by creating: - A virtual environment in ./env - A persistent data directory in ./data (which holds your development.ini and SQLite database)

Note: The Makefile handles environment setup and database initialization, so you do not need to run these steps manually.

Functional Testing Environment

To set up a functional testing environment on your workstation, open two terminal shells:

1. In the first shell, start the Remarkbox server:

   make serve

2. In the second shell, run a simple HTTP server (to serve an index.html file):

   make http

Browse to http://127.0.0.1:8000 to view the homepage, which embeds a local copy of Remarkbox. In development, one‑time-password codes are logged to the console if an SMTP server is not available.

SQL Migrations

For new environments, migrations are not needed—the Makefile creates and stamps the database schema as ready. For existing deployments, you can run:

• Upgrade to the Latest Revision:

  env/bin/alembic -c data/development.ini upgrade head

• View Migration History and Current Revision:

  env/bin/alembic -c data/development.ini history
  env/bin/alembic -c data/development.ini current

• Create a New Migration Script:

  env/bin/alembic -c data/development.ini revision -m "Added email_id column to User table."

• Autogenerate a Migration Script:

  env/bin/alembic -c data/development.ini revision --autogenerate -m "autogenerated indices."

Review the generated script before applying it.

Looking Up Paying Customers

To list paying customers, execute:

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

To interact with Remarkbox’s models and database using an interactive Python shell, run:

env/bin/pshell data/development.ini

For example, the following script modifies every Node that has a Uri:

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

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

# Update each Node.
for uri in uris:
    uri.node.has_uri = True
    request.dbsession.add(uri.node)

# Flush and commit changes.
request.dbsession.flush()
request.tm.commit()

Contributing

• Establish communication with Russell or another admin to have your GitLab account approved.

• Clone the repository and make commits.

• Create merge requests; unit and headless functional tests run automatically on each commit.

• Upon merge, changes are released to production and become visible to users.

Optional Formatting Guidelines:

• Python: Use black (manual execution).

• Jinja2/HTML: No formatter needed.

• JavaScript/CSS: Use Prettier or Biome (manual execution).

Licence

All contributed code is placed in the public domain.

Original Developer: Russell Ballestrini