erudikaltd/scoold repository overview

⁠Scoold - Stack Overflow in a JAR

Scoold is a Q&A and a knowledge sharing platform for teams. The project was created back in 2008, released in 2012 as social network for schools inspired by Stack Overflow. In 2017 it was refactored, repackaged and open-sourced.

Scoold can run anywhere - Heroku, DigitalOcean, AWS, Azure or any VPS hosting provider. It's lightweight (~7000 LOC), the backend is handled by a separate service called Para⁠. All the heavy lifting is delegated to Para which can also be configured to store the data in any of the popular databases. This makes the Scoold code base easy to read and can be learned quickly, even by junior developers.

Scoold Pro, the paid version of Scoold, has premium features which make it the perfect knowledge sharing platform for your company or team.

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 with RTL language support
• Reputation and voting system with badges
• Custom badges - add your own text, icon and color
• Spaces (Teams) - groups of isolated questions and users
• Webhooks with signature signing
• Zapier integration⁠
• 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
• Backup and Restore
• RESTful API defined with OpenAPI 3.0
• Spring Boot project (single JAR)
• Mutual authentication support (mTLS)
• LDAP authentication support
• Social login (Facebook, Google, GitHub, LinkedIn, Microsoft, Slack, Amazon, Twitter) with Gravatar support
• Syntax highlighting for code in posts, GFM markdown support with tables, task lists and strikethrough
• Import data from Stack Overflow for Teams
• Emojis! - using this cheat sheet⁠ or inline Unicode
• Support for uploading custom avatars (to Imgur, Cloudinary)
• SEO friendly
• Cookie consent (for GDPR, CCPA, etc.)

⁠Buy Scoold Pro⁠ and also get these premium features:

• Slack integration⁠
• Mattermost integration⁠
• Microsoft Teams integration⁠
• SAML authentication support
• Custom authentication support
• SCIM 2.0 for automatic user provisioning
• Mentions with notifications
• File uploads (local, AWS S3, Azure Blob)
• Account suspensions (permabans)
• Anonymous posts
• Unlimited spaces
• Multiple admins
• Multiple identity domains
• Sticky / Favorite posts
• Advanced syntax highlighting
• Email digest of recent questions
• Security notifications
• Wiki-style answers

...and more!

⁠Live Demos

⁠Scoold Demo⁠ | Scoold Pro Demo⁠

For admin access, open the Scoold Pro demo and login with "Demo login".

⁠Scoold architecture intro (or 'what the heck is Para?')

Scoold is a client application of the Para⁠ backend server. Almost every request to Scoold produces at least one request to Para as well. When you ask a question on Scoold, a create request is sent to Para to the location POST /v1/questions. Here are a few key points about that architecture:

• A Para server can be hosted anywhere and store data inside any of the supported databases⁠.
• Para is a multi-tenant server which stores data in isolated environments called "apps".
• One or more instance of Scoold (like a cluster) can connect to the same Para app environment and share the data.
• Multiple separate Scoold websites can be powered by the same Para backend using different Para apps.
• Each app environment is completely independent from others and has its own database table and search index.
• Both Scoold and Para can be hosted on the same machine or on multiple machines, on different networks.
• Scoold talks to Para via HTTP(S) so Para must be directly accessible from Scoold, but can also be hosted on a private network.

Here's an overview of the architecture:

                              ┌────────────┐
                          ┌───►  Database  │
┌──────────┐  ┌────────┐  │   ┌────────────┤
│ Scoold 1 ├──►        │  │   └────────────┤
├──────────┤  │  Para  ◄──┼───►   Search   │
│ Scoold 2 ├──►        │  │   ┌────────────┤
└──────────┘  └────────┘  │   └────────────┤
                          └───►   Cache    │
                              └────────────┘

⁠Quick Start with a managed Para backend (easier)

JDK 21 or higher⁠ and Maven⁠ are required to build the project. You can build the project with JDK 11/17 until version 1.59.0, at which point Scoold switches to JDK 21 and Spring Boot 3.x.

1. Create a new app on ParaIO.com⁠ and copy your access keys to a file.
2. Create Scoold's configuration file named scoold-application.conf with these properties:

   scoold.env = "production"
   scoold.app_name = "Scoold"
   scoold.para_access_key = "app:scoold"
   scoold.para_secret_key = "_secret_key_from_para_"
   scoold.para_endpoint = "https://paraio.com"
   # add your email here
   scoold.admins = "[email protected]"
   # (optional) require authentication for viewing content
   scoold.is_default_space_public = false
   

   Copy
3. Start Scoold with java -jar -Dconfig.file=./scoold-application.conf scoold-*.jar.
4. Open localhost:8000/signin/register⁠ and register a new account with same email you put in the configuration.

To login with a social account, you must create a developer app with Facebook⁠, Google⁠ or any other identity provider. This is not required when you log in with LDAP, SAML or email/password.

Save the obtained API keys in the scoold-application.conf file that you have created above.

⁠Quick Start with a self-hosted Para backend (harder)

Note: The Para backend server is deployed separately and is required for Scoold to run.

1. Download the latest executable Para JAR package⁠
2. Start Para with the command java -jar -Dconfig.file=./para-application.conf para-*.jar
3. Create a separate folder scoold and inside, a new configuration file named scoold-application.conf (see example above)
4. Start Scoold with the following command, pointing it to the location of the Para configuration file:

   java -jar -Dconfig.file=./scoold-application.conf \
     -Dscoold.autoinit.para_config_file=../para-application.conf scoold-*.jar`
   

   Copy

On startup, Para will initialize and create its own configuration file. Scoold will then try to initialize and configure itself automatically by reading the para-application.conf. Alternatively you could provide Scoold with the root access key directly, instead of pointing it to the Para configuration file, like so:

	java -jar -Dconfig.file=./scoold-application.conf \
	  -Dscoold.autoinit.root_app_secret_key="{secret key for root app}" scoold-*.jar`

The secret key for the root Para app can be found inside the Para configuration file, or para-application.conf, labeled para.root_secret_key.

1. Open localhost:8000/signin/register⁠ and register a new account with same email you put in the configuration

Optionally, you can also install the Para CLI⁠ tool for browsing and managing data in your Scoold app.

Important:

• The convention is to use para-application.conf and scoold-application.conf for Para and Scoold respectively.
• All settings shown here are meant to be kept inside the Scoold configuration file.
• SMTP settings must be configured before deploying Scoold to production.
• Scoold does not have a default user account with default username and password.

Read the Para docs⁠ for further details on how to run and configure your Scoold backend.

⁠Hardware requirements

Scoold and Para can both be hosted on the same machine, provided it has at least 3 GB of RAM.

Scoold requires:

• at least 500 MB RAM
• 1 vCPU or more
• 10 GB disk space or more (primarily for logs and storing images)

Para requires:

• at least 1 GB RAM
• 1 vCPU (2 are recommended)
• 10 GB disk space or more (unless the database is stored on the same machine)

JVM parameters: e.g. java -jar -Xms600m -Xmx600m scoold-*.jar

⁠Configuration

Scoold requires a persistent and direct connection to a Para server to function properly. By default, Scoold will load its configuration from a file named application.conf but that file can be renamed to scoold-application.conf or app.conf and then loaded with the system property -Dconfig.file=app.conf. The configuration can also be loaded from a JSON file or a URL⁠.

Copy this Scoold example configuration to your scoold-application.conf (edit the values if needed):

# the name of the application
scoold.app_name = "Scoold"
# the port for Scoold
scoold.port = 8000
# environment - "production" or "development"
scoold.env = "production"
# the public-facing URL where Scoold is hosted
scoold.host_url = "http://localhost:8000"
# the URL of Para - can also be "https://paraio.com"
scoold.para_endpoint = "http://localhost:8080"
# access key for your Para app
scoold.para_access_key = "app:scoold"
# secret key for your Para app
scoold.para_secret_key = ""
# the email or identifier of the admin user - check Para user object
scoold.admins = "[email protected]"
# Enable/disable password authentication
scoold.password_auth_enabled = true

⁠For the full README, visit the Scoold GitHub repo.⁠