make_post_sell/README.rst

Make Post Sell
==============

The `Make Post Sell <https://www.makepostsell.com>`_ monolith platform service.

You can use the SaaS or self-host!

Our `blog acts as our user guide <https://blog.makepostsell.com/>`_ & also uses ``make_post_sell``!


Quick Start: Operating a Server with PyPI or Source Code
==========================================================

Before you start, navigate to the directory where you want to install ``make_post_sell`` database & files.

This Makefile-based workflow lets you choose between installing ``make_post_sell`` 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 make_post_sell**

   - **PyPI Installation:**  
     Download the Makefile and run::
     
         wget "https://git.unturf.com/engineering/make-post-sell/make_post_sell/-/raw/master/Makefile"
         make install-from-pypi

   - **Source Installation (Editable Mode):**  
     Clone the repository and run::
     
         git clone ssh://git@git.unturf.com:2222/engineering/make-post-sell/make_post_sell.git
         make install-from-source

   - **Production Installation (Non‑Editable):**  
     For production use (non‑editable even from source), run::
     
         git clone ssh://git@git.unturf.com:2222/engineering/make-post-sell/make_post_sell.git
         make install-from-source-prod

2. **Activate the Virtual Environment**

   Before running any commands, activate the virtual environment::
   
         source env/bin/activate

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

         # boto3 style credentials for s3/digital-ocean spaces.
         # this is for storing content & physical products.
         export MPS_APP_MAIN_BUCKET="removed"
         export MPS_APP_SECURE_UPLOADS_ACCESS_KEY="removed"
         export MPS_APP_SECURE_UPLOADS_SECRET_KEY="removed"

         # stripe keys for collecting credit cards & crypto.
         # NOTE: These are used by tests, shops configure their own keys in the UI
         export MPS_TEST_STRIPE_PUBLIC_API_KEY="pk_test_removed"
         export MPS_TEST_STRIPE_SECRET_API_KEY="sk_test_removed"

         # the root domain acts as a SaaS for many shop domains!
         export MAKE_POST_SELL_ROOT_DOMAIN="example.com"
         export MAKE_POST_SELL_ROOT_URL="http://example.com:6501"
         
         # optional: email for the root domain owner
         export MAKE_POST_SELL_DOMAIN_OWNER_EMAIL="admin@example.com"

         # optional: DKIM email signing (commented out by default)
         # export MPS_APP_DKIM_PRIVATE_KEY_PATH="/path/to/dkim/private.key"
         # export MPS_APP_DKIM_SELECTOR="selector"

   With the virtual environment active, start the server::

         source vars.sh
         make serve

   Then browse to `http://127.0.0.1:6501/ <http://127.0.0.1:6501/>`_ to view the app.


Monero (XMR) Payment Support (Optional)
---------------------------------------

Make Post Sell now supports Monero (XMR) cryptocurrency payments alongside traditional Stripe payments. This feature is optional and can be enabled/disabled in the configuration.

**Configuration in development.ini:**

.. code-block:: ini

    # Payment method toggles
    app.payments.stripe.enabled = True
    app.payments.monero.enabled = False  # Set to True to enable Monero

    # Monero RPC Configuration (if enabled)
    monero.rpc_url = ${MPS_MONERO_RPC_URL:-http://127.0.0.1:18083/json_rpc}
    monero.rpc_user = ${MPS_MONERO_RPC_USER:-}
    monero.rpc_pass = ${MPS_MONERO_RPC_PASS:-}
    monero.account_index = ${MPS_MONERO_ACCOUNT_INDEX:-0}
    monero.confirmations_required = ${MPS_MONERO_CONFIRMATIONS_REQUIRED:-10}
    monero.quote_expiry_seconds = ${MPS_MONERO_QUOTE_EXPIRY_SECONDS:-900}
    monero.rate_source_url = ${MPS_MONERO_RATE_SOURCE_URL:-https://api.coingecko.com/api/v3/simple/price?ids=monero&vs_currencies=usd}

**Setting up Monero:**

1. **Run a Monero Wallet RPC:** You'll need to run ``monero-wallet-rpc`` with a wallet that can receive payments::

       monero-wallet-rpc --rpc-bind-ip=127.0.0.1 --rpc-bind-port=18083 \
           --disable-rpc-login --wallet-file=/path/to/wallet

2. **Configure environment variables** in your ``vars.sh``::

       export MPS_MONERO_RPC_URL="http://127.0.0.1:18083/json_rpc"
       
       # Optional: if RPC requires authentication
       export MPS_MONERO_RPC_USER="username"
       export MPS_MONERO_RPC_PASS="password"
       
       # Optional: confirmation requirements by amount
       export MPS_MONERO_CONFIRMATIONS_PETTY="2"        # For amounts < $10
       export MPS_MONERO_CONFIRMATIONS_MID="10"         # For amounts < $100
       export MPS_MONERO_CONFIRMATIONS_HIGH="20"        # For amounts >= $100
       export MPS_MONERO_THRESHOLD_MID="10.00"          # USD threshold for mid tier
       export MPS_MONERO_THRESHOLD_HIGH="100.00"        # USD threshold for high tier

3. **Run the crypto watcher:** This background service monitors incoming Monero payments and confirms orders.

   Using Make targets::

       make crypto-watcher        # Run continuously
       make crypto-watcher-once   # Run once for testing

   Or run directly::

       crypto_watcher development.ini         # Run continuously
       crypto_watcher development.ini --once  # Run once

**Shop Readiness:**

Shops are considered "ready" based on enabled payment methods:
- If only Stripe is enabled: Shop needs Stripe API keys
- If only Monero is enabled: Shop just needs the Monero RPC to be available
- If both are enabled: Shop needs either Stripe API keys OR Monero RPC available

**How it works:**

1. Customers can choose "Pay with Monero" at checkout (for single-shop carts)
2. A unique subaddress is generated for each payment
3. The system monitors the blockchain for incoming payments
4. Orders are automatically fulfilled when payment is confirmed


Running Tests
-------------

We currently use `pytest`:

.. code-block:: bash

 make test


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

If your deployment is brand new, you don't need to run any 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 indicies."

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

misc
====

You may source the new Python virtual environment during development:

.. code-block:: bash

 # source env/bin/activate.fish
 . env/bin/activate


Python Pyramid Shell
==========================

If you want to use an interactive Python interpreter to interact with Make Post Sell app/models & DB:

.. code-block:: bash

 pshell development.ini

For example, we needed to migrate production data using this script:

.. code-block:: python

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

 suses = models.stripe_user_shop.get_all_stripe_user_shop_objects(request.dbsession)
 for sus in suses:
     try:
         sus.active_card_id = sus.stripe_customer_default_source.id
         request.dbsession.add(sus)
     except AttributeError:
         pass

 # flush / commit all changes stored the the sqlachemy 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 contributed code is placed in the public domain.

source code: `https://git.unturf.com/engineering/make-post-sell/make_post_sell <https://git.unturf.com/engineering/make-post-sell/make_post_sell>`_

MakePostSell & make-post-sell are 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>`_