search

rendall / simple-comment

Simple Comment is a commenting platform for any website. Free, flexible, source-available, secure, private, and scalable.
https://simple-comment.netlify.app
GNU Affero General Public License v3.0
2 stars 3 forks source link
anonymous-posts anonymous-users authentication comment-system free free-tier identification mongodb nodejs typescript

readme

Simple Comment

Simple Comment is a commenting platform for any website. Free, flexible, open-source, private, and scalable.

See the demo: https://simple-comment.netlify.app

Status

NB: Moderation tools are not yet adequate. There is no notification when a user has posted a comment, nor any way to hold it in moderation before approval. If you like this project and would like to see it developed further on a specific timeline, contact me. Otherwise, this project is still on the road, but on the slow road.

Netlify Status Open API 3.0 Validator Website Documentation Status

MVP is complete!

The minimum functionality is up and running!

Completed tasks: (click to open) - Cross-origin capability - Script with frontend - All API endpoint respond as expected - `Access-Control-Allow-Origin` responds to `.env` variables - Authentication and Identification works as expected - Authenticated users and admins can interact with Simple Comment as expected - Anonymous user can _create topics_ - This is useful for sites with lots of pages - For security reasons, restrictions apply: - The `Referer` header and the `topicId` must map properly - The `Origin` must be on the `Access-Control-Allow-Origin` list - Server-side validation of user-posted data - Setup instructions - Are complicated but work when followed - Visitor can post anonymously - Comment includes guest user - Designed a beautiful badge! - [![Powered by Simple Comment](docs/simple-comment-badge.svg)](https://simple-comment.netlify.app) - Visitors can read and reply to comments ### Top priority after MVP - Optional user authentication and identification - Moderator holds posts for approval - Spam prevention measures - Integration with 3rd party authentication - Email notification & integration - Framework-friendly frontends - Extensive helpful comments! - E2E tests ### Nice to haves - Moderator change policy on holding posts for approval - Visitor can claim ownership over anonymous posts - Edit button - Delete / edit time windows in policy - User profiles - See comments - Avatar

Features

Upcoming features

Setup

Simple Comment can be run on the same server as your website or on a separate, cross-domain server

It is necessary that Simple Comment is served via https:

Follow these instructions. If anything is unclear, please create a new issue

  1. Fork this repository to your own account
  2. Clone your fork
  3. Copy example.env into the same, project root directory and rename it to be .env
  4. In .env, enter your own (made up or randomly generated), secret values for these entries (i.e. replace everything to the right of = in each line).
    • SIMPLE_COMMENT_MODERATOR_CONTACT_EMAIL
    • SIMPLE_COMMENT_MODERATOR_ID
    • SIMPLE_COMMENT_MODERATOR_PASSWORD
    • JWT_SECRET
  5. sign up for a free MongoDB Atlas account
    1. Follow these instructions
    2. In .env add the proper DB_CONNECION_STRING
  6. Sign up for a Netlify account, begin a new website, and link your repository to the new website
    1. Review Netlify's Build environment variables page
    2. Navigate to 'Build & Deploy => Environment`
    3. Under Environmental Variables click the button Edit Variables
    4. For each entry in .env add the key and corresponding value for all variables
    5. For IS_CROSS_SITE add the value true if the comment system is hosted in its own domain and false if it is the same domain.
  7. Modify your website. These are simple instructions, but feel free to hack away
    1. In the HTML for each page on your website where you want Simple Comment to run, add these two tags:
      1. <script src="https://github.com/rendall/simple-comment/raw/master/[path-to]/simple-comment.js" defer></script> (src must point to the simple-comment.js file)
      2. <div id="simple-comment-display"></div>
    2. Upload the simple-comment.js file to your website's script folder
  8. It should now be possible to leave and read comments on your website

Troubleshooting

Moderating

  1. Visit the login.html page you uploaded in Setup and
  2. Log in using the SIMPLE_COMMENT_MODERATOR_ID and SIMPLE_COMMENT_MODERATOR_PASSWORD values in your .env file

Default build

The default stack uses Netlify + MongoDB for the backend, and a minimal fetch based client for the frontend, but it can be readily adapted to use any technology stack, as long as the tests pass and the API conforms to the Open API 3 schema file

You can get your own free-tier MongoDB-in-the-cloud by following these instructions

Local development

Assumes a unix-like environment, like Ubuntu.

Installation

  1. Install nvm
  2. nvm install
  3. npm install -g yarn
  4. yarn install
  5. yarn run build
  6. Install and run MongoDB Community Edition

Test

  1. yarn run test
  2. yarn run test:e2e

Usage

  1. sudo systemctl start mongod (q.v. Linux)
  2. yarn run start
  3. open http://localhost:7070/

API

The API specification is described by the file simple-comment-openapi3.json in Open API 3 format and is designed to be interchangeable with any backend, frontend and identification system

This is an overview of the Simple Comment API endpoints

/comment

A comment is text that a user posts in reply to either another comment or a topic, and presenting these replies is the sole reason this project exists!

The comment endpoint is for the creation, reading, updating and deleting (CRUD) of individual comments. All comments must have a parent, that is, something it replies to, whether a topic or comment

/topic

A topic is a special kind of comment that by default can only be created by admin users, and forms an organizational bucket for comments that reply. It is a kind of root comment, and therefore has no parent

The /topic endpoint handles CRUD for these root comments. A GET operation of /topic will get a list of topics and GET on /topic/{topicId} will get all comments in reply to that topic and their descendents

/user

By default, comments can be posted by anonymous users, but Simple Comment does have a minimal identification scheme so that commenters who choose to do so can have control over their comments after the are posted, according to policy

/auth

Auth is the endpoint for the authentication and identification scheme. A user submits their username and password to the auth endpoint, and receives a JSON Web Token (JWT) that authenticates them as that user for other CRUD operations

/verify

Returns the logged-in user id or 401

policy

policy is an object holding key-value pairs that governs how Simple Comment behaves, determining for instance maximum comment length or whether ordinary users can delete themselves.

{
  isGuestAccountAllowed : boolean, // if true, a visitor can post anonymously using a guest account. if false, only authenticated users can comment.
  canFirstVisitCreateTopic : boolean, // if a discussion does not exist for a page, shall it be created when visited for the first time, or does admin create all topics?
  canGuestCreateUser : boolean, // can a user with guest credentials create (their own) user profile? if 'canPublicCreateUser' is set to 'true' this setting is ignored
  canGuestReadDiscussion : boolean, // can a user with guest credentials browse and read discussions? if 'canPublicReadDiscussion' is set to 'true' this setting is ignored
  canGuestReadUser : boolean, // can a user with guest credentials view user profiles? if 'canPublicReadUser' is true, this setting is ignored
  canPublicCreateUser : boolean, // can a user with no credentials create (their own) user profile?
  canPublicReadDiscussion : boolean, // can a user with no credentials browse and read discussions?
  canPublicReadUser : boolean, // can an anonymous visitor view any user's profile?
  canUserDeleteSelf : boolean, // can a user delete their own profile?
  maxCommentLengthChars : number, // Attempting to post a comment longer than this number of characters will be rejected by the API
}

Alternatives

There are 34 solutions that are not Simple Comment listed here. Nearly all of these are more mature than Simple Comment, and I would recommend considering one if you are not looking specifically for a serverless, open-source, self-hosted solution. Listed below each are pros and cons that distinguish it from Simple Comment. If Trust is required is listed, it means that using the service requires trust in the company, because they will be serving closed-source code to your users that you do not control and cannot easily inspect; as well, user data will be held on servers they control. This list is based on public documentation, not experience. If anything is incorrect or missing, please let me know.