remarkbox

Quick Start: Operating a Server with PyPI or Source Code

Before you install, navigate to the directory you want to install into.

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.

• Install Remarkbox

  • For a PyPI Installation, run::

    wget "https://git.unturf.com/engineering/remarkbox/remarkbox/-/raw/main/Makefile"
    make install-from-pypi
    

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

    git clone ssh://[e-mail]:2222/engineering/remarkbox/remarkbox.git
    make install-from-source
    

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

• Start the Development Server

  You'll want to configure the system in data/development.ini.

  Typically I control most stuff with environment vars, for example vars.sh::

    # optional but currently broken...
    export REMARKBOX_APP_STRIPE_PUBLIC="pk_test_removed"
    export REMARKBOX_APP_STRIPE_SECRET="sk_test_removed"
    
    # optional & you will need to create you're own slack app/bot.
    export REMARKBOX_APP_SLACK_PUBLIC="removed"
    export REMARKBOX_APP_SLACK_SECRET="removed"
    
    # optional, defaults to localhost & http://localhost:6543
    export REMARKBOX_APP_ROOT_DOMAIN="example.com"
    export REMARKBOX_APP_URL="https://example.com"
  

  Once the virtual environment is active, run::

    source vars.sh
    make serve
  

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

Remarkbox

This is the codebase that powers both self‑hosted and SaaS Remarkbox!

SaaS Sites

• https://www.remarkbox.com <https://www.remarkbox.com>_
• https://faq.remarkbox.com <https://faq.remarkbox.com>_
• https://meta.remarkbox.com <https://meta.remarkbox.com>_

Self‑hosted Example Running a Custom Theme

• https://westworld2.com <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.

#. Support Multiple Use Cases:

• Q&A sites (e.g. StackOverflow)
• Embedded comment systems for static sites
• Forums
• Product review sections on e‑commerce sites

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

#. To be popular
#. To be safe from spammers
#. To be easy to manage and clean up spam
#. To be passwordless – using one‑time-password codes via email for registration and authentication
#. To scale horizontally
#. To be multitenant
#. To minimize friction for new users
#. To be engaging for users
#. To be search engine optimized
#. To have great test coverage
#. 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:

• In the first shell, start the Remarkbox server::

  make serve
  

• 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 <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:

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

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

.. code-block:: bash

env/bin/pshell data/development.ini

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

.. code-block:: python

# 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 <https://black.readthedocs.io/>_ (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.

source code: https://git.unturf.com/engineering/remarkbox/remarkbox <https://git.unturf.com/engineering/remarkbox/remarkbox>_

Remarkbox is trademarked, do not misrepresent the brand.

Feel free to white label any code or themes into your own brand.

Original Developer:
Russell Ballestrini <https://russell.ballestrini.net>_