diff --git a/docs/latest/essentials/getting-started.md b/docs/latest/essentials/getting-started.md index 8668d78e4..9fc6784f9 100644 --- a/docs/latest/essentials/getting-started.md +++ b/docs/latest/essentials/getting-started.md @@ -1,43 +1,59 @@ # Getting Started -## Getting the Code +## Setup -Either clone the repository using Git: - -```bash -git clone git@github.com:OHIF/Viewers.git -``` - -or -[Download the latest Master as a ZIP File](https://github.com/OHIF/Viewers/archive/master.zip). - -## Run the OHIF Viewer application against our public DICOM server - -You can either spin up locally or run with Docker. - -### running locally - -1. [Install Node.js](https://nodejs.org/en/) -2. Open a new terminal tab, go under `ohif-viewer` directory and install all - dependency packages via `yarn` +### Fork & Clone + +If you intend to contribute back changes, or if you would like to pull updates +we make to the OHIF Viewer, then follow these steps: + +- [Fork][fork-a-repo] the [OHIF/Viewers][ohif-viewers-repo] repository +- [Create a local clone][clone-a-repo] of your fork + - `git clone https://github.com/YOUR-USERNAME/Viewers` +- Add OHIF/Viewers as a [remote repository][add-remote-repo] labled `upstream` + - Navigate to the cloned project's directory + - `git remote add upstream https://github.com/OHIF/Viewers.git` + +With this setup, you can now [sync your fork][sync-changes] to keep it +up-to-date with the upstream (original) repository. This is called a "Triangular +Workflow" and is common for Open Source projects. The GitHub blog has a [good +graphic that illustrates this setup][triangular-workflow]. + +### Private + +Alternatively, if you intend to use the OHIF Viewer as a starting point, and you +aren't as concerned with syncing updates, then follow these steps: + +1. Navigate to the [OHIF/Viewers/tree/react][ohif-viewers-react-repo] repository + and branch +2. Click `Clone or download`, and then `Download ZIP` +3. Use the contents of the `.zip` file as a starting point for your viewer + +> NOTE: It is still possible to sync changes using this approach. However, +> submitting pull requests for fixes and features are best done with the +> separate, forked repository setup described in "Fork & Clone" + +## Develop + +### Requirements + +- [Node.js & NPM](https://nodejs.org/en/) +- [Yarn](https://yarnpkg.com/en/) + +### Kick the tires + +Navigate to the root of the project's directory in your terminal and run the +following commands: ```bash +# Restore dependencies yarn install -``` -3. Run the application - -```bash +# Start local development server yarn start ``` -Note: This will connect to our public DICOMWeb server so you can verify your -installation. Follow the next section to connect to your own local or remote -DICOMWeb server. - -4. Launch the OHIF Viewer Study List. By default the address is - [http://localhost:3000/](http://localhost:3000/). The port may vary so check - the start up output messages such as: +You should see the following output: ```bash Compiled successfully! @@ -51,6 +67,16 @@ Note that the development build is not optimized. To create a production build, use yarn build. ``` +### Configuring + +Note: This will connect to our public DICOMWeb server so you can verify your +installation. Follow the next section to connect to your own local or remote +DICOMWeb server. + +4. Launch the OHIF Viewer Study List. By default the address is + [http://localhost:3000/](http://localhost:3000/). The port may vary so check + the start up output messages such as: + **If everything is working correctly, you should see the studies from our public archive when you visit the Study List.** @@ -180,3 +206,21 @@ Please visit the link to read about how to set environment variables on Windows. your docker instances. - If you see any errors in your server console, check the [Troubleshooting](./troubleshooting.md) page for more in depth advice. + + + + +[fork-a-repo]: https://help.github.com/en/articles/fork-a-repo +[clone-a-repo]: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork +[add-remote-repo]: https://help.github.com/en/articles/fork-a-repo#step-3-configure-git-to-sync-your-fork-with-the-original-spoon-knife-repository +[sync-changes]: https://help.github.com/en/articles/syncing-a-fork +[triangular-workflow]: https://github.blog/2015-07-29-git-2-5-including-multiple-worktrees-and-triangular-workflows/#improved-support-for-triangular-workflows +[ohif-viewers-repo]: https://github.com/OHIF/Viewers +[ohif-viewers-react-repo]: https://github.com/OHIF/Viewers/tree/react + + +``` + +```