Add documentation for 'orgs init'

CHANGELOG.md

@@ -11,7 +11,9 @@ Initial release. It includes a `docker-compose.yml` file to deploy source{d} CE
 
 The `sourced` binary is a wrapper for Docker Compose that downloads the `docker-compose.yml` file from this repository, and includes the following sub commands:
 
-- `init`: Install and initialize containers
+- `init`: Install and initialize containers to analyze local repositories
+- `orgs`: Manage services to analyze code from GitHub organizations
+  - `init`: Install and initialize containers to analyze GitHub organizations
 - `status`: Shows status of the components
 - `stop`: Stop running containers
 - `start`: Start stopped containers

README.md

@@ -7,6 +7,7 @@
   - [Install source{d} Community Edition](#install-source-d-community-edition)
 - [Usage](#usage)
   - [Defaults](#defaults)
+  - [Initialization](#initialization)
   - [Commands](#commands)
   - [Working With Multiple Data Sets](#working-with-multiple-data-sets)
 - [Docker Compose](#docker-compose)
@@ -68,9 +69,33 @@ You may also choose to manage the containers yourself with the `docker-compose.y
 - Default login: `admin`
 - Default password: `admin`
 
-### Commands
 
-#### Init
+### Initialization
+
+**source{d} CE** can be initialized from 2 different data sources: local Git repositories, or GitHub organizations.
+
+Please note that you have to choose one data source to initialize **source{d} CE**, but you can have more than one isolated environment, and they can have different sources. See the [Working With Multiple Data Sets](#working-with-multiple-data-sets) section below for more details.
+
+#### From GitHub Organizations
+
+When using GitHub organizations to populate the **source{d} CE** database you only need to provide a list of organization names, and a [GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). The token should have the following scopes enabled:
+
+- [x] `repo`  Full control of private repositories
+- [ ] `admin:org`  Full control of orgs and teams, read and write org projects
+  - [ ] `write:org`  Read and write org and team membership, read and write org projects
+  - [x] `read:org`  Read org and team membership, read org projects
+
+Use this command to initialize:
+
+```shell
+sourced orgs init --token <token> src-d,bblfsh
+```
+
+It will automatically open the web UI. Use login: `admin` and password `admin` to access it.
+
+If the UI wasn't opened automatically, use `sourced web` or visit http://localhost:8088.
+
+#### From Local Repositories
 
 ```
 sourced init /path/to/repositories
@@ -84,6 +109,8 @@ It will automatically open the web UI. Use login: `admin` and password `admin` t
 
 If the UI wasn't opened automatically, use `sourced web` or visit http://localhost:8088.
 
+### Commands
+
 #### Start
 
 ```
@@ -182,29 +209,35 @@ Set the active docker compose file.
 
 ### Working With Multiple Data Sets
 
-You can deploy more than one **source{d} CE** instance with different sets of repositories to analyze.
+You can deploy more than one **source{d} CE** instance with different sets of organizations, or repositories, to analyze.
 
-For example you may have initially started **source{d} CE** with the repositories in `~/repos`, with the command:
+For example you may have initially started **source{d} CE** with the repositories in the `src-d` organization, with the command:
 ```
-sourced init ~/repos
+sourced orgs init --token <token> src-d
 ```
 
-After a while you may want to analyze the data on another set of repositories. You can run `init` again with a different path:
+After a while you may want to analyze the data on another set of repositories. You can run `init` again with a different organization:
 ```
-sourced init ~/go/src/github.com/src-d
+sourced orgs init --token <token> bblfsh
 ```
 
-This command will stop any of the currently running containers, create an isolated environment for the new repositories path, and create a new, clean deployment.
+This command will stop any of the currently running containers, create an isolated environment for the new data, and create a new, clean deployment.
 
-Please note that each path will have an isolated deployment. This means that for example any chart or dashboard created for the deployment using `~/repos` will not be available to the new deployment for `~/go/src/github.com/src-d`.
+Please note that each path will have an isolated deployment. This means that for example any chart or dashboard created for the deployment for `src-d` will not be available to the new deployment for `bblfsh`.
 
-Each isolated environment is persistent (unless you run `prune`). Which means that if you decide to re-deploy **source{d} CE** using the original set of repositories:
+Each isolated environment is persistent (unless you run `prune`). Which means that if you decide to re-deploy **source{d} CE** using the original organization:
 ```
-sourced init ~/repos
+sourced orgs init --token <token> src-d
 ```
 
 You will get back to the previous state, and things like charts and dashboards will be restored.
 
+These isolated environments also allow you to deploy **source{d} CE** using a local set of Git repositories. For example, if we wanted a third deployment to analyze repositories already existing in the `~/repos` directory, we just need to run `init` again:
+
+```
+sourced init ~/repos
+```
+
 If you are familiar with Docker Compose and you want more control over the underlying resources, you can explore the contents of your `~/.sourced` directory. There you will find a `docker-compose.yml` and `.env` files for each set of repositories used by `sourced init`.
 
 ## Docker Compose

cmd/sourced/cmd/init.go

@@ -15,7 +15,7 @@ import (
 )
 
 type initCmd struct {
-	Command `name:"init" short-description:"Install and initialize containers" long-description:"Install, initialize, and start all the required docker containers, networks, volumes, and images.\n\nThe repos directory argument must point to a directory containing git repositories.\nIf it's not provided, the current working directory will be used."`
+	Command `name:"init" short-description:"Install and initialize containers to analyze local repositories" long-description:"Install, initialize, and start all the required docker containers, networks, volumes, and images.\n\nThe repos directory argument must point to a directory containing git repositories.\nIf it's not provided, the current working directory will be used."`
 
 	Args struct {
 		Reposdir string `positional-arg-name:"workdir"`

cmd/sourced/cmd/orgs.go

@@ -13,13 +13,13 @@ import (
 )
 
 type orgsCmd struct {
-	cli.PlainCommand `name:"orgs" short-description:"Manages services to analyze code from GitHub organizations"`
+	cli.PlainCommand `name:"orgs" short-description:"Manage services to analyze code from GitHub organizations" long-description:"Manage services to analyze code from GitHub organizations"`
 }
 
 type orgsInitCmd struct {
-	Command `name:"init" short-description:"Install and initialize containers to analyze github organizations" long-description:"Install, initialize, and start all the required docker containers, networks, volumes, and images.\n\nThe orgs argument must a list of the organizations to be analyzed."`
+	Command `name:"init" short-description:"Install and initialize containers to analyze GitHub organizations" long-description:"Install, initialize, and start all the required docker containers, networks, volumes, and images.\n\nThe orgs argument must a comma-separated list of GitHub organization names to be analyzed."`
 
-	Token string `short:"t" long:"token" description:"Github token for the passed organizations. It should be granted with 'repo' and 'read:org' scopes." required:"true"`
+	Token string `short:"t" long:"token" env:"SOURCED_GITHUB_TOKEN" description:"Github token for the passed organizations. It should be granted with 'repo' and 'read:org' scopes." required:"true"`
 	Args  struct {
 		Orgs []string `required:"yes"`
 	} `positional-args:"yes" required:"1"`