cli: document running invenio cmds

closes #85

Author: fenekku

README.md

@@ -1,4 +1,4 @@
-# docs.reana.io
+# inveniordm.docs.cern.ch
 
 [![Travis Build Status](https://img.shields.io/travis/inveniosoftware/docs-invenio-rdm.svg)](https://travis-ci.org/inveniosoftware/docs-invenio-rdm.svg) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/inveniosoftware/InvenioRDM?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![License](https://img.shields.io/github/license/inveniosoftware/InvenioRDM.svg)](https://github.com/inveniosoftware/docs-invenio-rdm/blob/master/LICENSE)
 
@@ -14,4 +14,3 @@ $ pip install -r requirements.txt
 $ mkdocs serve
 $ firefox http://127.0.0.1:8000
 ```
-

docs/deployment/kubernetes.md

@@ -1 +1,3 @@
-# Kubernetes
+# Kubernetes
+
+Coming soon

docs/deployment/openshift.md

@@ -1 +1,3 @@
 # OpenShift
+
+Coming soon

docs/develop/customize.md

@@ -19,6 +19,6 @@ Building assets...
 
 Passing the `--no-install-js` option, skips re-installation of JS dependencies.
 
-Go to the browser [*https://localhost:5000/*](https://localhost:5000) or refresh the page. And voila! The logo has been changed!
+Go to the browser [*https://localhost:5000/*](https://localhost:5000) or refresh the page. And voilà! The logo has been changed!
 
 **WARNING**: If you do not see it changing, check in an incognito window, the browser might have cached the logo.

docs/develop/init.md renamed to docs/develop/index.md

@@ -1,9 +1,9 @@
 # Getting Started
 
 You are now ready to learn how to create, customize and iterate on your own
-InvenioRDM instance. The previous section showed you what is the equivalent of
-a deploy compilation when working with a compiled language: it gets you the final
-result, but you wouldn't do that when developing.
+InvenioRDM instance. In fact, the previous section showed you the last step before
+deploying. You wouldn't want to fully containerize your application in the day
+to day of developing your instance.
 
 When working on your InvenioRDM application, you will want to use the commands
 and the workflow we explain in these pages.

docs/develop/install_locally.md

@@ -70,7 +70,7 @@ Assigning superuser access to admin role...
 
 **Known issues**:
 
-The Elasticsearch container might crash due to lack of memory. One solution is to increase the maximum allowed allocation per process (See more [here](https://www.elastic.co/guide/en/elasticsearch/reference/6.6/docker.html)). Solving this issue depends on your OS:
+The Elasticsearch container might crash due to lack of memory. One solution is to increase the maximum allowed allocation per process (See more [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.6/docker.html)). Solving this issue depends on your OS:
 
 On Linux, add the following to ``/etc/sysctl.conf`` on your local machine (host machine):
 

docs/develop/run.md

@@ -153,7 +153,7 @@ $ curl -k -XGET https://localhost:5000/api/records/?q=doge | python3 -m json.too
 
 Alternatively, you can use the web UI.
 
-Navigate to https://localhost:5000/search . Note that you might need to accept the SSL exception since it's using a test certificate.
+Navigate to https://localhost:5000/ . Note that you might need to accept the SSL exception since it's using a test certificate.
 And visit the record page for the newly created record. You will see it has no files associated with it. Let's change that!
 
 ### Upload a file to a record
@@ -169,9 +169,7 @@ Save it as `snow_doge.jpg` in your current directory. Then upload it to the reco
 **WARNING** Change `pv1dx-rwa61` in the URLs below for the recid of your record.
 
 ```
-$ curl -k -X PUT https://localhost:5000/api/records/pv1dx-rwa61/files/snow_doge.jpg \
-        -H "Content-Type: application/octet-stream" \
-        --data-binary @snow_doge.jpg
+$ curl -k -X PUT https://localhost:5000/api/records/pv1dx-rwa61/files/snow_doge.jpg -H "Content-Type: application/octet-stream" --data-binary @snow_doge.jpg
 ```
 
 This file can then be previewed on the record page and even downloaded.

docs/index.md

@@ -2,13 +2,14 @@
 
 Welcome to the InvenioRDM project!
 
-InvenioRDM is a ready-to-go Research Data Management web application putting
-together the Invenio framework so you don't have to.
+InvenioRDM is a ready-to-go turn-key Research Data Management repository. It
+puts together the Invenio framework so you don't have to.
 
-This documentation walks you through installing, developing and deploying
-your very own InvenioRDM instance. Follow the below sections in order to get a
-full picture of using InvenioRDM or go straight to what you're interested in -
-each section is independent.
+This documentation walks you through installing, configuring and deploying
+your very own InvenioRDM instance. Furthermore, you can customize it for your
+need and even add your own extensions! Follow the below sections in order to
+get a full picture of using InvenioRDM or go straight to what you're interested
+in - each section is independent.
 
 
 ## Install
@@ -19,7 +20,27 @@ allows you to easily install an instance and manage it.
 
 [> Installation Guide](install/index.md)
 
+## Preview
 
-Preview
-Develop
-Deploy
+To quickly get a sense for what InvenioRDM is and can do, you can preview
+the default instance after installing `invenio-cli`. Just follow the one page
+guide below.
+
+[> Quickly Preview an Instance](preview/index.md)
+
+## Develop
+
+Once you are ready to dive in and work on your own instance - that is,
+configure, customize, debug and iterate -, you will want to setup your project
+for development. Various commands are at your disposal and we walk you through
+the workflow to be effective with them.
+
+[> Getting Started on your Instance](preview/index.md)
+
+## Deploy
+
+Ready to deploy into production? Follow these guides to put a small instance in
+production and learn the avenues to take and decisions to make to grow it.
+Whether you use Openshift or Kubernetes, we got you covered.
+
+[> Deployment Guides](deployment/openshift.md)

docs/preview/index.md

@@ -13,7 +13,7 @@ First, we need to create the project - the necessary files and folders for your
 The CLI will require the following data:
 
 - **Project name**: Title of your project with space allowed (project name for humans)
-- **Project short name**: Hyphenated and lowercased title or (project name for machines)
+- **Project short name**: Hyphenated and lowercased title (project name for machines)
 - **Project website**: URL where the project will be deployed
 - **Github repository**: Repository in format `<owner>/<code repository>`
 - **Description**: Short description of project
@@ -68,17 +68,20 @@ $ ls -la february-release
 total 56
 drwxr-xr-x 5 youruser youruser 4096 Feb 19 13:45 ./
 drwxr-xr-x 5 youruser youruser 4096 Feb 19 13:45 ../
+drwxr-xr-x 3 youruser youruser 4096 Feb 19 13:45 assets/
 drwxr-xr-x 4 youruser youruser 4096 Feb 19 13:45 docker/
 -rw-r--r-- 1 youruser youruser 2932 Feb 19 13:45 docker-compose.full.yml
 -rw-r--r-- 1 youruser youruser  943 Feb 19 13:45 docker-compose.yml
 -rw-r--r-- 1 youruser youruser 1152 Feb 19 13:45 Dockerfile
+-rw-r--r-- 1 youruser youruser   46 Feb 19 13:45 .dockerignore
 -rw-r--r-- 1 youruser youruser 2665 Feb 19 13:45 docker-services.yml
 -rw-r--r-- 1 youruser youruser 2018 Feb 19 13:45 .invenio
 -rw-r--r-- 1 youruser youruser 1504 Feb 19 13:45 invenio.cfg
 drwxr-xr-x 2 youruser youruser 4096 Feb 19 13:45 logs/
 -rw-r--r-- 1 youruser youruser  431 Feb 19 13:45 Pipfile
 -rw-r--r-- 1 youruser youruser  756 Feb 19 13:45 README.rst
 drwxr-xr-x 3 youruser youruser 4096 Feb 19 13:45 static/
+drwxr-xr-x 2 youruser youruser 4096 Feb 19 13:45 templates/
 ```
 
 **Notes and Known Issues**
@@ -104,8 +107,30 @@ Visit https://localhost
 $ firefox https://localhost
 ```
 
-That is literally it! You now have a running instance of InvenioRDM at
-https://localhost . You can get a sense for what InvenioRDM offers and explore.
+You now have a running instance of InvenioRDM at [https://localhost](https://localhost),
+but it doesn't have any records in it. For demonstration purposes, we will add
+randomly generated records:
+
+``` console
+$ invenio-cli demo --containers
+```
+
+You can now get a full sense for what InvenioRDM offers and explore.
+
+
+## Running Invenio commands
+
+If you are already familiar with Invenio and the many commands its CLI (`invenio`)
+provides, you might be wondering how to execute those. Because the entire application
+is containerized, you need to connect to the web-api or web-ui container in order
+to use one of those commands. In fact, this is what `invenio-cli` does behind the scene!
+
+``` console
+$ docker exec -it <container name or id> /bin/bash
+# invenio <your command>
+```
+
+You can use `docker ps` to get the name or id of the web-api or web-ui container.
 
 
 ## Conclusions
@@ -124,5 +149,5 @@ $ firefox https://localhost
 
 These instructions don't provide you with a nice development experience though.
 You need to run `invenio-cli containerize` for every change you make in your
-project. That's slow and cumbersome. Up next, we show how to develop your
-local instance and set yourself up to be productive!
+project. That's slow and cumbersome. Up next, we show how to [develop your
+local instance](../develop/index.md) and set yourself up to be productive!

mkdocs.yml

@@ -8,7 +8,7 @@ repo_name: 'docs-invenio-rdm'
 repo_url: 'https://github.com/inveniosoftware/docs-invenio-rdm'
 
 # Copyright
-copyright: 'Copyright © 2020 CERN and Northwestern University.'
+copyright: 'Copyright © 2019-2020 CERN and Northwestern University.'
 
 # Configuration
 theme:
@@ -29,7 +29,7 @@ nav:
   - Install: 'install/index.md'
   - Preview: 'preview/index.md'
   - Develop:
-    - Getting Started: 'develop/init.md'
+    - Getting Started: 'develop/index.md'
     - Install Locally: 'develop/install_locally.md'
     - Run: 'develop/run.md'
     - Configuration: 'develop/config.md'