======================
Welcome to pg-discuss!
======================

.. image:: https://travis-ci.org/sprin/pg-discuss.svg
    :target: https://travis-ci.org/sprin/pg-discuss

pg-discuss is a comment system backend written in Python on top of a
`PostgreSQL`_ database. It is designed to support JavaScript comment widgets
embedded in any page, such as static sites generated by `Pelican`_, `Sphinx`_,
or `Nikola`_. pg-discuss can also be used with a content management system such
as `WordPress`_, or within your own dynamic web app that needs a robust comment
system.

.. _`PostgreSQL`: http://www.postgresql.org/
.. _`Pelican`: http://getpelican.com/
.. _`Sphinx`: http://sphinx-doc.org/
.. _`Nikola`: https://getnikola.com/
.. _`WordPress`: https://wordpress.org/


   - `Demo`_
   - `Features`_
   - `Installation`_
   - `Configuration`_
   - `Internals`_ (for Extension Authors and Contributors)

.. _Demo: https://pg-discuss.sprin.io/en/latest/demo.html
.. _Features: https://pg-discuss.sprin.io/en/latest/features.html
.. _Installation: https://pg-discuss.sprin.io/en/latest/installation.html
.. _Configuration: https://pg-discuss.sprin.io/en/latest/configuration.html
.. _Internals: https://pg-discuss.sprin.io/en/latest/internals/index.html

Why pg-discuss?
===============

Respect for Users
-----------------

pg-discuss has a feature set comparable to popular commercial comment
management systems. However, pg-discuss does not sell your users' browsing
habits and comments to marketers. You have full control over how your users'
information is used.

Permissively-Licensed Open Source
---------------------------------

pg-discuss is a MIT-licensed open source project that allows you to
operate, extend, and redistribute the application as you see fit. Contributions
are welcome.

Supports Multiple JavaScript Widgets
------------------------------------

The pg-discuss API can be adapted to work with existing embeddable comment
widgets. Of course, new widgets can also be written using the default REST
API.

Extensible
----------

The application is highly extensible, with most default features implemented as
extensions which are bundled. Extensions can change the comment workflow,
comment metadata collection, rendering engine, authentication, and HTTP API
format and endpoints. Extensions are implemented using a simple API that
exposes logical plugpoints and events.

Small and Readable Codebase
---------------------------

The core package of pg-discuss is less than 1000 lines. Code is structured
for readability, conforms to PEP8, and has ample comments. It is written to
be very approachable for both auditors and extension developers. Both prose
and API documentation of internals are published.

Robust and Performant Database
------------------------------

PostgreSQL offers strong data guarantees, ease of management, and high
performance. pg-discuss is written to take advantage of several
PostgreSQL-specific features that enable flexible extension and low latency
querying.

Available and Scalable
----------------------

The pg-discuss application can be deployed across many hosts for redundancy or
load balancing since it does not store any application state itself - all state
is held in the PostgreSQL database or in the client browser session. pg-discuss
also plays well with HTTP caches such as nginx, and a simple extension can
inform the cache when to purge stale objects.

pg-discuss alternatives
=======================

There are several good alternatives to pg-discuss that are also open source,
but have somewhat different design goals.

Isso
----

Perhaps you don't want to run a database?

`Isso`_ is an excellent SQLite-backed comment server - there is no separate
database instance to run, since the data is stored in a file. Also written
in Python. MIT licensed.

.. _Isso: http://posativ.org/isso/

Discourse
---------

Need a comment widget that also has file uploads, polling, private messaging,
analytics, all out of the box?

`Discourse`_ is a discussion platform with a `long list of features`_, with a
Ruby on Rails backend on top of PostgreSQL. GNU GPL v2 licensed.

.. _Discourse: http://www.discourse.org/
.. _long list of features: http://www.discourse.org/about/
