{"id":28395175,"url":"https://github.com/databiosphere/calhoun","last_synced_at":"2025-06-27T01:31:13.771Z","repository":{"id":43271661,"uuid":"153499543","full_name":"DataBiosphere/calhoun","owner":"DataBiosphere","description":"Notebook preview service","archived":false,"fork":false,"pushed_at":"2025-06-11T13:28:05.000Z","size":481,"stargazers_count":3,"open_issues_count":6,"forks_count":0,"subscribers_count":23,"default_branch":"dev","last_synced_at":"2025-06-11T14:45:14.985Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataBiosphere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-10-17T17:48:06.000Z","updated_at":"2025-06-11T13:26:46.000Z","dependencies_parsed_at":"2024-12-11T19:18:58.171Z","dependency_job_id":"4af1d520-0ba3-47d1-9cad-f7b6d7cde779","html_url":"https://github.com/DataBiosphere/calhoun","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DataBiosphere/calhoun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fcalhoun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fcalhoun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fcalhoun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fcalhoun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataBiosphere","download_url":"https://codeload.github.com/DataBiosphere/calhoun/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fcalhoun/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262172359,"owners_count":23269991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-31T19:39:24.236Z","updated_at":"2025-06-27T01:31:13.755Z","avatar_url":"https://github.com/DataBiosphere.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Calhoun\nJupyter notebook preview service\n\n## Background\nThis project is part of the Terra platform of service APIs. It is primarily intended to provide preview versions of notebooks and R markdown files for Terra-based web applications, such as the [Terra workbench](https://www.terra.bio) research environment.\n\n## Description\nYour web-app needs to display read-only versions of Jupyter notebooks and R markdown files.\n\nUnder the hood, Jupyter .ipynb files are JSON documents with a particular [format](https://nbformat.readthedocs.io). Jupyter provides a commandline tool / library [nbconvert](https://nbconvert.readthedocs.io) for interacting with these documents and converting them to various formats, in particular HTML.\n\nSimilarly, R Markdown .Rmd files are documents with a particular [format](https://bookdown.org/yihui/rmarkdown/markdown-document.html), and the [rmarkdown](https://cran.r-project.org/web/packages/rmarkdown/index.html) package provides mechanisms for converting R Markdown documents to HTML.\n\nThis project is essentially nbconvert and rmarkdown as a REST service. It takes an input notebook or R Markdown document and returns HTML that can be embedded in your application.\n\n## API\n\nA swagger-ui page is available at /swagger-ui/ on any running instance. For existing instances, those are:\n\n* dev: https://calhoun.dsde-dev.broadinstitute.org/swagger-ui/\n* staging: https://calhoun.dsde-staging.broadinstitute.org/swagger-ui/\n* prod: https://calhoun.dsde-prod.broadinstitute.org/swagger-ui/\n\n## Framework\n\nThis project uses the [Flask](https://flask.palletsprojects.com/en/1.1.x/) Python web framework.\n\n## Managing dependencies\n\nWe use [Poetry](https://python-poetry.org/docs/) to manage our dependencies. From their website:\n\n\u003e Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.\n\nInstall [Poetry](https://python-poetry.org/docs/)\n\n```sh\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n\nIf you need to change any dependency versions:\n- update the pyproject.toml file\n- run the following to update the lock file\n\n```sh\npoetry lock\n```\n\nTo install dependencies\n```sh\npoetry install\n```\n\nTo update dependencies\n```sh\npoetry update\n```\n\n## Running locally\n\nRun a local containerized server:\n\n```sh\ndocker image build . -t calhoun-test:0\ndocker kill t1\ndocker run \\\n  -e SAM_ROOT=https://sam.dsde-dev.broadinstitute.org \\\n  --rm -itd --name t1 -p 8080:8080 calhoun-test:0\n```\nThis will start a Calhoun server at localhost:8080.\n\nAccess the application locally:\n* http://localhost:8080/status\n* http://localhost:8080/swagger-ui\n\n### Alternative (no Docker container)\n\nYou can skip the container and run a local app with [Flask](https://flask.palletsprojects.com/en/1.1.x/):\n\n```sh\npython3 -m venv env\nsource env/bin/activate\npip install Flask\nexport FLASK_DEBUG=1\n```\n\n#### Dependencies for running containerless\n\nInstall [Pandoc](https://pandoc.org/installing.html) and R\n```sh\nbrew install pandoc\nbrew install R\n```\n\nInstall R packages\n```sh\nR\n\u003e install.packages(c(\"rmarkdown\", \"stringi\", \"tidyverse\", \"Seurat\", \"ggforce\"))\n```\n\nInstall [Poetry](https://python-poetry.org/docs/) and project dependencies\n```sh\ncurl -sSL https://install.python-poetry.org\npoetry install\n```\n\nWrite a dev config file\n```sh\ncp config.py config.dev.py\n```\n\nEnsure etc/hosts file has the following record:\n```\n127.0.0.1       local.dsde-dev.broadinstitute.org\n```\n\nOnce complete, copy `vault read secret/dsde/firecloud/dev/common/server.crt` to `/etc/ssl/certs` and\n`vault read secret/dsde/firecloud/dev/common/server.key` to `/etc/ssl/private`.\n\n#### Serve the containerless app\n\nRun a local server\n```sh\nDEVELOPMENT='true' SAM_ROOT='https://sam.dsde-dev.broadinstitute.org' python3 main.py\n```\n\n## Running locally with terra-ui\n\n- point the calhoun URL in the terra-ui [dev config](https://github.com/DataBiosphere/terra-ui/blob/dev/config/dev.json) to your local url http://localhost:8080\n- run a local [terra-ui](https://github.com/DataBiosphere/terra-ui)\n- Look at previews!\n\n## Automated testing\n\nRun unit tests locally\n```sh\n./scripts/unit-test.sh\n```\n\nRun automation tests locally\n```sh\ngcloud auth login \u003cany-terra-dev-user\u003e\nRUN_AUTHENTICATED_TEST=1 ./scripts/automation-test.sh\n```\n\nIf you add a new test case, make sure it is imported and added to `test_cases` in `unit_test.py`.\n\n## Deployment\n\nUpon merging a change to dev, the build github workflow will:\n- Build the new image\n- Automatically update the calhoun version in terra-helmfile\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabiosphere%2Fcalhoun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabiosphere%2Fcalhoun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabiosphere%2Fcalhoun/lists"}