X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/0bf166a618c7dafcffa3cf0602dc7f09f521e3b7..44c95f99098fa6c6acbfa82d4b6cbc6015eb6e39:/README.md diff --git a/README.md b/README.md index 9ced1d11d1..367c3e8f60 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,79 @@ -# Arvados-in-a-box +[//]: # Copyright (C) The Arvados Authors. All rights reserved. +[//]: # +[//]: # SPDX-License-Identifier: CC-BY-SA-3.0 -Self-contained development, demonstration and testing environment for Arvados. +[Arvados](https://arvados.org) is a free software distributed computing platform +for bioinformatics, data science, and high throughput analysis of massive data +sets. Arvados supports a variety of cloud, cluster and HPC environments. + +Arvados consists of: + +* *Keep*: a petabyte-scale content-addressed distributed storage system for managing and + storing collections of files, accessible via HTTP and FUSE mount. + +* *Crunch*: a Docker-based cluster and HPC workflow engine designed providing + strong versioning, reproducibilty, and provenance of computations. + +* Related services and components including a web workbench for managing files + and compute jobs, REST APIs, SDKs, and other tools. ## Quick start -``` -$ bin/arvbox reboot localdemo -``` +Curoverse maintains an Arvados public cloud demo at +[https://cloud.curoverse.com](https://cloud.curoverse.com). A Google account +is required to log in. -## Usage +To try out Arvados on your local workstation, you can use Arvbox, which +provides Arvados components pre-installed in a Docker container (requires +Docker 1.9+). After cloning the Arvados git repository: ``` -Arvados-in-a-box - -arvbox (build|start|run|open|shell|ip|stop|reboot|reset|destroy|log|svrestart) - -build build arvbox Docker image -start|run start arvbox container -open open arvbox workbench in a web browser -shell enter arvbox shell -ip print arvbox ip address -stop stop arvbox container -restart stop, then run again -reboot stop, build arvbox Docker image, run -reset delete arvbox arvados data (be careful!) -destroy delete all arvbox code and data (be careful!) -log tail log of specified service -svrestart restart specified service inside arvbox -clone clone an arvbox +$ cd arvados/tools/arvbox/bin +$ ./arvbox start localdemo ``` -## Requirements - -* Linux 3.x+ and Docker 1.9+ -* Minimum of 3 GiB of RAM + additional memory to run jobs -* Minimum of 3 GiB of disk + storage for actual data - -## Configs - -### dev -Development configuration. Boots a complete Arvados environment inside the -container. The "arvados", "arvado-dev" and "sso-devise-omniauth-provider" code -directories along data directories "postgres", "var", "passenger" and "gems" -are bind mounted from the host file system for easy access and persistence -across container rebuilds. Services are bound to the Docker container's -network IP address and can only be accessed on the local host. - -### localdemo -Demo configuration. Boots a complete Arvados environment inside the container. -Unlike the development configuration, code directories are included in the demo -image, and data directories are stored in a separate data volume container. -Services are bound to the Docker container's network IP address and can only be -accessed on the local host. - -### test -Run the test suite. - -### publicdev -Publicly accessible development configuration. Similar to 'dev' except that -service ports are published to the host's IP address and can accessed by anyone -who can connect to the host system. WARNING! The public arvbox configuration -is NOT SECURE and must not be placed on a public IP address or used for -production work. - -### publicdemo -Publicly accessible development configuration. Similar to 'localdemo' except -that service ports are published to the host's IP address and can accessed by -anyone who can connect to the host system. WARNING! The public arvbox configuration -is NOT SECURE and must not be placed on a public IP address or used for -production work. - -## Environment variables - -### ARVBOX_DOCKER -The location of Dockerfile.base and associated files used by "arvbox build". -default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker) - -### ARVBOX_CONTAINER -The name of the Docker container to manipulate. -default: arvbox - -### ARVBOX_BASE -The base directory to store persistent data for arvbox containers. -default: $HOME/.arvbox - -### ARVBOX_DATA -The base directory to store persistent data for the current container. -default: $ARVBOX_BASE/$ARVBOX_CONTAINER - -### ARVADOS_ROOT -The root directory of the Arvados source tree -default: $ARVBOX_DATA/arvados - -### ARVADOS_DEV_ROOT -The root directory of the Arvados-dev source tree -default: $ARVBOX_DATA/arvados-dev - -### SSO_ROOT -The root directory of the SSO source tree -default: $ARVBOX_DATA/sso-devise-omniauth-provider - -### ARVBOX_PUBLISH_IP -The IP address on which to publish services when running in public -configuration. Overrides default detection of the host's IP address. - -## Notes - -Services are designed to install and auto-configure on start or restart. For -example, the service script for keepstore always compiles keepstore from source -and registers the daemon with the API server. - -Services are run with process supervision, so a service which exits will be -restarted. Dependencies between services are handled by repeatedly trying and -failing the service script until dependencies are fulfilled (by other service -scripts) enabling the service script to complete. +In this mode you will only be able to connect to Arvbox from the same host. To +configure Arvbox to be accessible over a network and for other options see +http://doc.arvados.org/install/arvbox.html for details. + +## Documentation + +Complete documentation, including a User Guide, Installation documentation and +API documentation is available at http://doc.arvados.org/ + +If you wish to build the Arvados documentation from a local git clone, see +doc/README.textile for instructions. + +## Community + +The [#arvados](irc://irc.oftc.net:6667/#arvados IRC) (Internet Relay Chat) +channel at the +[Open and Free Technology Community (irc.oftc.net)](http://www.oftc.net/oftc/) +is available for live discussion and support. You can use a traditional IRC +client or [join OFTC over the web.](https://webchat.oftc.net/?channels=arvados) + +The +[Arvados user mailing list](http://lists.arvados.org/mailman/listinfo/arvados) +is a forum for general discussion, questions, and news about Arvados +development. The +[Arvados developer mailing list](http://lists.arvados.org/mailman/listinfo/arvados-dev) +is a forum for more technical discussion, intended for developers and +contributers to Arvados. + +## Development + +[![Build Status](https://ci.curoverse.com/buildStatus/icon?job=run-tests)](https://ci.curoverse.com/job/run-tests/) +[![Go Report Card](https://goreportcard.com/badge/github.com/curoverse/arvados)](https://goreportcard.com/report/github.com/curoverse/arvados) + +The Arvados public bug tracker is located at https://dev.arvados.org/projects/arvados/issues + +Continuous integration is hosted at https://ci.curoverse.com/ + +Instructions for setting up a development environment and working on specific +components can be found on the +["Hacking Arvados" page of the Arvados wiki](https://dev.arvados.org/projects/arvados/wiki/Hacking). + +## Licensing + +Arvados is Free Software. See COPYING for information about Arvados Free +Software licenses.