From b523197b3431839cc3181eac3e6899e2b954cc07 Mon Sep 17 00:00:00 2001 From: Pablo Panero Date: Wed, 8 Jan 2020 16:39:17 +0100 Subject: [PATCH] global: structure initialization and wiki migration --- .travis.yml | 26 ++++ LICENSE | 23 ++++ README.md | 17 +++ docs/deployment/kubernetes.md | 1 + docs/deployment/openshit.md | 1 + docs/images/favicon.ico | Bin 0 -> 1262 bytes docs/images/favicon.svg | 37 ++++++ docs/images/logo-rdm.png | Bin 0 -> 13765 bytes docs/index.md | 1 + docs/quickstart/build_setup.md | 84 +++++++++++++ docs/quickstart/cleanup.md | 12 ++ docs/quickstart/config.md | 118 ++++++++++++++++++ docs/quickstart/customize.md | 20 ++++ docs/quickstart/index.md | 1 + docs/quickstart/init.md | 88 ++++++++++++++ docs/quickstart/quickstart.md | 34 ++++++ docs/quickstart/server.md | 206 ++++++++++++++++++++++++++++++++ docs/quickstart/troubleshoot.md | 53 ++++++++ docs/stylesheets/extra.css | 117 ++++++++++++++++++ mkdocs.yml | 63 ++++++++++ requirements.txt | 10 ++ run-tests.sh | 13 ++ theme/partials/footer.html | 97 +++++++++++++++ 23 files changed, 1022 insertions(+) create mode 100644 .travis.yml create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/deployment/kubernetes.md create mode 100644 docs/deployment/openshit.md create mode 100644 docs/images/favicon.ico create mode 100644 docs/images/favicon.svg create mode 100644 docs/images/logo-rdm.png create mode 100644 docs/index.md create mode 100644 docs/quickstart/build_setup.md create mode 100644 docs/quickstart/cleanup.md create mode 100644 docs/quickstart/config.md create mode 100644 docs/quickstart/customize.md create mode 100644 docs/quickstart/index.md create mode 100644 docs/quickstart/init.md create mode 100644 docs/quickstart/quickstart.md create mode 100644 docs/quickstart/server.md create mode 100644 docs/quickstart/troubleshoot.md create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.yml create mode 100644 requirements.txt create mode 100644 run-tests.sh create mode 100644 theme/partials/footer.html diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..c890ae67 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,26 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2019 CERN. +# Copyright (C) 2019 Northwestern University. +# +# Invenio-Cli is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. + +notifications: + email: false + +sudo: true + +language: python + +python: + - "3.6" + +services: + - docker + +before_script: + - gem install awesome_bot + +script: + - ./run-tests.sh diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..171460ad --- /dev/null +++ b/LICENSE @@ -0,0 +1,23 @@ +MIT License + +Copyright (C) 2019 CERN. +Copyright (C) 2019 Northwestern University. + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/README.md b/README.md new file mode 100644 index 00000000..53663110 --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +# docs.reana.io + +[![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) + +## About + +InvenioRDM user documentation web site. + +## Running + +```console +$ mkvirtualenv docs-invenio-rdm +$ pip install -r requirements.txt +$ mkdocs serve +$ firefox http://127.0.0.1:8000 +``` + diff --git a/docs/deployment/kubernetes.md b/docs/deployment/kubernetes.md new file mode 100644 index 00000000..ddf04c9b --- /dev/null +++ b/docs/deployment/kubernetes.md @@ -0,0 +1 @@ +# Kubernetes \ No newline at end of file diff --git a/docs/deployment/openshit.md b/docs/deployment/openshit.md new file mode 100644 index 00000000..3456c6d0 --- /dev/null +++ b/docs/deployment/openshit.md @@ -0,0 +1 @@ +# OpenShift diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..510ae2ae0ba21de6e6604df75e5d6d931064b1c6 GIT binary patch literal 1262 zcmb`GUx-Xm9LFzhY>GAwMMhf^VNqN1;AtPGEqOxO&DKi9gVz3;JF^n)Jy*L(BoFd{ zJjgzfQrbpryHeCfk$)qyHZ4!4#?HCd-gSL`J9E};G`zUeXMX2=@44UaJ%6rc&EglI zXYpTay{WRS#g=8QhB(AP^h#G4hFf3^HdPw)zjd-!!DsjiEB@u5QvOz3dH33TgGIKh z+mgz=-RT51q6zeGrChH;e7Ju#?dXl@Cq<(kO)7u8+#_o_ynwe5EA@9%TVbh;F_*3M zex41JCxSS21ny4fqmglg{vhNWCzwsntF-GS=#N1U++@rl*~^)c=zf1oZ&gY&yv4We4-cLOQ0X*yyigGb)gw! zJ3)*+t(SLicY+0?<5?w|(Cq}v%-FO$u~N>G^o#S>_3|wb@?Bh+Obk5x(a`ttNVZRB Yven}k;Zk$sc&52Azj^q8cRcid0j1SiwEzGB literal 0 HcmV?d00001 diff --git a/docs/images/favicon.svg b/docs/images/favicon.svg new file mode 100644 index 00000000..9c0fa624 --- /dev/null +++ b/docs/images/favicon.svg @@ -0,0 +1,37 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logo-rdm.png b/docs/images/logo-rdm.png new file mode 100644 index 0000000000000000000000000000000000000000..7926de17800e595d12268bd350abdae185916416 GIT binary patch literal 13765 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 literal 0 HcmV?d00001 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..291ca386 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +# Home diff --git a/docs/quickstart/build_setup.md b/docs/quickstart/build_setup.md new file mode 100644 index 00000000..fc802ffd --- /dev/null +++ b/docs/quickstart/build_setup.md @@ -0,0 +1,84 @@ +# Build and Setup + +## Deploy your instance + +The CLI supports two deployment modes: local development and containerized *semi*-production. This document will focus on deploying a containerized *semi*-production instance (we will use the `--containers` flag throughout). To deploy for local development, replace that flag by `--local`. + +Before going on, let's move into the project directory: + +``` console +$ cd december-release +``` + +**Known issues**: + +- If you do not move into the correct directory you will get an error like this: +``` +ERROR:root:No flavour specified. +``` + +The error message is not intuitive: it is not because no flavour was specified that there is an error! We will change it. It just means that the folder does not contain the `.invenio` config file because the current directory is wrong: *cd into it :-)*. + +### Build the docker images + +We use the `build` command with the `--containers` flag to build the images specified in the `december-release/docker-compose.full.yml`. +In addition, we need to add ``--pre`` in order to allow `pipenv` to install alpha releases, since many InvenioRDM packages are now in this phase. Be patient, the docker images might take some time to build. + +``` console +(your-virtualenv)$ invenio-cli build --pre --containers +Building RDM application... +Locking dependencies... +Bootstrapping server... +Building base docker image... +Building applications docker image... +Creating services... +``` + +As a result, six images (December-Release, Nginx, Redis, PostgreSQL, RabbitMQ and Elasticsearch) have been built. + +### Setup the DB, ES and others + +We just need to initialize the database, the indices and so on. For this, we can use the `setup` command. Note that this command is only needed once. Afterwards, you can stop (not destroy) your instance and start again, and your data will still be there. + +``` console +(your-virtualenv)$ invenio-cli setup --containers +Setting up environment for RDM application... +Setting up server... +Starting containers... +Creating database... +Creating indexes... +Creating files location... +Creating admin role... +Assigning superuser access to admin role... +Stopping containers... +``` + +In case you want to wipe out the data that was there (say to start fresh), you can use `--force` and nuke the content! + +``` console +(your-virtualenv)$ invenio-cli setup --containers --force +Setting up environment for RDM application... +Setting up server... +Starting containers... +Flushing redis cache... +Deleting database... +Deleting indexes... +Purging queues... +Creating database... +Creating indexes... +Creating files location... +Creating admin role... +Assigning superuser access to admin role... +Stopping containers... +``` + +### Populate DB + +Let's add some content so you can interact a bit with the instance. For this you will generate 10 random demo records, using the `demo` command: + +``` console +(your-virtualenv)$ invenio-cli demo --containers +Setting up server... +Starting containers... +Populating instance with demo records... +``` diff --git a/docs/quickstart/cleanup.md b/docs/quickstart/cleanup.md new file mode 100644 index 00000000..32396a2d --- /dev/null +++ b/docs/quickstart/cleanup.md @@ -0,0 +1,12 @@ +# Cleanup after you + +## Destroy the instance + +Finally, we want to destroy it. This will take us to a clean state. Note that it destroys images, containers and volumes (the ones defined in the `december-release/docker-compose.full.yml`. ). + +Stop the application: + +``` console +(your-virtualenv)$ invenio-cli destroy --containers +Destroying RDM application... +``` diff --git a/docs/quickstart/config.md b/docs/quickstart/config.md new file mode 100644 index 00000000..bccd7825 --- /dev/null +++ b/docs/quickstart/config.md @@ -0,0 +1,118 @@ +# Configuration + +You can configure your InvenioRDM instance to best suit your needs. The `invenio.cfg` file, overrides the `config.py` variables provided by [Invenio modules](https://invenio.readthedocs.io/en/latest/general/bundles.html) and their dependencies. We will use configuring permissions as an example of how to configure your application. + +For the purpose of this example, we will only allow super users to create records through the REST API. To do so, we define our own permission policy. + +Open the `invenio.cfg` file with your favorite editor. We will use `vim` to avoid `emacs` and other wars ;). + +``` console +$ vim invenio.cfg +``` + +Let's add the following to the file: + +```python +# imports at the top... +from invenio_rdm_records.permissions import RDMRecordPermissionPolicy +from invenio_records_permissions.generators import SuperUser + +# ... + +# At the bottom +# Our custom Permission Policy +class MyRecordPermissionPolicy(RDMRecordPermissionPolicy): + can_create = [SuperUser()] + +RECORDS_PERMISSIONS_RECORD_POLICY = MyRecordPermissionPolicy +``` + +When we set `RECORDS_PERMISSIONS_RECORD_POLICY = MyRecordPermissionPolicy`, we are overriding `RECORDS_PERMISSIONS_RECORD_POLICY` provided by [invenio-records-permissions](https://github.com/inveniosoftware/invenio-app-rdm). You will note that `invenio.cfg` is really just a Python module. How convenient! + +**Pro tip** : You can type `can_create = []` to achieve the same effect; any empty permission list only allows super users. + +That's it configuration-wise. If we try to create a record through the API, your instance will check if you are a super user before allowing you. The same approach to configuration holds for any other setting you would like to override. Now we must stop the current instance, rebuild the application image and re-start it to see our changes take effect. + +You can run the same `build` command. If you are in a hurry, you can skip locking dependencies and building the base image. + +``` console +(your-virtualenv)$ invenio-cli server --containers --stop +(your-virtualenv)$ invenio-cli build --pre --containers [--skip-base --skip-lock] +(your-virtualenv)$ invenio-cli server --containers --start +``` + +Did the changes work? We are going to try to create a new record: + +``` console + $ curl -k -XPOST -H "Content-Type: application/json" https://localhost/api/records/ -d ' +{ + "access": { + "metadata_restricted": "false", + "files_restricted": "false" + }, + "access_right": "open", + "contributors": [{"name": "Jon Doe"}], + "description": "A Holiday Record description", + "owners": [1], + "publication_date": "25/12/2019", + "resource_type": { + "type": "Dataset", + "subtype": "dataset" + }, + "title": "A Holiday Record" +}' +``` + +As you can see, the server could not know if we are authenticated/superuser and rejected us: + +``` console +{"message":"The server could not verify that you are authorized to access the URL requested. You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required.","status":401} +``` + +**Advanced example**: + +1- Create a user, for example using the web UI (*sign up* button). Alternatively, you can do so with the CLI, executing the following command (Wait until you read point number *2* before executing): + +``` console +invenio-cli users create user@test.ch --password=123456 +``` + +Note that the user will have ID 1 if it was the first one created. + +2- Grant admin access to it. In order to do so, we only have to add the `-a` flag to the previous command: + +``` console +invenio-cli users create admin@test.ch -a --password=123456 +``` + +Note that this user will have ID 2. + +3- Get a token and try to create the record again. You can do so on the UI by going to `settings->applications-->new token`. Alternatively you can do it in the terminal by executing the following command: + +``` console +# TODO Wait until invenio-oauthclient REST only is integrated +``` + +Afterwards we can test if the new permissions are working correctly. + +``` console +$ curl -k -XPOST -H "Authorization:Bearer sHHq1K9y7a2v5doKDRSFmSFOxa1tZDHFcbs31npaxm1sFEt27yomLMt0ynkl" -H "Content-Type: application/json" https://localhost/api/records/ -d ' +{ + "access": { + "metadata_restricted": "false", + "files_restricted": "false" + }, + "access_right": "open", + "contributors": [{"name": "Jon Doe"}], + "description": "A Holiday Record description", + "owners": [1], + "publication_date": "25/12/2019", + "resource_type": { + "type": "Dataset", + "subtype": "dataset" + }, + "title": "A Holiday Record" +}' +``` + +It works! diff --git a/docs/quickstart/customize.md b/docs/quickstart/customize.md new file mode 100644 index 00000000..37a704b1 --- /dev/null +++ b/docs/quickstart/customize.md @@ -0,0 +1,20 @@ +# Customization + +As we just saw, overriding configured values is an easy and common way of customizing your instance to your needs. Sometimes, however, you need to provide custom files too: logos, templates... We show how to perform these custom changes. + +We are going to change the logo, take an *svg* file and update your **local** static files (You can use the [invenio color logo](https://github.com/inveniosoftware/invenio-theme/blob/master/invenio_theme/static/images/invenio-color.svg)): + +``` console +$ cp ./path/to/new/color/logo.svg static/images/logo.svg +``` + +Then, use the update command: + +``` console +(your-virtualenv)$ invenio-cli update --containers +Updating static files... +``` + +Go to the browser [*https://localhost/*](https://localhost) or refresh the page. And voila! 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. diff --git a/docs/quickstart/index.md b/docs/quickstart/index.md new file mode 100644 index 00000000..291ca386 --- /dev/null +++ b/docs/quickstart/index.md @@ -0,0 +1 @@ +# Home diff --git a/docs/quickstart/init.md b/docs/quickstart/init.md new file mode 100644 index 00000000..f9df74e5 --- /dev/null +++ b/docs/quickstart/init.md @@ -0,0 +1,88 @@ +# Initialization + +## Bootstrap your instance + +### Initialize your file system + +Running the `init` command and passing the requested configuration values will create the necessary files and folders in your working directory. + +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 one word (project name for machine) +- Project website: URL where the project will be deployed +- Github repository: Repository in format `/` +- Description: Short description of project +- Author name: Your name or that of your organization +- Author email: Email for communication +- Year: The current year +- One of the three available storage systems: postgresql (default), mysql or sqlite +- The version of Elasticsearch: 7 (default) or 6 + +It will generate a test private key. + +Enable your virtualenv or use `pipenv run` then run the `init` command. You will want to run all the commands from here on out in this virtualenv: + +``` console +$ pipenv shell +(your-virtualenv)$ invenio-cli init --flavour=RDM +Initializing RDM application... +You've downloaded /home/youruser/.cookiecutters/cookiecutter-invenio-rdm before. Is it okay to delete and re-download it? [yes]: +project_name [My Site]: December Release +project_shortname [december-release]: +project_site [december-release.com]: +github_repo [december-release/december-release]: +description [Invenio RDM December Release Instance]: +author_name [CERN]: +author_email [info@december-release.com]: +year [2019]: +Select database: +1 - postgresql +2 - mysql +3 - sqlite +Choose from 1, 2, 3 (1, 2, 3) [1]: +Select elasticsearch: +1 - 7 +2 - 6 +Choose from 1, 2 (1, 2) [1]: +------------------------------------------------------------------------------- + +Generating SSL certificate and private key for testing.... +Can't load /home/youruser/.rnd into RNG +139989104693696:error:2406F079:random number generator:RAND_load_file:Cannot open file:../crypto/rand/randfile.c:88:Filename=/home/youruser/.rnd +Generating a RSA private key +..................++++ +..................................++++ +writing new private key to 'docker/nginx/test.key' +----- +------------------------------------------------------------------------------- +Creating logs directory... +``` + +Finally, observe the generated files. A full description of each of them can be found in the [invenio-cli RFC](https://github.com/inveniosoftware/rfcs/pull/4) + +``` console +$ ls -la december-release +total 56 +drwxr-xr-x 5 youruser youruser 4096 Dec 19 13:45 ./ +drwxr-xr-x 5 youruser youruser 4096 Dec 19 13:45 ../ +drwxr-xr-x 4 youruser youruser 4096 Dec 19 13:45 docker/ +-rw-r--r-- 1 youruser youruser 2932 Dec 19 13:45 docker-compose.full.yml +-rw-r--r-- 1 youruser youruser 943 Dec 19 13:45 docker-compose.yml +-rw-r--r-- 1 youruser youruser 1152 Dec 19 13:45 Dockerfile +-rw-r--r-- 1 youruser youruser 703 Dec 19 13:45 Dockerfile.base +-rw-r--r-- 1 youruser youruser 2665 Dec 19 13:45 docker-services.yml +-rw-r--r-- 1 youruser youruser 2018 Dec 19 13:45 .invenio +-rw-r--r-- 1 youruser youruser 1504 Dec 19 13:45 invenio.cfg +drwxr-xr-x 2 youruser youruser 4096 Dec 19 13:45 logs/ +-rw-r--r-- 1 youruser youruser 431 Dec 19 13:45 Pipfile +-rw-r--r-- 1 youruser youruser 756 Dec 19 13:45 README.rst +drwxr-xr-x 3 youruser youruser 4096 Dec 19 13:45 static/ +``` + +**Notes and Known Issues** + +For now, the only available flavour is RDM (Research Data Management). In the future, there will be others, for example ILS (Integrated Library System). + +You may be prompted with `You've downloaded /home//.cookiecutters/cookiecutter-invenio-rdm before. Is it okay to delete and re-download it? [yes]: `. Type `yes` and press enter in that case. This will download the latest cookiecutter template. + +Some OpenSSL versions display an error message when obtaining random numbers, but this has no incidence (as far as we can tell) on functionality. We are investigating a possible solution to raise less eyebrows for appearance sake. diff --git a/docs/quickstart/quickstart.md b/docs/quickstart/quickstart.md new file mode 100644 index 00000000..fec562c7 --- /dev/null +++ b/docs/quickstart/quickstart.md @@ -0,0 +1,34 @@ +# Quickstart + +## Pre-Requirements + +In order to successfully use the CLI, two components are needed: + +- Docker-Compose +- Docker + +You can find details on how to install them HERE and HERE, respectively. In addition, make sure the user that will be executing the CLI has access to the docker command (i.e. it is not only available for the root user). For that you can see the following DOCKER documentation. + +## Install the CLI + +You can install and manage your InvenioRDM instance using the Invenio CLI, aptly named `invenio-cli`. The package is available on [PyPI](https://pypi.org/project/invenio-cli/) and you should install it using `pipenv` (Follow the [instructions here](https://pipenv.readthedocs.io/en/latest/install/#installing-pipenv) to install `pipenv` for your platform): + +``` console +$ pipenv install --pre invenio-cli +``` + +*Note: The CLI is still in alpha release. This release's version is **v1.0.0a8**. Use `pipenv run pip list | grep invenio-cli` to make sure you have the right version.* + +**Known Issue**: If you are installing `invenio-cli` globally (e.g., pipx), some of the commands below in `--local` mode will not be found because they are not in the same virtualenv. We are investigating how to best remedy this. However, for the purposes of this installation guide, we use the `--containers` mode which doesn't face this issue. + +## Quick containerized installation + +``` console +$ invenio-cli init --flavour=RDM +$ cd my-site +$ invenio-cli build --pre --containers +$ invenio-cli setup --containers +$ invenio-cli demo --containers +$ invenio-cli server --containers +$ curl -k -XGET https://localhost/api/records/ | python3 -m json.tool +``` \ No newline at end of file diff --git a/docs/quickstart/server.md b/docs/quickstart/server.md new file mode 100644 index 00000000..63814673 --- /dev/null +++ b/docs/quickstart/server.md @@ -0,0 +1,206 @@ +# Run it! + +## Run the instance + +Let's get it rolling! + +Once the images have been built, they just need to run. For that, the `server` command is executed. **WARNING: It is the SERVER command, NOT the RUN command**. + +``` console +(your-virtualenv)$ invenio-cli server --containers +Booting up server... +Starting docker containers. It might take up to a minute. +Containers started use --stop to stop server. +``` + +**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: + +On Linux, add the following to ``/etc/sysctl.conf`` on your local machine (host machine): + +```console +# Memory mapped max size set for ElasticSearch +vm.max_map_count=262144 +``` + +On macOS, do the following: + +```console +screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty +# and in the shell +sysctl -w vm.max_map_count=262144 +``` + +## Use your instance: have fun! + +Are we done? Yes, let the fun begin... + +### List records + +Let's see what is in the instance by querying the API. Using another terminal: + +``` console +$ curl -k -XGET https://localhost/api/records/ | python3 -m json.tool +{ + "aggregations": { + "access_right": { + "buckets": [ + { + "doc_count": 10, + "key": "open" + } + ], + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0 + }, + "resource_type": { + "buckets": [ + { + "doc_count": 10, + "key": "Dataset" + } + ], + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0 + } + }, + "hits": { + "hits": [ + { + "created": "2019-12-19T20:15:29.167218+00:00", + "id": "s2pwq-mzw48", + "links": { + "files": "https://localhost/api/records/s2pwq-mzw48/files", + "self": "https://localhost/api/records/s2pwq-mzw48" + }, + "metadata": { + "_access": { + "files_restricted": false, + "metadata_restricted": false + }, + "access_right": "open", + "contributors": [ + { + "name": "Jeanne Jones" + } + ], + "description": "repurpose robust eyeballs", + "owners": [ + 1 + ], + "publication_date": "2009-12-30", + "recid": "s2pwq-mzw48", + "resource_type": { + "subtype": "dataset", + "type": "Dataset" + }, + "title": "Rodriguez Group's dataset" + }, + "revision": 0, + "updated": "2019-12-19T20:15:29.167224+00:00" + }, + ... +} +``` + +**Note**: Output shortened for readability. Your records will be different because they are generated randomly. + +**Pro Tip**: You can use [jq](https://github.com/stedolan/jq) for color highlighting: + +```console +$ curl -k -XGET https://localhost/api/records/ | jq . +... +``` + +### Create records + +You can create a new record using the API: + +```console +$ curl -k -XPOST -H "Content-Type: application/json" https://localhost/api/records/ -d ' +{ + "access": { + "metadata_restricted": "false", + "files_restricted": "false" + }, + "access_right": "open", + "contributors": [{"name": "Jon Doe"}, {"name": "Ian Matyssik"}], + "description": "Photo-analysis of doge in crystalline structures", + "owners": [1], + "publication_date": "05/11/2019", + "resource_type": { + "type": "image", + "subtype": "photo" + }, + "title": "Manually indexed record" +}' +``` + +And then search for it: + +``` console +$ curl -k -XGET https://localhost/api/records/?q=doge | python3 -m json.tool +{ + "aggregations": { + [...] + }, + "hits": { + "hits": [ + { + "created": "2019-12-19T13:05:48.479895+00:00", + "id": "pv1dx-rwa61", + "links": { + "self": "https://localhost/api/records/pv1dx-rwa61" + }, + "metadata": { + [...] + "title": "Manually indexed record" + }, + "revision": 0, + "updated": "2019-12-19T13:05:48.479900+00:00" + } + ], + "total": 1 + }, + "links": { + "self": "https://localhost/api/records/?sort=bestmatch&q=doge&size=10&page=1" + } +} +``` + +### ** NEW ** Use your browser + +Alternatively, you can use the web UI. + +Navigate to https://localhost/search . 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! + +### ** NEW ** Upload a file to a record + +For demonstration purposes, we will attach this scientific photo: + +![Very scientific picture of a shiba in the snow](https://images.unsplash.com/photo-1548116137-c9ac24e446c9?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1350&q=80) + +By Ian Matyssik + + +Save it as `snow_doge.jpg` in your current directory. Then upload it to the record: + +**WARNING** Change `pv1dx-rwa61` in the URLs below for the recid of your record. + +``` +$ curl -k -X PUT https://localhost/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. + +## Stop the instance + +We have reached the end of this journey, we are going to stop the instance. Nonetheless you can keep testing and playing around with configurations! + +``` console +(your-virtualenv)$ invenio-cli server --containers --stop +``` \ No newline at end of file diff --git a/docs/quickstart/troubleshoot.md b/docs/quickstart/troubleshoot.md new file mode 100644 index 00000000..a8e8059b --- /dev/null +++ b/docs/quickstart/troubleshoot.md @@ -0,0 +1,53 @@ +# Troubleshooting + +Something has gone wrong, now what? InvenioRDM provides logs in two ways, depending on where the error happened. If the error comes from the deployment of the instance (e.g. the containerized quickstart or a local development instance) your section is the [CLI](#cli) on the other hand, if once the application is running you get an error you should go to the [Web Application](#web-application) section. + +## CLI + +The Invenio-CLI saves the logs in the `logs` folder, inside the directory that was created with your instance name. For example, if you called it `My Site`, the logs file would be `my-site/logs/invenio-cli.log`. + +``` console +(your-virtualenv)$ invenio-cli init --flavour=RDM +Initializing RDM application... +You've downloaded /home/youruser/.cookiecutters/cookiecutter-invenio-rdm before. Is it okay to delete and re-download it? [yes]: +project_name [My Site]: My Site +project_shortname [my-site]: my-site <-- *THIS IS THE NAME OF THE FOLDER* +... +``` + +Another option is to run the CLI in verbose mode and get all the logs in the terminal at the same time thatn you execute the commands. To do so, just add the `--verbose` option to the commands. For example: `invenio-cli setup --versbose --containers`. + +## Web Application + +If you are running a development (`--local`) InvenioRDM instance you can use the `--verbose` flag in order to get the logs forwareded to the terminal. However, if you are running the containerized environment you need to get the logs from the corresponding containers. It can be done in two steps, first obtaining the container IDs and then getting their logs: + +``` console +$ docker ps -a + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +5cb64814ed2a my-site-frontend "nginx -g 'daemon of…" 24 minutes ago Up 1 minute mysite_frontend_1 +39993dcbb84f my-site "bash -c 'celery wor…" 24 minutes ago Up 1 minute mysite_worker_1 +ff9a589845e4 my-site "bash -c 'uwsgi /opt…" 24 minutes ago Up 1 minute 0.0.0.0:32810->5000/tcp mysite_web-api_1 +a99532c10a8b my-site "bash -c 'uwsgi /opt…" 24 minutes ago Up 1 minute 0.0.0.0:32811->5000/tcp mysite_web-ui_1 +d9afc36a573c redis "docker-entrypoint.s…" 24 minutes ago Up 3 minute 0.0.0.0:6379->6379/tcp mysite_cache_1 +cbdac8cbd6a9 rabbitmq:3-management "docker-entrypoint.s…" 24 minutes ago Up 3 minute 4369/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 15671/tcp, 25672/tcp, 0.0.0.0:15672->15672/tcp mysite_mq_1 +38d63e050e6b postgres:9.6 "docker-entrypoint.s…" 24 minutes ago Up 3 minute 0.0.0.0:5432->5432/tcp mysite_db_1 +30356839105a docker.elastic.co/elasticsearch/elasticsearch-oss:7.2.0 "/usr/local/bin/dock…" 24 minutes ago Up 3 minute (health: starting) 0.0.0.0:9200->9200/tcp, 0.0.0.0:9300->9300/tcp mysite_es_1 +``` + +The most insteresting ones will be the `web-ui` and `web-api` containers, which in this case have id `a99532c10a8b` and `ff9a589845e4` respectively. The logs can be obtaines by using the `logs` command of `docker`. An example of a working instance of the `web-api` container would show the following (Trimmed output for clarity): + +``` console +$ docker logs ff9a589845e4 + +[uWSGI] getting INI configuration from /opt/invenio/var/instance/uwsgi_rest.ini +*** Starting uWSGI 2.0.18 (64bit) on [Wed Jan 8 13:09:07 2020] *** +[...] +spawned uWSGI master process (pid: 1) +spawned uWSGI worker 1 (pid: 255, cores: 2) +spawned uWSGI worker 2 (pid: 257, cores: 2) +*** Stats server enabled on 0.0.0.0:9001 fd: 11 *** +``` + + + \ No newline at end of file diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..f9faccc5 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,117 @@ +body { + font-family: "Helvetica Neue", "Open Sans", Helvetica, Arial, sans-serif; +} + + +.md-typeset a, +.md-nav__link--active { + color: #000000; + opacity: 0.54; +} + +.md-typeset a:hover, +.md-nav__link:hover { + color: #000000; +} + +[data-md-color-primary="white"] .md-header { + background-image: linear-gradient(90deg, rgba(3, 119, 205, 1), rgba(3, 119, 205, 1) 52.52%, rgba(251, 130, 115, 1)); + color: #ffffff; +} +[data-md-color-primary="white"] .md-tabs { + background-image: linear-gradient(50deg, rgba(3, 119, 205, 1), rgba(3, 119, 205, 1) 52.52%, rgba(251, 130, 115, 1)); + color: #ffffff; +} + + + +.md-header[data-md-state="shadow"] { + box-shadow: none; + border-bottom: 0.05rem solid #ffffff; +} + +.md-source__facts { + display: none; +} + +.md-logo { + padding-top: 0.3rem; +} + +.md-logo img { + width: 131px; + height: 30px; +} + +.md-footer { + border-top: 0.05rem solid #ffffff; +} + +.md-footer-nav__link { + padding-top: 0.8rem; + padding-bottom: 0; +} + +.md-footer-nav { + background-color: #0377cd; +} + +.md-footer-nav__link { + color: #ffffff; + opacity: 0.75; +} + +.md-footer-nav__direction { + color: #ffffff; + opacity: 0.75; +} + +.md-footer-nav__link:hover, +.md-footer-nav__direction:hover { + opacity: 1; +} + +.md-footer-meta { + background-color: rgb(1, 98, 170); +} + +html .md-footer-meta .md-footer-meta__inner a { + color: #ffffff; +} + +.md-footer-meta__inner { + padding: 0 0.2rem; +} + +.md-footer-copyright { + padding: 0.7rem 0; +} + +.md-footer-social { + padding: 0.4rem 0; +} + +.md-search-result__link[data-md-state="active"] { + background-color: #ffffff; +} + +.md-typeset h1[id] .headerlink:focus, +.md-typeset h1[id]:hover .headerlink:hover, +.md-typeset h1[id]:target .headerlink, +.md-typeset h2[id] .headerlink:focus, +.md-typeset h2[id]:hover .headerlink:hover, +.md-typeset h2[id]:target .headerlink, +.md-typeset h3[id] .headerlink:focus, +.md-typeset h3[id]:hover .headerlink:hover, +.md-typeset h3[id]:target .headerlink, +.md-typeset h4[id] .headerlink:focus, +.md-typeset h4[id]:hover .headerlink:hover, +.md-typeset h4[id]:target .headerlink, +.md-typeset h5[id] .headerlink:focus, +.md-typeset h5[id]:hover .headerlink:hover, +.md-typeset h5[id]:target .headerlink, +.md-typeset h6[id] .headerlink:focus, +.md-typeset h6[id]:hover .headerlink:hover, +.md-typeset h6[id]:target .headerlink { + color: #0377cd; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..7e5a70f0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,63 @@ +# Project information +site_name: 'User Documentation' +site_description: 'InvenioRDM user documentation web site' +site_url: 'https://docs-invenio-rdm' + +# Repository +repo_name: 'docs-invenio-rdm' +repo_url: 'https://github.com/inveniosoftware/docs-invenio-rdm' + +# Copyright +copyright: 'Copyright © 2019 CERN and Northwestern University.' + +# Configuration +theme: + name: 'material' + custom_dir: 'theme' + palette: + primary: 'white' + font: + text: 'Open Sans' + code: 'Roboto Mono' + logo: 'images/logo-rdm.png' + favicon: 'images/favicon.ico' + feature: + tabs: true + +nav: + - Home: 'index.md' + - Quickstart: + - Quickstart: 'quickstart/quickstart.md' + - Initialization: 'quickstart/init.md' + - Build and Setup: 'quickstart/build_setup.md' + - Run: 'quickstart/server.md' + - Configuration: 'quickstart/config.md' + - Customization: 'quickstart/customize.md' + - Troubleshooting: 'quickstart/troubleshoot.md' + - Cleanup: 'quickstart/cleanup.md' + - Deployment: + - Kubernetes: 'deployment/kubernetes.md' + - OpenShift: 'deployment/openshift.md' + + +# Customization +extra: + social: + - type: 'github' + link: 'https://github.com/inveniosoftware' + - type: 'twitter' + link: 'https://twitter.com/invenio' + - type: 'comments' + link: 'https://invenio-talk.web.cern.ch/c/projects/invenio-rdm' + - type: 'globe' + link: 'https://inveniosoftware.org/products/rdm/' +extra_css: + - stylesheets/extra.css + +# Extensions +markdown_extensions: + - admonition + - codehilite: + guess_lang: false + - toc: + permalink: true diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..3d45e820 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,10 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2019 CERN. +# Copyright (C) 2019 Northwestern University. +# +# Invenio-Cli is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. + +mkdocs>=1.0.4 +mkdocs-material>=4.6.0 diff --git a/run-tests.sh b/run-tests.sh new file mode 100644 index 00000000..48f93ad5 --- /dev/null +++ b/run-tests.sh @@ -0,0 +1,13 @@ +#!/bin/sh +# -*- coding: utf-8 -*- +# +# Copyright (C) 2019 CERN. +# Copyright (C) 2019 Northwestern University. +# +# Invenio-Cli is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. + +npx markdownlint-cli docs/* && \ +awesome_bot --allow-dupe --skip-save-results --allow-redirect docs/**/*.md && \ +mkdocs build -v +rm -rf site/ diff --git a/theme/partials/footer.html b/theme/partials/footer.html new file mode 100644 index 00000000..8372ac6c --- /dev/null +++ b/theme/partials/footer.html @@ -0,0 +1,97 @@ + + +{% import "partials/language.html" as lang with context %} + + +