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.

1. 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://git@git.unturf.com:2222/engineering/remarkbox/remarkbox.git
     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

   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!

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_payment
    INNER JOIN rb_user ON rb_user.id = rb_payment.user_id
    WHERE status = 'completed';

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.

source code: 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