This is an auto-generated copy of the README for this repository: https://github.com/sourcecred/template-instance
This repository contains a template for running a SourceCred instance.
New users of SourceCred are encouraged to use this template repo to start their own instance.
This repo comes with a GitHub action configured that will run SourceCred automatically every 24 hours, as well as any time you change the configuration.
SourceCred is organized around "instances". Every instance must have a
sourcecred.json file at root, which specifies which plugins are active in the
instance. Config and permanent data (e.g. the Ledger) are stored in the main branch.
All output or site data gets stored in the
gh-pages branch by the Github Action.
confighas JSON files that will be hand-edited to configure your instance (more on this below).
data/ledger.jsonkeeps a history of all grain distributions and transfers as well as identities added / merged. This should not be hand-edited.
cache/stores intermediate produced by the plugins. This directory should not be checked into Git at all.
output/stores output data generated by SourceCred, including the Cred Graph and Cred Scores. This directory should be checked into Git; when needed, it may be removed and re-generated by SourceCred.
site/which stores the compiled SourceCred frontend, which can display data stored in the instance.
Using this instance as a starting point, you can update the config to include the plugins you want, pointing at the data you care about. We recommend setting up your instance locally first and make sure its working before pushing your changes to main and using the Github Action.
Setting up a SourceCred Instance requires basic knowledge of:
- using a terminal
- using git
- hand-editing JSON files
Step 1: Do Initial Setup
Hit the big green "Use this template" button on github. (do not fork)
Use a git client to clone your new repo locally.
Get Yarn, navigate to the cloned repo directory in a terminal, and then run
yarnto install SourceCred and dependencies.
Enable the plugins you want to use by adding them to the
bundledPluginsarray in the
sourcecred.jsonfile. To disable a plugin, simply remove it. For example, to enable all the plugins:
- If you are using the GitHub or Discord plugin, copy the
.env.examplefile to a
cp .env.example .env
Step 2: Configure Plugins
The GitHub plugin loads GitHub repositories.
You can specify the repositories to load in
In order for SourceCred to access your GitHub repos,
you must have a GitHub API key in your
.env file as
SOURCECRED_GITHUB_TOKEN=<token> (copy the
.env.example file for reference). The key should be read-only without any special
scopes or permissions (unless you are loading a private GitHub repository, in which case
the key needs access to your private repositories).
You can generate a GitHub API key here.
The Discourse plugin loads Discourse forums; currently, only one forum can be loaded in any single instance. This does not require any special API
keys or permissions. You just need to set the server url in
config/plugins/sourcecred/discourse/config.json. The discourse forum must be publicly accessible via the URL that is set, however. The forum must be accessible without a login.
The Discord plugin loads Discord servers, and mints Cred on Discord reactions. In order for SourceCred to
access your Discord server, you need to generate a "bot token" and paste it in the
.env file as
SOURCECRED_DISCORD_TOKEN=<token> (copy the
.env.example file for reference).
The full instructions for setting up the Discord plugin can be found in the Discord plugin page in the SourceCred documentation.
Step 3: Configure CredRank Weights
Our current core algorithm, CredRank, is a variation of an algorithm called PageRank. This is a graph-based algorithm that requires weights to be set for the nodes and edges. We provide default weights, and if you want, you can skip this section for now. When you're ready to decide for yourself how Cred should flow through the graph, follow these instructions:
yarn sourcecred serve, open
localhost:6006in a browser, and navigate to the Weight Configuration page.
- Set the node and edge weights for each plugin. See this guide and the plugin docs for help.
- Click "Download weights", move the downloaded file from your downloads folder to the
config/folder in your instance, and then make sure the name is exactly
Step 3 (alternative): Configure our experimental algorithm CredEquate
For a comparison of the two available algorithms, and example configs, see: https://sourcecred.io/docs/guides/core-algorithm/
Step 4: Configure Dependency Cred
config/dependencies.json you'll notice there is a default configuration for recognizing SourceCred as a dependency that powers your community. This will create bonus Cred and give it to an identity named
sourcecred, which will be activated to receive rewards. By default it is set to 0.05 (5% of minted Cred).
If you choose to keep or increase our dependency cred, rewards distributed to our community support the longevity and development of the project. If you are interested in possibly getting extra tech support or feature prioritization for higher depencency cred, reach out on Discord in our #any-questions channel! If you want to lower or remove the dependency cred, we're dedicated to open source and you totally can.
NOTE: WE ARE NO LONGER ACCEPTING REWARDS/DONATIONS AT THIS TIME
Step 5: Test with the CLI
Use the following commands to run your instance locally:
yarn loadloads the data from each plugin into the cache. Run this anytime you want to re-load the data from your plugins.
yarn startcreates the cred graph, computes cred scores and runs the front end interface which you can access at
localhost:6006in your browser.
NOTE: this command will not load any new data from Discord / GitHub / Discourse, etc. If you want to re-load
all the latest user activity, run
yarn load again.
yarn cleanwill clear any cached data that was loaded by the plugins. You can run this if any plugins fail to load. Run
yarn startafter this to refresh the data.
yarn clean-allgives you and even cleaner state. Run it if the
yarn startcommand fails due to a change in the config or breaking changes in a new version of SourceCred, and then run
yarn startto refresh.
Step 6: Set Up GitHub Actions
- Once you get
yarn startworking, push your local changes to GitHub.
- (Skip this if you are not using the Discord or GitHub plugins.) In GitHub, go to your repository's Settings tab and click Secrets in the left sidebar. Add the API tokens from your local .env file by clicking New repository secret and adding
SOURCECRED_<PLUGIN>_TOKENas the name and the token as the value.
- Go to the repository's Actions tab. If the most recent Generate Cred Instance workflow has failed, click into it and click "Re-run all jobs". Wait or come back to verify that Generate Cred Instance succeeds.
Step 7: Publish with GitHub Pages
The Generate Cred Instance workflow has deployed a static site to a branch called
- Go to Settings > Pages
- Select the gh-pages branch if it is not already selected.
- Click "Select theme" and then click the green "Select Theme" to choose a random theme. This is required but it does not matter what theme is chosen.
- Verify that the URL it gives you works.
Step 8: Distribute Rewards
By default, rewards are called Grain by SourceCred. If you would like to re-skin the rewards to represent your community's token, edit
yarn grain distributes Grain according to the current Cred scores, and the config in
config/grain.json. This repo contains a GitHub Action for automatically distributing Grain. It will run every Sunday and create a Pull Request
with the ledger updated with the new grain balances based on the users Cred scores.
- Configure the amounts to distribution and the distribution strategy by editing "config/grain.json". There are three different policies that can be used to control how the grain gets distributed: "IMMEDIATE", "BALANCED", and "RECENT". For info on what each policy does, how to choose the right policy for your community, and how Grain operates in general, see How Grain Works.
- The grain distribution will not take effect until you manually approve and merge it every week in the Pull Requests tab of your instance repository. You should do this weekly, or you will encounter merge conflicts. If you want to skip the Pull Request step and commit directly to the main branch, read the instructions in
.github/workflows/distribute-grain.ymland make the described edit.
Example Grain Configuration
Below is an example
grain.json file for a configuration that uses a combination of all three policies. Here we tell SourceCred to distribute 1,000 grain every week, with 25% (250 grain) distributed according to
IMMEDIATE, 25% (250 grain) distributed according to
BALANCED, and 50% (500 grain) distributed according to
MaxSimultaneousDistributions can be used to back-fill multiple weeks of missing distributions, but can usually just be kept at 1.
Optionally use our CSV Grain Integration
Instead of doing Grain balance accounting in SourceCred, you can instead make Grain distributions output CSV files to directly send payouts to participants using Disperse.app or Gnosis Safe CSV app. To try this out, see: https://sourcecred.io/docs/guides/csv-grain/
If you want to go deeper, you can access lower-level commands in the SourceCred CLI in the form of:
yarn sourcecred <command>.
For a list of what's available, and what each command does, run
yarn sourcecred help. Then run
yarn sourcecred help <command name> to see what feature flags are available for each command.