Landing page for all things related to the Research Software Directory
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
admin @ 6856e70 update submodules Jun 14, 2018
ansible update .env files Aug 14, 2018
auth-github @ fa3e0e6 update submodule Jun 14, 2018
backend @ 97c26c5 update submodules Jun 12, 2018
config remove old certbot script Aug 14, 2018
db-dump @ 0ee6a5b remove old certbot script Aug 14, 2018
faq Merge pull request #184 from research-software-directory/faqs Dec 4, 2018
frontend @ 4ed56c0 update frontend submodule Sep 11, 2018
images added product page image Jul 10, 2018
readthedocs @ 362da73 update submodules Jun 12, 2018
tasks-nlesc @ 593a721 update submodule Aug 13, 2018
tests set .env default to 'changeme' to let travis work Jun 12, 2018
.dockerignore add testing & travis config test Jun 12, 2018
.env.example update .env files Aug 14, 2018
.gitattributes merge rsd/stack Jun 11, 2018
.gitignore add testing & travis config test Jun 12, 2018
.gitmodules fix: tasks submodule SSH -> HTTPS Aug 14, 2018
.travis.yml set .env default to 'changeme' to let travis work Jun 12, 2018
.zenodo.json Update .zenodo.json Jul 5, 2018
CHANGELOG.md Update CHANGELOG.md Jul 5, 2018
CITATION.cff Update CITATION.cff Jul 5, 2018
LICENSE Initial commit Jan 16, 2018
README.md Update README.md Sep 20, 2018
ROADMAP.md Update ROADMAP.md Mar 1, 2018
codemeta.json added rich structured data as codemeta Jul 4, 2018
docker-compose.png merge rsd/stack Jun 11, 2018
docker-compose.prod.yml use new HTTPS docker container Aug 14, 2018
docker-compose.test.yml add docker ps before test Jun 12, 2018
docker-compose.yml use new HTTPS docker container Aug 14, 2018
submodules.sha.txt added submodule SHAs, updated the README Jul 4, 2018
tmux_start update paths in tmux_start Jun 12, 2018

README.md

Research Software Directory Build Status DOI

This README file has 3 sections, with documentation for users, for developers, and for maintainers.

For users

The Research Software Directory is a content management system that is tailored to software.

The idea is that institutes for whom research software is an important output, can run their own instance of the Research Software Directory. The system is designed to be flexible enough to allow for different data sources, database schemas, and so on. By default, the Research Software Directory is set up to collect data from GitHub, Zenodo, Zotero, as well as Medium blogs.

For each software package, a product page can be created on the Research Software Directory if the software is deemed useful to others. Here is an example of what a product page may look like:

images/20180627-webcapture-xenon.png

While the content shown on the product page can be completely customized, by default it includes a Mentions section, which can be used to characterize the context in which the software exists. The context may include links to scientific papers, but is certainly broader than that: for example, there may be links to web applications that demonstrate the use of the software, there may be links to videos on YouTube, tutorials on readthedocs.io or Jupyter notebooks, or there may be links to blog posts; really, anything that helps visitors decide if the software could be useful for them.

The Research Software Directory improves findability of software packages, partly because it provides metadata that helps search engines understand what the software is about, but more importantly because of the human centered text snippets that must be provided for each software package. After all, discovery of a software package is often not so much about finding it but knowing that you found it.

Try it out

Basically, these are the steps to get a copy of https://research-software.nl running locally (including data):

  1. Clone this repo
  2. Configure
  3. Start the complete stack using docker-compose

For details, see below.

Try it out, step 1/3: Clone this repo

Make sure to use the --recursive flag, because this repository has git submodules.

git clone --recursive https://github.com/research-software-directory/research-software-directory.git

Try it out, step 2/3: Configure

The research software directory is configured using a file with environment variables called .env. An example config file (.env.example) is available, use it as a starting point.

cd research-software-directory
cp .env.example .env

The config file has some place holder values (changeme) they must be set by editing the .env file. Below are instructions how to get the different tokens and keys.

  • AUTH_GITHUB_ORGANIZATION
    1. Set to GitHub organization name which users should be member of to login to admin site
  • AUTH_GITHUB_CLIENT_ID + AUTH_GITHUB_CLIENT_SECRET
    1. Goto https://github.com/settings/developers -> OAuth Apps -> New OAuth App
    2. Set Authorization callback url: https://localhost/auth/get_jwt (replace localhost with the domain the site will be accessible on)
    3. Register application
      • Use Client ID as value for AUTH_GITHUB_CLIENT_ID
      • Use Client Secret as value for AUTH_GITHUB_CLIENT_SECRET
  • GITHUB_ACCESS_TOKEN
    1. Goto https://github.com/settings/tokens
    2. Generate new token
    3. Select no scopes
    4. Use token as value for GITHUB_ACCESS_TOKEN
  • ZOTERO_API_KEY
    1. https://www.zotero.org/settings/keys
    2. Create new private key
    3. Group permissions: Read Only
    4. Use api key as value for ZOTERO_API_KEY
  • ZOTERO_LIBRARY
    1. The Zotero group identifier, for example 1689348 is the identifier for group https://www.zotero.org/groups/1689348/netherlands_escience_center
  • JWT_SECRET
    1. Generate a random string (eg. openssl rand -base64 32) and use as value for JWT_SECRET

Try it out, step 3/3: Start the complete stack using docker-compose

docker-compose --file docker-compose.yml --file docker-compose.prod.yml up --build

Wait (at maximum 5 minutes) until you see some output scroll by that is generated by the tasks container, something like:

tasks_1     | 2018-07-11 10:30:02,990 cache_software [INFO] processing Xenon command line interface
tasks_1     | 2018-07-11 10:30:03,013 cache_software [INFO] processing Xenon gRPC server
tasks_1     | 2018-07-11 10:30:03,036 cache_software [INFO] processing xtas
tasks_1     | 2018-07-11 10:30:03,059 cache_software [INFO] processing boatswain
tasks_1     | 2018-07-11 10:30:03,080 cache_software [INFO] processing Research Software Directory
tasks_1     | 2018-07-11 10:30:03,122 cache_software [INFO] processing cffconvert
tasks_1     | 2018-07-11 10:30:03,149 cache_software [INFO] processing sv-callers

Open a web browser to verify that everything works as it should.


For developers

General workflow when making changes

Let's say you followed the steps above, and have a running instance of the Research Software Directory. Now you may want to make some changes to bring the frontend in line with your institute's branding. For example, you could follow the steps outlined here to change the fonts.

Now the question is, after making your changes, how do you get to see them? Here's how:

  1. Go to the terminal where you started docker-compose

  2. Use Ctrl+C to stop the running instance of Research Software Directory

  3. Check which docker containers you have with:

    docker-compose ps
    

    For example, mine says:

                    Name                              Command                State     Ports 
    ----------------------------------------------------------------------------------------
    researchsoftwaredirectory_admin_1      sh -c rm -rf /build/* && c ...   Exit 0           
    researchsoftwaredirectory_auth_1       /bin/sh -c gunicorn --prel ...   Exit 137         
    researchsoftwaredirectory_backend_1    /bin/sh -c gunicorn --prel ...   Exit 137         
    researchsoftwaredirectory_certbot_1    sh /certbot.sh                   Exit 1           
    researchsoftwaredirectory_frontend_1   /bin/sh -c sh -c "mkdir -p ...   Exit 137         
    researchsoftwaredirectory_mongo_1      /mongo.sh --bind_ip 0.0.0.0      Exit 137         
    researchsoftwaredirectory_nginx_1      /bin/sh -c sh /start.sh          Exit 137         
    researchsoftwaredirectory_tasks_1      /bin/sh -c crond -d7 -f          Exit 137         
    

    In the list above, container names consist of the directory name, the name of the service, plus a number. Use docker-compose rm to delete the container by service name, e.g. the frontend container:

    docker-compose rm --force frontend
    docker rmi --force rsdnlesc/frontend
    
  4. Rebuild containers as necessary, using:

    docker-compose -f docker-compose.yml -f docker-compose.prod.yml up --build
    

Frequently Asked Questions

Refer to the Frequently Asked Questions for more detailed answers to specific questions:

Frontend

  1. How do I change the font?
  2. How do I change the logo?
  3. How do I change the colors?

Tasks

  1. How do I change when data collection scripts run?

For maintainers

Making a release

  1. Update the submodules to the latest version that the remote knows about

    git submodule update --remote --merge
    # check the status
    git submodule status
    # if there are any SHAs preceded by a plus sign, you need
    # to git add them, e.g.
    git add db-dump 
    git commit -m "updated db-dump submodule to the latest version"
  2. Gather information on submodules such that it will make it to Zenodo, e.g.

    git submodule status > submodules.sha.txt
  3. Write the release notes, include the content of submodules.sha.txt

  4. Update CITATION.cff

  5. Generate the metadata file for Zenodo using cffconvert.

    pip install --user cffconvert
    cffconvert --outputformat zenodo --ignore-suspect-keys --outfile .zenodo.json
    # git add, commit, and push everything
  6. Make sure that everything is pushed

    cd $(mktemp -d)
    git clone --recursive https://github.com/research-software-directory/research-software-directory.git
    cd research-software-directory
  7. Follow the notes from the 'For users' section above, and verify that it all works as it should.

  8. Use GitHub's Draft a new release button here to make a release.