Developer Guides - As a new developer, I want a single page set of quick and easy instructions for installing Dataverse

[mheppler]

We need a simpler set of instructions for installing Dataverse. This is commonly known as a "Quick Start" guide.

If you are a developer, and you want to install Dataverse, you would go to the Developer Guide > Development Environment. There are over 4,200 words on that page. The instructions you are expected to follow, "Setting Up Your Dev Environment", are buried four sections down.

The instructions in that section have a word count of nearly 900, which I am sure we could trim down to make a "Quick Start" guide. A quick test in Google Drive, by copying that entire section into a new document, has one page of instructions at just about 325 words.

[mheppler]

First attempt at a rough draft cut the instructions from 893 words to 420. (Counts vary depending on the tool used.) There is much more we can improve upon here. I'll leave this here for future reference until we prioritize this. (Full disclosure, did not test these instructions 😝.)

Set Up Your Dev Environment

This quick start guide to setting up your Dataverse development environment should only take you 10-20 minutes to complete.

Prerequisites
- Clone Dataverse Repository from GitHub
- Build WAR File
- Install Solr

Once you have all of that set up, it is time to Install Dataverse by running the installer script.

Let's get started!

Clone Dataverse Repository from GitHub

Fork the `IQSS/dataverse` repository in GitHub at https://github.com/IQSS/dataverse.

If you are a developer with push access to the repo, use:

`git clone [email protected]:IQSS/dataverse.git`

Tip: You can use git with passwords over HTTPS, but it’s much nicer to set up SSH keys. https://github.com/settings/ssh is the place to manage the ssh keys GitHub knows about for you.

Build WAR File

The first time you build the war file, it may take a few minutes while dependencies are downloaded from Maven Central. You can build the WAR file from both Netbean or the terminal, but in both cases, you’ll want to see the output “BUILD SUCCESS”.

From Netbeans, click “Run” and then “Build Project (dataverse)”. From the terminal, make sure you are in the direcotry that you cloned the git repo into with `cd dataverse`, and then run `mvn package`. If the `mvn` command is not available, you need to install Maven, which is mentioned in the Tools section.

Install Solr

A Dataverse-specific schema.xml configuration file (described below) is required.

Download solr-4.6.0.tgz from http://archive.apache.org/dist/lucene/solr/4.6.0/solr-4.6.0.tgz to any directory you like but in the example below, we have downloaded the tarball to a directory called “solr” in our home directory. For now we are using the “example” template but we are replacing schema.xml with our own. We will also assume that the clone on the Dataverse repository was retrieved using NetBeans and that it is saved in the path ~/NetBeansProjects.

    cd ~/solr
    tar xvfz solr-4.6.0.tgz
    cd solr-4.6.0/example
    cp ~/NetBeansProjects/dataverse/conf/solr/4.6.0/schema.xml solr/collection1/conf/schema.xml
    java -jar start.jar

Once Solr is up and running you should be able to see a “Solr Admin” dashboard at http://localhost:8983/solr

Install Dataverse

Now that you have all the prerequisites in place, you need to configure the environment for the Dataverse app - configure the database connection, set some options, etc. The installer script will do it all for you by prompting you for the neccessary configuration values. It is recommended that you choose “localhost” for your hostname if this is a development environment. For everything else it should be safe to accept the defaults.

Assuming that the clone on the Dataverse repository was retrieved using NetBeans and that it is saved in the path ~/NetBeansProjects:

cd ~/NetBeansProjects/dataverse/scripts/installer

./install

[pdurbin]

One of the reasons the "dev environment" page is so long is that I keep adding stuff to it about Docker, Kubernetes, and OpenShift. In 6bee8d1 (no pull request yet), I'm putting all that content in its own page.

Next I intend to move the following content on the "dev environment" page elsewhere:

• Iterating on Code and Redeploying
• Troubleshooting
• Shibboleth and OAuth
• Geoconnect
• DataCite

We will continue to link to all this content, especially about troubleshooting, for new developers. The idea is to make the "dev environment" page as short as possible, as @mheppler and I discussed after standup this morning.

[pdurbin]

I just made pull request #4502 but I'll probably show it to @mheppler before I move it to code review at https://waffle.io/IQSS/dataverse since I'd like to incorporate some of his ideas above. So far I've just been focusing on getting non-quickstart content out of the dev environment page.

[pdurbin]

Ok, I'm ready for code review of pull request #4502 so I just dragged it over in Waffle.

[pdurbin]

I just set up a Jenkins job to build the new shorter "dev environment" page (and the rest of the guides) hourly at http://guides.dataverse.org/en/4419-new-developer/developers/dev-environment.html

[pdurbin]

Part of why I'm working on this issue is that I want to be able to show a shorter and more focused version of the "setting up a dev environment" page to participants on SpinachCon 2018 next Friday. I just opened #4505 which is about making further improvements to the Dev Guide based on feedback from that event.

[pdurbin]

As I mentioned at standup this morning, @jggautier handed me a pristine Mac running High Sierra to test on (thanks!) and I'm running through what I wrote. I need to make a ton of changes so I'm pulling this back into development.

[pdurbin]

I just pushed 094cc54 after running through the install on High Sierra. It was a sizeable rewrite. Attached is the output from the installer: dev-install-094cc54.txt

[pdurbin]

I'm sticking this in code review for feedback. I'm borrowing a Windows laptop but I'm not sure how long I'll spend trying to get it to work. I can always make commits against #3927 if I come up with any solutions on Windows.

[pdurbin]

In 0b5db67 I just incorporated some feedback based rewrites and comments in google doc: https://docs.google.com/document/d/12OYstI-soBa0BxnWHU9u3C53JaESn4_2KuNMVrhxFNA/edit?usp=sharing

I don't have the Windows laptop in front of me today so I'm not planning on any more edits. I'm happy to keep receiving feedback.

[pdurbin]

@dlmurphy did a final check in a5ccb39 (thanks!) and I merged it so now I'm ready to point SpinachCon participants at http://guides.dataverse.org/en/develop/developers/dev-environment.html next week. I'm guessing that their feedback in #4505 will result in even more improvements. I also still have a Windows laptop on loan that I'm hoping to use to at least understand the lay of the land on Windows for #3927.