scoold: A Java repository from corin8823

Stack Overflow in a JAR

Scoold is a Q&A platform written in Java. The project was created back in 2008, released in 2012 as social network for schools inspired by StackOverflow, and as of 2017 it has been refactored, repackaged and open-sourced. The primary goal of this project is educational but it can also work great as a Q&A/support section for your website.

Scoold can run on Heroku or any other PaaS. It's lightweight (~4000 LOC) - the backend is handled by a separate service called Para. Scoold does not require a database, and the controller logic is really simple because all the heavy lifting is delegated to Para. This makes the code easy to read and can be learned quickly by junior developers.

This project is fully funded and supported by Erudika - an independent, bootstrapped company.

Features

Full featured Q&A platform
Database-agnostic, optimized for cloud deployment
Full-text search
Distributed object cache
Location-based search and "near me" filtering of posts
I18n and branding customization
Spring Boot project (single JAR)
Reputation and voting system with badges
Minimal frontend JS code based on jQuery
Modern, responsive layout powered by Materialize CSS
Suggestions for similar questions and hints for duplicate posts
Email notifications for post replies and comments
LDAP authentication support
Social login (Facebook, Google, GitHub, LinkedIn, Microsoft, Twitter) with Gravatar support
SEO friendly

Live Demo

Scoold is deployed on a free dyno and it might take a minute to wake up.

Live demo on Heroku

Quick Start

You first need to create a developer app with Facebook, Google or any other identity provider that you wish to use. This isn't necessary only if you enable LDAP or password authentication.
Create a new app on ParaIO.com and save the access keys
Click here =>

Create a new app on ParaIO.com and save the access keys OR run it locally
Create application.conf and configure Scoold to connect to Para
Run java -jar -Dserver.port=8000 -Dconfig.file=./application.conf scoold.jar OR mvn spring-boot:run
Open http://localhost:8000 in your browser

If you run Para locally, use the Para CLI tool to create a separate app for Scoold:

$ para-cli ping && para-cli new-app "scoold" --name "Scoold"

Important: Do not use the same application.conf file for both Para and Scoold! Keep the two applications in separate directories, each with its own configuration file. The settings shown below are all meant to part of the Scoold config file.

Read the Para docs for more information.

Configuration

The most important settings are para.endpoint - the URL of the Para server, as well as, para.access_key and para.secret_key. Connection to a Para server is required for Scoold to run.

This is an example of what your application.conf should look like:

para.app_name = "Scoold"
# the port for Scoold
para.port = 8080
# change this to "production" later
para.env = "development"
# the URL where Scoold is hosted, e.g. https://scoold.yourhost.com
para.host_url = "https://your-scoold-domain.com"
# the URL of Para - could also be "http://localhost:8080"
para.endpoint = "https://paraio.com"
# access key for your Para app
para.access_key = "app:scoold"
# secret key for your Para app
para.secret_key = "*****************"
# enable or disable email&password authentication
para.password_auth_enabled = false
# if false, commenting is allowed after 100+ reputation
para.new_users_can_comment = true
# needed for geolocation filtering of posts
para.gmaps_api_key = "********************************"
# the identifier of admin user - check Para user object
para.admin_ident = "admin@domain.com"
# GA code
para.google_analytics_id = "UA-123456-7"
# enables syntax highlighting in posts
para.code_highlighting_enabled = true
# Facebook - create your own Facebook app first!
para.fb_app_id = "123456789"
# Google - create your own Google app first!
para.google_client_id = "123-abcd.apps.googleusercontent.com"

Note: On Heroku, the config variables above must be set without dots ".", for example para.endpoint becomes para_endpoint. These are set through the Heroku admin panel, under "Settings", "Reveal Config Vars".

Content-Security-Policy header

This header is enabled by default for enhanced security. It can be disabled with para.csp_header_enabled = false. The default value is modified through para.csp_header = "new_value". The default CSP header is:

default-src 'self';
base-uri 'self';
connect-src 'self' scoold.com www.google-analytics.com;
frame-src 'self' accounts.google.com staticxx.facebook.com;
font-src cdnjs.cloudflare.com fonts.gstatic.com fonts.googleapis.com;
script-src 'self' 'unsafe-eval' apis.google.com maps.googleapis.com connect.facebook.net cdnjs.cloudflare.com www.google-analytics.com code.jquery.com static.scoold.com;
style-src 'self' 'unsafe-inline' fonts.googleapis.com cdnjs.cloudflare.com static.scoold.com;
img-src 'self' https: data:; report-uri /reports/cspv

Note: If you get CSP violation errors, check you para.host_url configuration, or edit the value of para.csp_header.

Serving static files from a CDN

Scoold will serve static files (JS, CSS, fonts) from the same domain where it is deployed. You can configure the para.cdn_url to enable serving those files from a CDN. The value of the CDN URL will override para.host_url and must not end in "/".

SMTP configuration

Scoold uses the JavaMail API to send emails. If you want Scoold to send notification emails you should add the following SMTP settings to your config file:

# system email address
para.support_email = "support@scoold.com"

para.mail.host = "smtp.example.com"
para.mail.port = 587
para.mail.username = "user@example.com"
para.mail.password = "password"
para.mail.tls = true
para.mail.ssl = false

The email template is located in src/main/resources/emails/notify.html.

Social login

For authenticating with Facebook or Google, you only need your Gogle client id (e.g. 123-abcd.apps.googleusercontent.com), or Facebook app id (only digits). For all the other providers, GitHub, LinkedIn, Twitter and Microsoft, you need to set both the app id and secret key. Note: if the credentials are blank, the sign in button is hidden for that provider.

# Facebook
para.fb_app_id = "123456789"
# Google
para.google_client_id = "123-abcd.apps.googleusercontent.com"
# GitHub
para.gh_app_id = ""
para.gh_secret = ""
# LinkedIn
para.in_app_id = ""
para.in_secret = ""
# Twitter
para.tw_app_id = ""
para.tw_secret = ""
# Microsoft
para.ms_app_id = ""
para.ms_secret = ""

You also need to set your host URL when running Scoold in production:

para.host_url = "https://your.scoold.url"

This is required for authentication requests to be redirected back to the origin.

LDAP configuration

LDAP authentication is initiated with a request like this GET /signin?provider=ldap&access_token=username:password. There are several configuration options which Para needs in order to connect to your LDAP server. These are the defaults:

para.security.ldap.server_url = "ldap://localhost:8389/"
para.security.ldap.base_dn = "dc=springframework,dc=org"
para.security.ldap.bind_dn = ""
para.security.ldap.bind_pass = ""
para.security.ldap.user_search_base = ""
para.security.ldap.user_search_filter = "(cn={0})"
para.security.ldap.user_dn_pattern = "uid={0},ou=people"
para.security.ldap.password_attribute = "userPassword"
# set this only if you are connecting to Active Directory
para.security.ldap.active_directory_domain = ""

Customizing the UI

HTML templates are in src/main/resources/templates/
CSS stylesheets can be found in src/main/resources/static/styles/
JavaScript files can be found in src/main/resources/static/scripts
Images are in located in src/main/resources/static/images/

Also, please refer to the documentation for Spring Boot and Spring MVC.

Building Scoold

To compile it you'll need JDK 8+ and Maven. Once you have it, just clone and build:

$ git clone https://github.com/erudika/scoold.git && cd scoold
$ mvn install

To run a local instance of Scoold for development, use:

$ mvn -Dconfig.file=./application.conf spring-boot:run

Contributing

Fork this repository and clone the fork to your machine
Create a branch (git checkout -b my-new-feature)
Implement a new feature or fix a bug and add some tests
Commit your changes (git commit -am 'Added a new feature')
Push the branch to your fork on GitHub (git push origin my-new-feature)
Create new Pull Request from your fork

Please try to respect the code style of this project. To check your code, run it through the style checker:

mvn validate

For more information see CONTRIBUTING.md

License

Apache 2.0

corin8823/scoold