From 4a008e51e32a6996a26c8f8ecb301c3b42950851 Mon Sep 17 00:00:00 2001 From: lana-shanghai <31368580+lana-shanghai@users.noreply.github.com> Date: Mon, 18 May 2020 20:22:26 +0700 Subject: [PATCH] [WIP] Documentation re-org (#2694) * Reorganized docs * Fixed internal links in basic usage * fixed the docker-compose command and volume for docs * fixed docs tests * fix travis docs test * tox ini file * fixed readme localhost links * edited tox and test docs to previous state * Fix tests errors related to docs reorganization Signed-off-by: David Dashyan * Added ansible script installation option Signed-off-by: Lana Ivina * Added ansible script to network setup guide Signed-off-by: Lana Ivina * Hid the non-working button for now. Signed-off: Lana Ivina * Try now button Co-authored-by: David Dashyan --- .gitignore | 2 + .travis.yml | 3 - bigchaindb/common/transaction.py | 7 +- bigchaindb/core.py | 10 +- docker-compose.yml | 4 +- docs/README.md | 2 +- docs/contributing/Makefile | 225 ---------- docs/contributing/requirements.txt | 5 - docs/contributing/source/conf.py | 384 ------------------ .../ways-to-contribute/answer-questions.md | 18 - .../source/ways-to-contribute/index.rst | 18 - .../make-a-feature-request-or-proposal.md | 10 - .../source/ways-to-contribute/report-a-bug.md | 10 - .../ways-to-contribute/write-an-issue.md | 10 - .../generate_http_server_api_documentation.py | 2 +- docs/{server => root}/make.bat | 0 docs/root/requirements.txt | 3 + ...{private-data.rst => about-bigchaindb.rst} | 32 +- docs/root/source/assets.rst | 22 - ...transaction-concepts.md => basic-usage.md} | 26 +- docs/root/source/bft.md | 13 - docs/root/source/conf.py | 68 +++- .../cross-project-policies/code-of-conduct.md | 57 +++ .../cross-project-policies/index.rst | 0 .../python-style-guide.md | 97 +++++ .../cross-project-policies/release-process.md | 101 +++++ .../index.rst | 0 .../run-dev-network-ansible.md | 4 +- .../run-dev-network-stack.md | 6 +- .../run-node-as-processes.md | 0 .../run-node-with-docker-compose.md | 0 .../write-code.rst | 0 .../source/contributing}/index.rst | 1 - .../ways-to-contribute}/index.rst | 8 +- .../ways-to-contribute/report-a-bug.md} | 25 +- .../ways-to-contribute/write-docs.md | 0 docs/root/source/decentralized.md | 22 - docs/root/source/diversity.md | 17 - .../source/drivers}/index.rst | 6 +- docs/root/source/immutable.md | 27 -- docs/root/source/index.rst | 87 +--- .../_static/Conditions_Circuit_Diagram.png | Bin .../installation}/_static/Node-components.png | Bin .../source/installation}/_static/arch.jpg | Bin .../_static/cc_escrow_execute_abort.png | Bin .../installation}/_static/models_diagrams.odg | Bin .../_static/mongodb_cloud_manager_1.png | Bin .../_static/monitoring_system_diagram.png | Bin .../_static/stories_3_assets.png | Bin .../_static/tx_escrow_execute_abort.png | Bin ...x_multi_condition_multi_fulfillment_v1.png | Bin .../installation}/_static/tx_schematics.odg | Bin ...single_condition_single_fulfillment_v1.png | Bin .../api}/http-client-server-api.rst | 6 +- .../api/http-samples/api-index-response.http | 13 + .../api/http-samples/get-block-request.http | 3 + .../api/http-samples/get-block-response.http | 45 ++ .../http-samples/get-block-txid-request.http | 3 + .../http-samples/get-block-txid-response.http | 6 + .../http-samples/get-tx-by-asset-request.http | 3 + .../get-tx-by-asset-response.http | 79 ++++ .../api/http-samples/get-tx-id-request.http | 3 + .../api/http-samples/get-tx-id-response.http | 40 ++ .../api/http-samples/index-response.http | 20 + .../api/http-samples/post-tx-request.http | 41 ++ .../api/http-samples/post-tx-response.http | 40 ++ .../source/installation/api}/index.rst | 7 +- .../api}/websocket-event-stream-api.rst | 2 +- .../installation}/appendices/cryptography.rst | 0 .../appendices/firewall-notes.md | 2 +- .../appendices/generate-key-pair-for-ssh.md | 0 .../source/installation}/appendices/index.rst | 8 +- .../installation}/appendices/licenses.md | 0 .../installation}/appendices/log-rotation.md | 4 +- .../installation}/appendices/ntp-notes.md | 0 .../commands-and-backend}/backend.rst | 0 .../commands-and-backend}/commands.rst | 0 .../commands-and-backend}/index.rst | 7 +- .../the-bigchaindb-class.rst | 0 docs/root/source/installation/index.rst | 20 + .../network-setup/bigchaindb-node-ansible.md | 7 + .../installation/network-setup/index.rst | 19 + .../k8s-deployment-template/architecture.rst | 6 +- .../bigchaindb-network-on-kubernetes.rst | 2 +- .../ca-installation.rst | 0 .../client-tls-certificate.rst | 0 .../k8s-deployment-template/cloud-manager.rst | 6 +- .../k8s-deployment-template/easy-rsa.rst | 0 .../k8s-deployment-template/index.rst | 2 +- .../k8s-deployment-template/log-analytics.rst | 2 +- .../node-config-map-and-secrets.rst | 2 +- .../node-on-kubernetes.rst | 2 +- .../revoke-tls-certificate.rst | 0 .../server-tls-certificate.rst | 0 .../tectonic-azure.rst | 2 +- .../template-kubernetes-azure.rst | 4 +- .../k8s-deployment-template/troubleshoot.rst | 0 .../upgrade-on-kubernetes.rst | 2 +- .../k8s-deployment-template/workflow.rst | 2 +- .../network-setup}/network-setup.md | 3 +- .../installation/network-setup}/networks.md | 2 +- .../node-setup}/all-in-one-bigchaindb.md | 2 +- .../installation/node-setup}/aws-setup.md | 2 +- .../node-setup}/bigchaindb-cli.md | 0 .../node-setup/bigchaindb-node-ansible.md | 7 + .../installation/node-setup}/configuration.md | 4 +- .../node-setup}/deploy-a-machine.md | 10 +- .../source/installation/node-setup/index.rst | 25 ++ .../node-setup/production-node}/index.rst | 0 .../production-node}/node-assumptions.md | 9 +- .../production-node}/node-components.md | 2 +- .../production-node}/node-requirements.md | 0 .../node-security-and-privacy.md | 2 +- .../production-node}/reverse-proxy-notes.md | 0 .../installation/node-setup}/release-notes.md | 0 .../installation/node-setup}/set-up-nginx.md | 0 .../node-setup}/set-up-node-software.md | 0 .../node-setup/troubleshooting.md} | 37 +- .../source/installation}/quickstart.md | 37 +- docs/root/source/permissions.rst | 71 ---- docs/root/source/production-ready.md | 13 - docs/root/source/properties.md | 60 +++ docs/root/source/query.rst | 4 +- docs/root/source/smart-contracts.rst | 16 - docs/root/source/store-files.md | 14 - docs/root/source/terminology.md | 63 ++- docs/server/Makefile | 216 ---------- docs/server/requirements.txt | 8 - .../source/appendices/json-serialization.rst | 14 - docs/server/source/conf.py | 332 --------------- .../server/source/data-models/asset-model.rst | 14 - .../server/source/data-models/block-model.rst | 39 -- docs/server/source/data-models/conditions.rst | 14 - docs/server/source/data-models/index.rst | 17 - .../source/data-models/inputs-outputs.rst | 14 - .../source/data-models/transaction-model.rst | 12 - docs/server/source/dev-and-test/index.rst | 12 - docs/server/source/index.rst | 28 -- docs/server/source/introduction.md | 30 -- .../simple-deployment-template/index.rst | 38 -- .../troubleshooting.md | 32 -- tests/backend/localmongodb/test_queries.py | 4 +- tests/test_docs.py | 7 - tox.ini | 10 +- 144 files changed, 1031 insertions(+), 1935 deletions(-) delete mode 100644 docs/contributing/Makefile delete mode 100644 docs/contributing/requirements.txt delete mode 100644 docs/contributing/source/conf.py delete mode 100644 docs/contributing/source/ways-to-contribute/answer-questions.md delete mode 100644 docs/contributing/source/ways-to-contribute/index.rst delete mode 100644 docs/contributing/source/ways-to-contribute/make-a-feature-request-or-proposal.md delete mode 100644 docs/contributing/source/ways-to-contribute/report-a-bug.md delete mode 100644 docs/contributing/source/ways-to-contribute/write-an-issue.md rename docs/{server => root}/generate_http_server_api_documentation.py (98%) rename docs/{server => root}/make.bat (100%) rename docs/root/source/{private-data.rst => about-bigchaindb.rst} (78%) delete mode 100644 docs/root/source/assets.rst rename docs/root/source/{transaction-concepts.md => basic-usage.md} (90%) delete mode 100644 docs/root/source/bft.md create mode 100644 docs/root/source/contributing/cross-project-policies/code-of-conduct.md rename docs/{contributing/source => root/source/contributing}/cross-project-policies/index.rst (100%) create mode 100644 docs/root/source/contributing/cross-project-policies/python-style-guide.md create mode 100644 docs/root/source/contributing/cross-project-policies/release-process.md rename docs/{contributing/source => root/source/contributing}/dev-setup-coding-and-contribution-process/index.rst (100%) rename docs/{contributing/source => root/source/contributing}/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md (98%) rename docs/{contributing/source => root/source/contributing}/dev-setup-coding-and-contribution-process/run-dev-network-stack.md (99%) rename docs/{contributing/source => root/source/contributing}/dev-setup-coding-and-contribution-process/run-node-as-processes.md (100%) rename docs/{contributing/source => root/source/contributing}/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md (100%) rename docs/{contributing/source => root/source/contributing}/dev-setup-coding-and-contribution-process/write-code.rst (100%) rename docs/{contributing/source => root/source/contributing}/index.rst (92%) rename docs/{server/source/server-reference => root/source/contributing/ways-to-contribute}/index.rst (78%) rename docs/{contributing/source/ways-to-contribute/write-a-bep.md => root/source/contributing/ways-to-contribute/report-a-bug.md} (64%) rename docs/{contributing/source => root/source/contributing}/ways-to-contribute/write-docs.md (100%) delete mode 100644 docs/root/source/decentralized.md delete mode 100644 docs/root/source/diversity.md rename docs/{server/source/drivers-clients => root/source/drivers}/index.rst (85%) delete mode 100644 docs/root/source/immutable.md rename docs/{server/source => root/source/installation}/_static/Conditions_Circuit_Diagram.png (100%) rename docs/{server/source => root/source/installation}/_static/Node-components.png (100%) rename docs/{server/source => root/source/installation}/_static/arch.jpg (100%) rename docs/{server/source => root/source/installation}/_static/cc_escrow_execute_abort.png (100%) rename docs/{server/source => root/source/installation}/_static/models_diagrams.odg (100%) rename docs/{server/source => root/source/installation}/_static/mongodb_cloud_manager_1.png (100%) rename docs/{server/source => root/source/installation}/_static/monitoring_system_diagram.png (100%) rename docs/{server/source => root/source/installation}/_static/stories_3_assets.png (100%) rename docs/{server/source => root/source/installation}/_static/tx_escrow_execute_abort.png (100%) rename docs/{server/source => root/source/installation}/_static/tx_multi_condition_multi_fulfillment_v1.png (100%) rename docs/{server/source => root/source/installation}/_static/tx_schematics.odg (100%) rename docs/{server/source => root/source/installation}/_static/tx_single_condition_single_fulfillment_v1.png (100%) rename docs/{server/source => root/source/installation/api}/http-client-server-api.rst (99%) create mode 100644 docs/root/source/installation/api/http-samples/api-index-response.http create mode 100644 docs/root/source/installation/api/http-samples/get-block-request.http create mode 100644 docs/root/source/installation/api/http-samples/get-block-response.http create mode 100644 docs/root/source/installation/api/http-samples/get-block-txid-request.http create mode 100644 docs/root/source/installation/api/http-samples/get-block-txid-response.http create mode 100644 docs/root/source/installation/api/http-samples/get-tx-by-asset-request.http create mode 100644 docs/root/source/installation/api/http-samples/get-tx-by-asset-response.http create mode 100644 docs/root/source/installation/api/http-samples/get-tx-id-request.http create mode 100644 docs/root/source/installation/api/http-samples/get-tx-id-response.http create mode 100644 docs/root/source/installation/api/http-samples/index-response.http create mode 100644 docs/root/source/installation/api/http-samples/post-tx-request.http create mode 100644 docs/root/source/installation/api/http-samples/post-tx-response.http rename docs/{server/source/events => root/source/installation/api}/index.rst (87%) rename docs/{server/source/events => root/source/installation/api}/websocket-event-stream-api.rst (97%) rename docs/{server/source => root/source/installation}/appendices/cryptography.rst (100%) rename docs/{server/source => root/source/installation}/appendices/firewall-notes.md (96%) rename docs/{server/source => root/source/installation}/appendices/generate-key-pair-for-ssh.md (100%) rename docs/{server/source => root/source/installation}/appendices/index.rst (85%) rename docs/{server/source => root/source/installation}/appendices/licenses.md (100%) rename docs/{server/source => root/source/installation}/appendices/log-rotation.md (91%) rename docs/{server/source => root/source/installation}/appendices/ntp-notes.md (100%) rename docs/{server/source/code-reference => root/source/installation/commands-and-backend}/backend.rst (100%) rename docs/{server/source/code-reference => root/source/installation/commands-and-backend}/commands.rst (100%) rename docs/{server/source/code-reference => root/source/installation/commands-and-backend}/index.rst (92%) rename docs/{server/source/code-reference => root/source/installation/commands-and-backend}/the-bigchaindb-class.rst (100%) create mode 100644 docs/root/source/installation/index.rst create mode 100644 docs/root/source/installation/network-setup/bigchaindb-node-ansible.md create mode 100644 docs/root/source/installation/network-setup/index.rst rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/architecture.rst (99%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst (99%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/ca-installation.rst (100%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/client-tls-certificate.rst (100%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/cloud-manager.rst (93%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/easy-rsa.rst (100%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/index.rst (96%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/log-analytics.rst (99%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/node-config-map-and-secrets.rst (98%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/node-on-kubernetes.rst (99%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/revoke-tls-certificate.rst (100%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/server-tls-certificate.rst (100%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/tectonic-azure.rst (98%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/template-kubernetes-azure.rst (98%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/troubleshoot.rst (100%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/upgrade-on-kubernetes.rst (98%) rename docs/{server/source => root/source/installation/network-setup}/k8s-deployment-template/workflow.rst (99%) rename docs/{server/source/simple-deployment-template => root/source/installation/network-setup}/network-setup.md (96%) rename docs/{server/source => root/source/installation/network-setup}/networks.md (94%) rename docs/{server/source/appendices => root/source/installation/node-setup}/all-in-one-bigchaindb.md (97%) rename docs/{server/source/appendices => root/source/installation/node-setup}/aws-setup.md (96%) rename docs/{server/source/server-reference => root/source/installation/node-setup}/bigchaindb-cli.md (100%) create mode 100644 docs/root/source/installation/node-setup/bigchaindb-node-ansible.md rename docs/{server/source/server-reference => root/source/installation/node-setup}/configuration.md (98%) rename docs/{server/source/simple-deployment-template => root/source/installation/node-setup}/deploy-a-machine.md (88%) create mode 100644 docs/root/source/installation/node-setup/index.rst rename docs/{server/source/production-nodes => root/source/installation/node-setup/production-node}/index.rst (100%) rename docs/{server/source/production-nodes => root/source/installation/node-setup/production-node}/node-assumptions.md (54%) rename docs/{server/source/production-nodes => root/source/installation/node-setup/production-node}/node-components.md (92%) rename docs/{server/source/production-nodes => root/source/installation/node-setup/production-node}/node-requirements.md (100%) rename docs/{server/source/production-nodes => root/source/installation/node-setup/production-node}/node-security-and-privacy.md (94%) rename docs/{server/source/production-nodes => root/source/installation/node-setup/production-node}/reverse-proxy-notes.md (100%) rename docs/{server/source => root/source/installation/node-setup}/release-notes.md (100%) rename docs/{server/source/simple-deployment-template => root/source/installation/node-setup}/set-up-nginx.md (100%) rename docs/{server/source/simple-deployment-template => root/source/installation/node-setup}/set-up-node-software.md (100%) rename docs/{server/source/simple-deployment-template/tips.md => root/source/installation/node-setup/troubleshooting.md} (71%) rename docs/{server/source => root/source/installation}/quickstart.md (63%) delete mode 100644 docs/root/source/permissions.rst delete mode 100644 docs/root/source/production-ready.md create mode 100644 docs/root/source/properties.md delete mode 100644 docs/root/source/smart-contracts.rst delete mode 100644 docs/root/source/store-files.md delete mode 100644 docs/server/Makefile delete mode 100644 docs/server/requirements.txt delete mode 100644 docs/server/source/appendices/json-serialization.rst delete mode 100644 docs/server/source/conf.py delete mode 100644 docs/server/source/data-models/asset-model.rst delete mode 100644 docs/server/source/data-models/block-model.rst delete mode 100644 docs/server/source/data-models/conditions.rst delete mode 100644 docs/server/source/data-models/index.rst delete mode 100644 docs/server/source/data-models/inputs-outputs.rst delete mode 100644 docs/server/source/data-models/transaction-model.rst delete mode 100644 docs/server/source/dev-and-test/index.rst delete mode 100644 docs/server/source/index.rst delete mode 100644 docs/server/source/introduction.md delete mode 100644 docs/server/source/simple-deployment-template/index.rst delete mode 100644 docs/server/source/simple-deployment-template/troubleshooting.md diff --git a/.gitignore b/.gitignore index 867c197a..1e0fb310 100644 --- a/.gitignore +++ b/.gitignore @@ -95,3 +95,5 @@ network/*/data # Docs that are fetched at build time docs/contributing/source/cross-project-policies/*.md + +.DS_Store diff --git a/.travis.yml b/.travis.yml index e4acca44..628b333a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -23,7 +23,6 @@ env: matrix: - TOXENV=flake8 - TOXENV=docsroot - - TOXENV=docsserver matrix: fast_finish: true @@ -32,8 +31,6 @@ matrix: env: TOXENV=flake8 - python: 3.5 env: TOXENV=docsroot - - python: 3.5 - env: TOXENV=docsserver include: - python: 3.6 env: diff --git a/bigchaindb/common/transaction.py b/bigchaindb/common/transaction.py index a3f17dcd..69960ff7 100644 --- a/bigchaindb/common/transaction.py +++ b/bigchaindb/common/transaction.py @@ -546,7 +546,7 @@ class Transaction(object): elif (operation == self.TRANSFER and not (isinstance(asset, dict) and 'id' in asset)): raise TypeError(('`asset` must be a dict holding an `id` property ' - "for 'TRANSFER' Transactions".format(operation))) + 'for \'TRANSFER\' Transactions')) if outputs and not isinstance(outputs, list): raise TypeError('`outputs` must be a list instance or None') @@ -869,8 +869,9 @@ class Transaction(object): return cls._sign_threshold_signature_fulfillment(input_, message, key_pairs) else: - raise ValueError("Fulfillment couldn't be matched to " - 'Cryptocondition fulfillment type.') + raise ValueError( + 'Fulfillment couldn\'t be matched to ' + 'Cryptocondition fulfillment type.') @classmethod def _sign_simple_signature_fulfillment(cls, input_, message, key_pairs): diff --git a/bigchaindb/core.py b/bigchaindb/core.py index 87cc5819..4898ee94 100644 --- a/bigchaindb/core.py +++ b/bigchaindb/core.py @@ -46,9 +46,9 @@ class App(BaseApplication): self.chain = self.bigchaindb.get_latest_abci_chain() def log_abci_migration_error(self, chain_id, validators): - logger.error(f'An ABCI chain migration is in process. ' + - 'Download the new ABCI client and configure it with ' + - 'chain_id={chain_id} and validators={validators}.') + logger.error('An ABCI chain migration is in process. ' + 'Download the new ABCI client and configure it with ' + f'chain_id={chain_id} and validators={validators}.') def abort_if_abci_chain_is_not_synced(self): if self.chain is None or self.chain['is_synced']: @@ -69,8 +69,8 @@ class App(BaseApplication): chain_id = known_chain['chain_id'] if known_chain['is_synced']: - msg = f'Got invalid InitChain ABCI request ({genesis}) - ' + \ - 'the chain {chain_id} is already synced.' + msg = (f'Got invalid InitChain ABCI request ({genesis}) - ' + f'the chain {chain_id} is already synced.') logger.error(msg) sys.exit(1) diff --git a/docker-compose.yml b/docker-compose.yml index 230144d4..063c8e0e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -96,10 +96,10 @@ services: backend: localmongodb volumes: - .:/usr/src/app/ - command: make -C docs/server html + command: make -C docs/root html vdocs: image: nginx ports: - '33333:80' volumes: - - ./docs/server/build/html:/usr/share/nginx/html + - ./docs/root/build/html:/usr/share/nginx/html diff --git a/docs/README.md b/docs/README.md index 0899986b..3bcc51e8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -45,7 +45,7 @@ You can also use [Docker Compose](https://docs.docker.com/compose/) to build and $ docker-compose up -d bdocs ``` -The docs will be hosted on port **33333**, and can be accessed over [localhost](http:/localhost:33333), [127.0.0.1](http:/127.0.0.1:33333) +The docs will be hosted on port **33333**, and can be accessed over [localhost](http://localhost:33333), [127.0.0.1](http://127.0.0.1:33333) OR http:/HOST_IP:33333. diff --git a/docs/contributing/Makefile b/docs/contributing/Makefile deleted file mode 100644 index 578ec7d6..00000000 --- a/docs/contributing/Makefile +++ /dev/null @@ -1,225 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -W -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " epub3 to make an epub3" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - @echo " dummy to check syntax errors of document sources" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/BigchainDB.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/BigchainDB.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/BigchainDB" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/BigchainDB" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: epub3 -epub3: - $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 - @echo - @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." - -.PHONY: latex -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -.PHONY: dummy -dummy: - $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy - @echo - @echo "Build finished. Dummy builder generates no files." diff --git a/docs/contributing/requirements.txt b/docs/contributing/requirements.txt deleted file mode 100644 index de6c0c1d..00000000 --- a/docs/contributing/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -Sphinx~=1.0 -recommonmark>=0.4.0 -sphinx-rtd-theme>=0.1.9 -wget -packaging~=18.0 diff --git a/docs/contributing/source/conf.py b/docs/contributing/source/conf.py deleted file mode 100644 index bcd7bf86..00000000 --- a/docs/contributing/source/conf.py +++ /dev/null @@ -1,384 +0,0 @@ -#!/usr/bin/env python3 -# Copyright © 2020 Interplanetary Database Association e.V., -# BigchainDB and IPDB software contributors. -# SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) -# Code is Apache-2.0 and docs are CC-BY-4.0 - -# BigchainDB documentation build configuration file, created by -# sphinx-quickstart on Thu Sep 29 11:13:27 2016. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import wget # is for real! -import datetime - -from os import rename, remove -from recommonmark.parser import CommonMarkParser - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -import sphinx_rtd_theme - -extensions = [ -# 'sphinx.ext.autosectionlabel', -] - -# Get remote files to here. -# Because this is just Pyton and we can do whatever Python can do: - -try: - remove('cross-project-policies/code-of-conduct.md') - remove('cross-project-policies/release-process.md') - remove('cross-project-policies/python-style-guide.md') -except: - print('done') - -def get_old_new(url, old, new): - filename = wget.download(url) - rename(old, new) - -get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/CODE_OF_CONDUCT.md', - 'CODE_OF_CONDUCT.md', 'cross-project-policies/code-of-conduct.md') - -get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/RELEASE_PROCESS.md', - 'RELEASE_PROCESS.md', 'cross-project-policies/release-process.md') - -get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/PYTHON_STYLE_GUIDE.md', - 'PYTHON_STYLE_GUIDE.md', 'cross-project-policies/python-style-guide.md') - -suppress_warnings = ['misc.highlighting_failure'] - - - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -source_parsers = { - '.md': CommonMarkParser, -} - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ['.rst', '.md'] - -# The encoding of source files. -# -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'Contributing to BigchainDB' -now = datetime.datetime.now() -copyright = str(now.year) + ', BigchainDB Contributors' -author = 'BigchainDB Contributors' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '' -# The full version, including alpha/beta/rc tags. -release = '' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# -# today = '' -# -# Else, today_fmt is used as the format for a strftime call. -# -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# The name for this set of Sphinx documents. -# " v documentation" by default. -# -# html_title = 'BigchainDB v0.1' - -# A shorter title for the navigation bar. Default is the same as html_title. -# -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# -# html_logo = None - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -# html_last_updated_fmt = None - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# -# html_additional_pages = {} - -# If false, no module index is generated. -# -# html_domain_indices = True - -# If false, no index is generated. -# -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'BigchainDBdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'BigchainDB.tex', 'Contributing to BigchainDB', - 'BigchainDB Contributors', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# -# latex_use_parts = False - -# If true, show page references after internal links. -# -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# -# latex_appendices = [] - -# It false, will not define \strong, \code, itleref, \crossref ... but only -# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added -# packages. -# -# latex_keep_old_macro_names = True - -# If false, no module index is generated. -# -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'bigchaindb', 'Contributing to BigchainDB', - [author], 1) -] - -# If true, show URL addresses after external links. -# -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'BigchainDB', 'Contributing to BigchainDB', - author, 'BigchainDB', 'How to contribute to BigchainDB.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -# -# texinfo_appendices = [] - -# If false, no module index is generated. -# -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False diff --git a/docs/contributing/source/ways-to-contribute/answer-questions.md b/docs/contributing/source/ways-to-contribute/answer-questions.md deleted file mode 100644 index 350ed1a1..00000000 --- a/docs/contributing/source/ways-to-contribute/answer-questions.md +++ /dev/null @@ -1,18 +0,0 @@ - - -# Answer Questions - -People ask questions about BigchainDB in the following places: - -- Gitter - - [bigchaindb/bigchaindb](https://gitter.im/bigchaindb/bigchaindb) - - [bigchaindb/js-bigchaindb-driver](https://gitter.im/bigchaindb/js-bigchaindb-driver) -- [Twitter](https://twitter.com/bigchaindb) -- [Stack Overflow "bigchaindb"](https://stackoverflow.com/search?q=bigchaindb) - -Feel free to hang out and answer some questions. People will be thankful. diff --git a/docs/contributing/source/ways-to-contribute/index.rst b/docs/contributing/source/ways-to-contribute/index.rst deleted file mode 100644 index 2818d1be..00000000 --- a/docs/contributing/source/ways-to-contribute/index.rst +++ /dev/null @@ -1,18 +0,0 @@ - -.. Copyright © 2020 Interplanetary Database Association e.V., - BigchainDB and IPDB software contributors. - SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) - Code is Apache-2.0 and docs are CC-BY-4.0 - -Ways to Contribute -================== - -.. toctree:: - :maxdepth: 1 - - report-a-bug - write-an-issue - make-a-feature-request-or-proposal - write-a-bep - write-docs - answer-questions diff --git a/docs/contributing/source/ways-to-contribute/make-a-feature-request-or-proposal.md b/docs/contributing/source/ways-to-contribute/make-a-feature-request-or-proposal.md deleted file mode 100644 index 379eae3c..00000000 --- a/docs/contributing/source/ways-to-contribute/make-a-feature-request-or-proposal.md +++ /dev/null @@ -1,10 +0,0 @@ - - -# Make a Feature Request or Proposal - -To make a feature request or proposal, [write a BigchainDB Enhancement Proposal (BEP)](write-a-bep). diff --git a/docs/contributing/source/ways-to-contribute/report-a-bug.md b/docs/contributing/source/ways-to-contribute/report-a-bug.md deleted file mode 100644 index 134850b6..00000000 --- a/docs/contributing/source/ways-to-contribute/report-a-bug.md +++ /dev/null @@ -1,10 +0,0 @@ - - -# Report a Bug - -To report a bug, go to the relevant GitHub repository, click on the **Issues** tab, click on the **New issue** button, and read the instructions. diff --git a/docs/contributing/source/ways-to-contribute/write-an-issue.md b/docs/contributing/source/ways-to-contribute/write-an-issue.md deleted file mode 100644 index 85938a4f..00000000 --- a/docs/contributing/source/ways-to-contribute/write-an-issue.md +++ /dev/null @@ -1,10 +0,0 @@ - - -# Write an Issue - -To write an issue, go to the relevant GitHub repository, click on the **Issues** tab, click on the **New issue** button, and read the instructions. diff --git a/docs/server/generate_http_server_api_documentation.py b/docs/root/generate_http_server_api_documentation.py similarity index 98% rename from docs/server/generate_http_server_api_documentation.py rename to docs/root/generate_http_server_api_documentation.py index 3cafa277..d58181ed 100644 --- a/docs/server/generate_http_server_api_documentation.py +++ b/docs/root/generate_http_server_api_documentation.py @@ -187,7 +187,7 @@ def main(): base_path = os.path.join(os.path.dirname(__file__), - 'source/http-samples') + 'source/installation/api/http-samples') if not os.path.exists(base_path): os.makedirs(base_path) diff --git a/docs/server/make.bat b/docs/root/make.bat similarity index 100% rename from docs/server/make.bat rename to docs/root/make.bat diff --git a/docs/root/requirements.txt b/docs/root/requirements.txt index 4ee8907d..81df20df 100644 --- a/docs/root/requirements.txt +++ b/docs/root/requirements.txt @@ -3,4 +3,7 @@ recommonmark>=0.4.0 sphinx-rtd-theme>=0.1.9 sphinxcontrib-napoleon>=0.4.4 sphinxcontrib-httpdomain>=1.5.0 +pyyaml>=4.2b1 +aafigure>=0.6 packaging~=18.0 +wget diff --git a/docs/root/source/private-data.rst b/docs/root/source/about-bigchaindb.rst similarity index 78% rename from docs/root/source/private-data.rst rename to docs/root/source/about-bigchaindb.rst index bd28de9b..977d0fe4 100644 --- a/docs/root/source/private-data.rst +++ b/docs/root/source/about-bigchaindb.rst @@ -4,8 +4,8 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 -BigchainDB, Privacy and Private Data ------------------------------------- +About BigchainDB +---------------- Basic Facts =========== @@ -20,6 +20,30 @@ Basic Facts #. If the connection between an external user and a BigchainDB node isn’t encrypted (using HTTPS, for example), then a wiretapper can read all HTTP requests and responses in transit. #. If someone gets access to plaintext (regardless of where they got it), then they can (in principle) share it with the whole world. One can make it difficult for them to do that, e.g. if it is a lot of data and they only get access inside a secure room where they are searched as they leave the room. +BigchainDB for Asset Registrations & Transfers +============================================== + +BigchainDB can store data of any kind, but it's designed to be particularly good for storing asset registrations and transfers: + +* The fundamental thing that one sends to a BigchainDB network, to be checked and stored (if valid), is a *transaction*, and there are two kinds: CREATE transactions and TRANSFER transactions. +* A CREATE transaction can be use to register any kind of asset (divisible or indivisible), along with arbitrary metadata. +* An asset can have zero, one, or several owners. +* The owners of an asset can specify (crypto-)conditions which must be satisfied by anyone wishing transfer the asset to new owners. For example, a condition might be that at least 3 of the 5 current owners must cryptographically sign a TRANSFER transaction. +* BigchainDB verifies that the conditions have been satisfied as part of checking the validity of TRANSFER transactions. (Moreover, anyone can check that they were satisfied.) +* BigchainDB prevents double-spending of an asset. +* Validated transactions are immutable. + +.. note:: + + We used the word "owners" somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or transfer-enablers. See the section titled **A Note about Owners** in the relevant `BigchainDB Transactions Spec `_. + +# Production-Ready? + +Depending on your use case, BigchainDB may or may not be production-ready. You should ask your service provider. +If you want to go live (into production) with BigchainDB, please consult with your service provider. + +Note: BigchainDB has an open source license with a "no warranty" section that is typical of open source licenses. This is standard in the software industry. For example, the Linux kernel is used in production by billions of machines even though its license includes a "no warranty" section. Warranties are usually provided above the level of the software license, by service providers. + Storing Private Data Off-Chain ============================== @@ -28,7 +52,7 @@ A system could store data off-chain, e.g. in a third-party database, document st - Keep track of who has read permissions (or other permissions) in a third-party system. An example of how this could be done is described below. - Keep a permanent record of all requests made to the third-party system. - Store hashes of documents-stored-elsewhere, so that a change in any document can be detected. -- Record all handshake-establishing requests and responses between two off-chain parties (e.g. a Diffie-Hellman key exchange), so as to prove that they established an encrypted tunnel (without giving readers access to that tunnel). There are more details about this idea in `the BigchainDB Privacy Protocols repository `_. +- Record all handshake-establishing requests and responses between two off-chain parties (e.g. a Diffie-Hellman key exchange), so as to prove that they established an encrypted tunnel (without giving readers access to that tunnel). There are more details about this idea in `the Privacy Protocols repository `_. A simple way to record who has read permission on a particular document would be for the third-party system (“DocPile”) to store a CREATE transaction in a BigchainDB network for every document+user pair, to indicate that that user has read permissions for that document. The transaction could be signed by DocPile (or maybe by a document owner, as a variation). The asset data field would contain 1) the unique ID of the user and 2) the unique ID of the document. The one output on the CREATE transaction would only be transferable/spendable by DocPile (or, again, a document owner). @@ -45,7 +69,7 @@ You might have noticed that the above example didn’t treat the “read permiss Storing Private Data On-Chain, Encrypted ======================================== -There are many ways to store private data on-chain, encrypted. Every use case has its own objectives and constraints, and the best solution depends on the use case. `The BigchainDB consulting team `_, along with our partners, can help you design the best solution for your use case. +There are many ways to store private data on-chain, encrypted. Every use case has its own objectives and constraints, and the best solution depends on the use case. `The IPDB consulting team `_ can help you design the best solution for your use case. Below we describe some example system setups, using various crypto primitives, to give a sense of what’s possible. diff --git a/docs/root/source/assets.rst b/docs/root/source/assets.rst deleted file mode 100644 index d02ff96b..00000000 --- a/docs/root/source/assets.rst +++ /dev/null @@ -1,22 +0,0 @@ - -.. Copyright © 2020 Interplanetary Database Association e.V., - BigchainDB and IPDB software contributors. - SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) - Code is Apache-2.0 and docs are CC-BY-4.0 - -How BigchainDB is Good for Asset Registrations & Transfers -========================================================== - -BigchainDB can store data of any kind (within reason), but it's designed to be particularly good for storing asset registrations and transfers: - -* The fundamental thing that one sends to a BigchainDB network, to be checked and stored (if valid), is a *transaction*, and there are two kinds: CREATE transactions and TRANSFER transactions. -* A CREATE transaction can be use to register any kind of asset (divisible or indivisible), along with arbitrary metadata. -* An asset can have zero, one, or several owners. -* The owners of an asset can specify (crypto-)conditions which must be satisfied by anyone wishing transfer the asset to new owners. For example, a condition might be that at least 3 of the 5 current owners must cryptographically sign a TRANSFER transaction. -* BigchainDB verifies that the conditions have been satisfied as part of checking the validity of TRANSFER transactions. (Moreover, anyone can check that they were satisfied.) -* BigchainDB prevents double-spending of an asset. -* Validated transactions are :doc:`"immutable" `. - -.. note:: - - We used the word "owners" somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or transfer-enablers. See the section titled **A Note about Owners** in the relevant `BigchainDB Transactions Spec `_. \ No newline at end of file diff --git a/docs/root/source/transaction-concepts.md b/docs/root/source/basic-usage.md similarity index 90% rename from docs/root/source/transaction-concepts.md rename to docs/root/source/basic-usage.md index 420326e6..a0503b45 100644 --- a/docs/root/source/transaction-concepts.md +++ b/docs/root/source/basic-usage.md @@ -5,7 +5,9 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 ---> -# Transaction Concepts +# Basic usage + +## Transactions in BigchainDB In BigchainDB, _transactions_ are used to register, issue, create or transfer things (e.g. assets). @@ -13,7 +15,11 @@ things (e.g. assets). Transactions are the most basic kind of record stored by BigchainDB. There are two kinds: CREATE transactions and TRANSFER transactions. -## CREATE Transactions +You can view the transaction specifications in Github, which describe transaction components and the conditions they have to fulfill in order to be valid. + +[BigchainDB Transactions Specs](https://github.com/bigchaindb/BEPs/tree/master/13/) + +### CREATE Transactions A CREATE transaction can be used to register, issue, create or otherwise initiate the history of a single thing (or asset) in BigchainDB. For example, @@ -38,7 +44,7 @@ BigchainDB supports a variety of conditions. For details, see the section titled **Transaction Components: Conditions** in the relevant -[BigchainDB Transactions Spec](https://github.com/bigchaindb/BEPs/tree/master/tx-specs/). +[BigchainDB Transactions Spec](https://github.com/bigchaindb/BEPs/tree/master/13/). ![Example BigchainDB CREATE transaction](./_static/CREATE_example.png) @@ -52,13 +58,13 @@ Loosely speaking, that list might be interpreted as the list of "owners." A more accurate word might be fulfillers, signers, controllers, or transfer-enablers. See the section titled **A Note about Owners** -in the relevant [BigchainDB Transactions Spec](https://github.com/bigchaindb/BEPs/tree/master/tx-specs/). +in the relevant [BigchainDB Transactions Spec](https://github.com/bigchaindb/BEPs/tree/master/13/). A CREATE transaction must be signed by all the owners. (If you're looking for that signature, it's in the one "fulfillment" of the one input, albeit encoded.) -## TRANSFER Transactions +### TRANSFER Transactions A TRANSFER transaction can transfer/spend one or more outputs on other transactions (CREATE transactions or other TRANSFER transactions). @@ -110,18 +116,16 @@ transferred if both Jack and Kelly sign. Note how the sum of the incoming paperclips must equal the sum of the outgoing paperclips (100). -## Transaction Validity +### Transaction Validity When a node is asked to check if a transaction is valid, it checks several things. We documented those things in a post on *The BigchainDB Blog*: ["What is a Valid Transaction in BigchainDB?"](https://blog.bigchaindb.com/what-is-a-valid-transaction-in-bigchaindb-9a1a075a9598) (Note: That post was about BigchainDB Server v1.0.0.) -Each [BigchainDB Transactions Spec](https://github.com/bigchaindb/BEPs/tree/master/tx-specs/) documents the conditions for a transaction (of that version) to be valid. - -## Example Transactions +### Example Transactions There are example BigchainDB transactions in -[the HTTP API documentation](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html) +[the HTTP API documentation](./installation/api/http-client-server-api) and -[the Python Driver documentation](https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html). +[the Python Driver documentation](./drivers/index). diff --git a/docs/root/source/bft.md b/docs/root/source/bft.md deleted file mode 100644 index 2cd80fe7..00000000 --- a/docs/root/source/bft.md +++ /dev/null @@ -1,13 +0,0 @@ - - -# BigchainDB and Byzantine Fault Tolerance - -[BigchainDB Server](https://docs.bigchaindb.com/projects/server/en/latest/index.html) -uses [Tendermint](https://tendermint.com/) -for consensus and transaction replication, -and Tendermint is [Byzantine Fault Tolerant (BFT)](https://en.wikipedia.org/wiki/Byzantine_fault_tolerance). diff --git a/docs/root/source/conf.py b/docs/root/source/conf.py index 822c662d..cba72378 100644 --- a/docs/root/source/conf.py +++ b/docs/root/source/conf.py @@ -16,17 +16,31 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import wget import datetime +import os +import sys +import inspect +from os import rename, remove from recommonmark.parser import CommonMarkParser + + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) + +# get version +_version = {} +with open('../../../bigchaindb/version.py') as fp: + exec(fp.read(), _version) + + +currentdir = os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe()))) +parentdir = os.path.dirname(currentdir) +sys.path.insert(0,parentdir) +#sys.path.insert(0, "/home/myname/pythonfiles") # -- General configuration ------------------------------------------------ @@ -41,11 +55,50 @@ import sphinx_rtd_theme extensions = [ 'sphinx.ext.autosectionlabel', + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', + 'sphinx.ext.todo', + 'sphinx.ext.napoleon', + 'sphinxcontrib.httpdomain', + 'aafigure.sphinxext', + # Below are actually build steps made to look like sphinx extensions. + # It was the easiest way to get it running with ReadTheDocs. + 'generate_http_server_api_documentation', ] +try: + remove('contributing/cross-project-policies/code-of-conduct.md') + remove('contributing/cross-project-policies/release-process.md') + remove('contributing/cross-project-policies/python-style-guide.md') +except: + print('done') + +def get_old_new(url, old, new): + filename = wget.download(url) + rename(old, new) + +get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/CODE_OF_CONDUCT.md', + 'CODE_OF_CONDUCT.md', 'contributing/cross-project-policies/code-of-conduct.md') + +get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/RELEASE_PROCESS.md', + 'RELEASE_PROCESS.md', 'contributing/cross-project-policies/release-process.md') + +get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/PYTHON_STYLE_GUIDE.md', + 'PYTHON_STYLE_GUIDE.md', 'contributing/cross-project-policies/python-style-guide.md') + +suppress_warnings = ['misc.highlighting_failure'] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +# autodoc settings +autodoc_member_order = 'bysource' +autodoc_default_options = { + 'members': None, +} + source_parsers = { '.md': CommonMarkParser, } @@ -74,9 +127,10 @@ author = 'BigchainDB Contributors' # built documents. # # The short X.Y version. -version = '' +version = _version['__short_version__'] +# The full version, including alpha/beta/rc tags. +release = _version['__version__'] # The full version, including alpha/beta/rc tags. -release = '' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -170,7 +224,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/root/source/contributing/cross-project-policies/code-of-conduct.md b/docs/root/source/contributing/cross-project-policies/code-of-conduct.md new file mode 100644 index 00000000..4dff95cd --- /dev/null +++ b/docs/root/source/contributing/cross-project-policies/code-of-conduct.md @@ -0,0 +1,57 @@ + + +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of +fostering an open and welcoming community, we pledge to respect all people who +contribute to the project. + +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of level of experience, gender, gender +identity and expression, sexual orientation, disability, personal appearance, +body size, race, ethnicity, age, religion, nationality, or species--no picking on Wrigley for being a buffalo! + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic + addresses, without explicit permission +* Deliberate intimidation +* Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +By adopting this Code of Conduct, project maintainers commit themselves to +fairly and consistently applying these principles to every aspect of managing +this project. Project maintainers who do not follow or enforce the Code of +Conduct may be permanently removed from the project team. + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior directed at yourself or another community member may be +reported by contacting a project maintainer at [contact@bigchaindb.com](mailto:contact@bigchaindb.com). All +complaints will be reviewed and investigated and will result in a response that +is appropriate to the circumstances. Maintainers are +obligated to maintain confidentiality with regard to the reporter of an +incident. + + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.3.0, available at +[http://contributor-covenant.org/version/1/3/0/][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/3/0/ diff --git a/docs/contributing/source/cross-project-policies/index.rst b/docs/root/source/contributing/cross-project-policies/index.rst similarity index 100% rename from docs/contributing/source/cross-project-policies/index.rst rename to docs/root/source/contributing/cross-project-policies/index.rst diff --git a/docs/root/source/contributing/cross-project-policies/python-style-guide.md b/docs/root/source/contributing/cross-project-policies/python-style-guide.md new file mode 100644 index 00000000..5cdb39b8 --- /dev/null +++ b/docs/root/source/contributing/cross-project-policies/python-style-guide.md @@ -0,0 +1,97 @@ + + +# Python Style Guide + +This guide starts out with our general Python coding style guidelines and ends with a section on how we write & run (Python) tests. + +## General Python Coding Style Guidelines + +Our starting point is [PEP8](https://www.python.org/dev/peps/pep-0008/), the standard "Style Guide for Python Code." Many Python IDEs will check your code against PEP8. (Note that PEP8 isn't frozen; it actually changes over time, but slowly.) + +BigchainDB uses Python 3.5+, so you can ignore all PEP8 guidelines specific to Python 2. + +We use [pre-commit](http://pre-commit.com/) to check some of the rules below before every commit but not everything is realized yet. +The hooks we use can be found in the [.pre-commit-config.yaml](https://github.com/bigchaindb/bigchaindb/blob/master/.pre-commit-config.yaml) file. + +### Python Docstrings + +PEP8 says some things about docstrings, but not what to put in them or how to structure them. [PEP257](https://www.python.org/dev/peps/pep-0257/) was one proposal for docstring conventions, but we prefer [Google-style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) instead: they're easier to read and the [napoleon extension](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) for Sphinx lets us turn them into nice-looking documentation. Here are some references on Google-style docstrings: + +* [Google's docs on Google-style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) +* [napoleon's docs include an overview of Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html) +* [Example Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html) (from napoleon's docs) + +### Maximum Line Length + +PEP8 has some [maximum line length guidelines](https://www.python.org/dev/peps/pep-0008/#id17), starting with "Limit all lines to a maximum of 79 characters" but "for flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters." + +We discussed this at length, and it seems that the consensus is: _try_ to keep line lengths less than 79/72 characters, unless you have a special situation where longer lines would improve readability. (The basic reason is that 79/72 works for everyone, and BigchainDB is an open source project.) As a hard limit, keep all lines less than 119 characters (which is the width of GitHub code review). + +### Single or Double Quotes? + +Python lets you use single or double quotes. PEP8 says you can use either, as long as you're consistent. We try to stick to using single quotes, except in cases where using double quotes is more readable. For example: +```python +print('This doesn\'t look so nice.') +print("Doesn't this look nicer?") +``` + +### Breaking Strings Across Multiple Lines + +Should we use parentheses or slashes (`\`) to break strings across multiple lines, i.e. +```python +my_string = ('This is a very long string, so long that it will not fit into just one line ' + 'so it must be split across multiple lines.') +# or +my_string = 'This is a very long string, so long that it will not fit into just one line ' \ + 'so it must be split across multiple lines.' +``` + +It seems the preference is for slashes, but using parentheses is okay too. (There are good arguments either way. Arguing about it seems like a waste of time.) + +### How to Format Long import Statements + +If you need to `import` lots of names from a module or package, and they won't all fit in one line (without making the line too long), then use parentheses to spread the names across multiple lines, like so: +```python +from Tkinter import ( + Tk, Frame, Button, Entry, Canvas, Text, + LEFT, DISABLED, NORMAL, RIDGE, END, +) + +# Or + +from Tkinter import (Tk, Frame, Button, Entry, Canvas, Text, + LEFT, DISABLED, NORMAL, RIDGE, END) +``` + +For the rationale, see [PEP 328](https://www.python.org/dev/peps/pep-0328/#rationale-for-parentheses). + +### Using the % operator or `format()` to Format Strings + +Given the choice: +```python +x = 'name: %s; score: %d' % (name, n) +# or +x = 'name: {}; score: {}'.format(name, n) +``` + +we use the `format()` version. The [official Python documentation says](https://docs.python.org/2/library/stdtypes.html#str.format), "This method of string formatting is the new standard in Python 3, and should be preferred to the % formatting described in String Formatting Operations in new code." + + +## Running the Flake8 Style Checker + +We use [Flake8](http://flake8.pycqa.org/en/latest/index.html) to check our Python code style. Once you have it installed, you can run it using: +```text +flake8 --max-line-length 119 bigchaindb/ +``` + + +## Writing and Running (Python) Tests + +The content of this section was moved to [`bigchaindb/tests/README.md`](https://github.com/bigchaindb/bigchaindb/blob/master/tests/README.md). + +Note: We automatically run all tests on all pull requests (using Travis CI), so you should definitely run all tests locally before you submit a pull request. See the above-linked README file for instructions. diff --git a/docs/root/source/contributing/cross-project-policies/release-process.md b/docs/root/source/contributing/cross-project-policies/release-process.md new file mode 100644 index 00000000..84e19247 --- /dev/null +++ b/docs/root/source/contributing/cross-project-policies/release-process.md @@ -0,0 +1,101 @@ + + +# Our Release Process + +## Notes + +BigchainDB follows +[the Python form of Semantic Versioning](https://packaging.python.org/tutorials/distributing-packages/#choosing-a-versioning-scheme) +(i.e. MAJOR.MINOR.PATCH), +which is almost identical +to [regular semantic versioning](http://semver.org/), but there's no hyphen, e.g. + +- `0.9.0` for a typical final release +- `4.5.2a1` not `4.5.2-a1` for the first Alpha release +- `3.4.5rc2` not `3.4.5-rc2` for Release Candidate 2 + +**Note 1:** For Git tags (which are used to identify releases on GitHub), we append a `v` in front. For example, the Git tag for version `2.0.0a1` was `v2.0.0a1`. + +**Note 2:** For Docker image tags (e.g. on Docker Hub), we use longer version names for Alpha, Beta and Release Candidate releases. For example, the Docker image tag for version `2.0.0a2` was `2.0.0-alpha2`. + +We use `0.9` and `0.9.0` as example version and short-version values below. You should replace those with the correct values for your new version. + +We follow [BEP-1](https://github.com/bigchaindb/BEPs/tree/master/1), which is our variant of C4, the Collective Code Construction Contract, so a release is just a [tagged commit](https://git-scm.com/book/en/v2/Git-Basics-Tagging) on the `master` branch, i.e. a label for a particular Git commit. + +The following steps are what we do to release a new version of _BigchainDB Server_. The steps to release the Python Driver are similar but not the same. + +## Steps + +1. Create a pull request where you make the following changes: + + - Update `CHANGELOG.md` + - Update all Docker image tags in all Kubernetes YAML files (in the `k8s/` directory). + For example, in the files: + + - `k8s/bigchaindb/bigchaindb-ss.yaml` and + - `k8s/dev-setup/bigchaindb.yaml` + + find the line of the form `image: bigchaindb/bigchaindb:0.8.1` and change the version number to the new version number, e.g. `0.9.0`. (This is the Docker image that Kubernetes should pull from Docker Hub.) + Keep in mind that this is a _Docker image tag_ so our naming convention is + a bit different; see Note 2 in the **Notes** section above. + - In `bigchaindb/version.py`: + - update `__version__` to e.g. `0.9.0` (with no `.dev` on the end) + - update `__short_version__` to e.g. `0.9` (with no `.dev` on the end) + - In the docs about installing BigchainDB (and Tendermint), and in the associated scripts, recommend/install a version of Tendermint that _actually works_ with the soon-to-be-released version of BigchainDB. You can find all such references by doing a search for the previously-recommended version number, such as `0.31.5`. + - In `setup.py`, _maybe_ update the development status item in the `classifiers` list. For example, one allowed value is `"Development Status :: 5 - Production/Stable"`. The [allowed values are listed at pypi.python.org](https://pypi.python.org/pypi?%3Aaction=list_classifiers). + +2. **Wait for all the tests to pass!** +3. Merge the pull request into the `master` branch. +4. Go to the [bigchaindb/bigchaindb Releases page on GitHub](https://github.com/bigchaindb/bigchaindb/releases) + and click the "Draft a new release" button. +5. Fill in the details: + - **Tag version:** version number preceded by `v`, e.g. `v0.9.1` + - **Target:** the last commit that was just merged. In other words, that commit will get a Git tag with the value given for tag version above. + - **Title:** Same as tag version above, e.g `v0.9.1` + - **Description:** The body of the changelog entry (Added, Changed, etc.) +6. Click "Publish release" to publish the release on GitHub. +7. On your local computer, make sure you're on the `master` branch and that it's up-to-date with the `master` branch in the bigchaindb/bigchaindb repository (e.g. `git pull upstream master`). We're going to use that to push a new `bigchaindb` package to PyPI. +8. Make sure you have a `~/.pypirc` file containing credentials for PyPI. +9. Do `make release` to build and publish the new `bigchaindb` package on PyPI. For this step you need to have `twine` installed. If you get an error like `Makefile:135: recipe for target 'clean-pyc' failed` then try doing + ```text + sudo chown -R $(whoami):$(whoami) . + ``` +10. [Log in to readthedocs.org](https://readthedocs.org/accounts/login/) and go to the **BigchainDB Server** project, then: + - Click on "Builds", select "latest" from the drop-down menu, then click the "Build Version:" button. + - Wait for the build of "latest" to finish. This can take a few minutes. + - Go to Admin --> Advanced Settings + and make sure that "Default branch:" (i.e. what "latest" points to) + is set to the new release's tag, e.g. `v0.9.1`. + (It won't be an option if you didn't wait for the build of "latest" to finish.) + Then scroll to the bottom and click "Save". + - Go to Admin --> Versions + and under **Choose Active Versions**, do these things: + 1. Make sure that the new version's tag is "Active" and "Public" + 2. Make sure the **stable** branch is _not_ active. + 3. Scroll to the bottom of the page and click "Save". +11. Go to [Docker Hub](https://hub.docker.com/) and sign in, then: + - Click on "Organizations" + - Click on "bigchaindb" + - Click on "bigchaindb/bigchaindb" + - Click on "Build Settings" + - Find the row where "Docker Tag Name" equals `latest` + and change the value of "Name" to the name (Git tag) + of the new release, e.g. `v0.9.0`. + - If the release is an Alpha, Beta or Release Candidate release, + then a new row must be added. + You can do that by clicking the green "+" (plus) icon. + The contents of the new row should be similar to the existing rows + of previous releases like that. + - Click on "Tags" + - Delete the "latest" tag (so we can rebuild it) + - Click on "Build Settings" again + - Click on the "Trigger" button for the "latest" tag and make sure it worked by clicking on "Tags" again + - If the release is an Alpha, Beta or Release Candidate release, + then click on the "Trigger" button for that tag as well. + +Congratulations, you have released a new version of BigchainDB Server! diff --git a/docs/contributing/source/dev-setup-coding-and-contribution-process/index.rst b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/index.rst similarity index 100% rename from docs/contributing/source/dev-setup-coding-and-contribution-process/index.rst rename to docs/root/source/contributing/dev-setup-coding-and-contribution-process/index.rst diff --git a/docs/contributing/source/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md similarity index 98% rename from docs/contributing/source/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md rename to docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md index 5802b7eb..f01dd187 100644 --- a/docs/contributing/source/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md +++ b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md @@ -130,7 +130,7 @@ BigchainDB can run as a process or inside a Docker container(s) depending on you Before, running the playbook on a remote host, you need to update the `hosts` and `stack-config.yml` configuration, which will notify Ansible that we need to run the play on a remote host. -##### Update Hosts +##### Update Remote Hosts Navigate to `bigchaindb/pkg/configuration/hosts` inside the BigchainDB repository. ```text $ cd bigchaindb/pkg/configuration/hosts @@ -147,7 +147,7 @@ Edit `all` configuration file: **Note**: You can also use other methods to get inside the remote machines instead of password based SSH. For other methods please consult [Ansible Documentation](http://docs.ansible.com/ansible/latest/intro_getting_started.html). -##### Update Configuration +##### Update Remote Configuration Navigate to `bigchaindb/pkg/configuration/vars` inside the BigchainDB repository. ```text $ cd bigchaindb/pkg/configuration/vars/stack-config.yml diff --git a/docs/contributing/source/dev-setup-coding-and-contribution-process/run-dev-network-stack.md b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-stack.md similarity index 99% rename from docs/contributing/source/dev-setup-coding-and-contribution-process/run-dev-network-stack.md rename to docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-stack.md index 75eda47b..2a10c75e 100644 --- a/docs/contributing/source/dev-setup-coding-and-contribution-process/run-dev-network-stack.md +++ b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-stack.md @@ -18,7 +18,7 @@ Currently, this workflow is only supported for the following Operating systems: - Fedora >= 24 - MacOSX -## Minimum Requirements +## Machine Minimum Requirements Minimum resource requirements for a single node BigchainDB dev setup. **The more the better**: - Memory >= 512MB - VCPUs >= 1 @@ -160,7 +160,7 @@ an opinionated deployment of BigchainDB on `docker`, `local` and `cloud`. ### STACK_TYPE: docker This configuration deploys a docker based BigchainDB network on the dev/test machine that you are running `stack.sh` on. This is also the default `STACK_TYPE` config for `stack.sh`. -#### Example +#### Example: docker Deploy a 4 node docker based BigchainDB network on your host. ```text @@ -203,7 +203,7 @@ This configuration deploys a VM based BigchainDB network on your host/dev. All t - `vagrant plugin install vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure` - [Virtualbox](https://www.virtualbox.org/wiki/Downloads) -#### Example +#### Example: VM Deploy a 4 node VM based BigchainDB network. ```text diff --git a/docs/contributing/source/dev-setup-coding-and-contribution-process/run-node-as-processes.md b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-node-as-processes.md similarity index 100% rename from docs/contributing/source/dev-setup-coding-and-contribution-process/run-node-as-processes.md rename to docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-node-as-processes.md diff --git a/docs/contributing/source/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md similarity index 100% rename from docs/contributing/source/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md rename to docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md diff --git a/docs/contributing/source/dev-setup-coding-and-contribution-process/write-code.rst b/docs/root/source/contributing/dev-setup-coding-and-contribution-process/write-code.rst similarity index 100% rename from docs/contributing/source/dev-setup-coding-and-contribution-process/write-code.rst rename to docs/root/source/contributing/dev-setup-coding-and-contribution-process/write-code.rst diff --git a/docs/contributing/source/index.rst b/docs/root/source/contributing/index.rst similarity index 92% rename from docs/contributing/source/index.rst rename to docs/root/source/contributing/index.rst index a008f0c4..cd1aad6d 100644 --- a/docs/contributing/source/index.rst +++ b/docs/root/source/contributing/index.rst @@ -24,7 +24,6 @@ Contents .. toctree:: :maxdepth: 2 - ← Back to All BigchainDB Docs ways-to-contribute/index dev-setup-coding-and-contribution-process/index cross-project-policies/index diff --git a/docs/server/source/server-reference/index.rst b/docs/root/source/contributing/ways-to-contribute/index.rst similarity index 78% rename from docs/server/source/server-reference/index.rst rename to docs/root/source/contributing/ways-to-contribute/index.rst index 90582dac..008ae6e3 100644 --- a/docs/server/source/server-reference/index.rst +++ b/docs/root/source/contributing/ways-to-contribute/index.rst @@ -4,11 +4,11 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 -Settings & CLI -============== +Ways to Contribute +================== .. toctree:: :maxdepth: 1 - configuration - bigchaindb-cli + report-a-bug + write-docs diff --git a/docs/contributing/source/ways-to-contribute/write-a-bep.md b/docs/root/source/contributing/ways-to-contribute/report-a-bug.md similarity index 64% rename from docs/contributing/source/ways-to-contribute/write-a-bep.md rename to docs/root/source/contributing/ways-to-contribute/report-a-bug.md index 5c55060d..da91f94f 100644 --- a/docs/contributing/source/ways-to-contribute/write-a-bep.md +++ b/docs/root/source/contributing/ways-to-contribute/report-a-bug.md @@ -5,6 +5,29 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 ---> +How to contribute? +================== + +# Report a Bug + +To report a bug, go to the relevant GitHub repository, click on the **Issues** tab, click on the **New issue** button, and read the instructions. + +# Write an Issue + +To write an issue, go to the relevant GitHub repository, click on the **Issues** tab, click on the **New issue** button, and read the instructions. + +# Answer Questions + +People ask questions about BigchainDB in the following places: + +- Gitter + - [bigchaindb/bigchaindb](https://gitter.im/bigchaindb/bigchaindb) + - [bigchaindb/js-bigchaindb-driver](https://gitter.im/bigchaindb/js-bigchaindb-driver) +- [Twitter](https://twitter.com/bigchaindb) +- [Stack Overflow "bigchaindb"](https://stackoverflow.com/search?q=bigchaindb) + +Feel free to hang out and answer some questions. People will be thankful. + # Write a BigchainDB Enhancement Proposal (BEP) If you have an idea for a new feature or enhancement, and you want some feedback before you write a full BigchainDB Enhancement Proposal (BEP), then feel free to: @@ -18,4 +41,4 @@ If you want to discuss an existing BEP, then [open a new issue in the bigchaindb 1. Look at the structure of existing BEPs in the [bigchaindb/BEPs repo](https://github.com/bigchaindb/BEPs). Note the section headings. [BEP-2](https://github.com/bigchaindb/BEPs/tree/master/2) (our variant of the consensus-oriented specification system [COSS]) says more about the expected structure and process. 1. Write a first draft of your BEP. It doesn't have to be long or perfect. 1. Push your BEP draft to the [bigchaindb/BEPs repo](https://github.com/bigchaindb/BEPs) and make a pull request. [BEP-1](https://github.com/bigchaindb/BEPs/tree/master/1) (our variant of C4) outlines the process we use to handle all pull requests. In particular, we try to merge all pull requests quickly. -1. Your BEP can be revised by pushing more pull requests. +1. Your BEP can be revised by pushing more pull requests. \ No newline at end of file diff --git a/docs/contributing/source/ways-to-contribute/write-docs.md b/docs/root/source/contributing/ways-to-contribute/write-docs.md similarity index 100% rename from docs/contributing/source/ways-to-contribute/write-docs.md rename to docs/root/source/contributing/ways-to-contribute/write-docs.md diff --git a/docs/root/source/decentralized.md b/docs/root/source/decentralized.md deleted file mode 100644 index bdb6a245..00000000 --- a/docs/root/source/decentralized.md +++ /dev/null @@ -1,22 +0,0 @@ - - -# How BigchainDB is Decentralized - -Decentralization means that no one owns or controls everything, and there is no single point of failure. - -Ideally, each node in a BigchainDB network is owned and controlled by a different person or organization. Even if the network lives within one organization, it's still preferable to have each node controlled by a different person or subdivision. - -We use the phrase "BigchainDB consortium" (or just "consortium") to refer to the set of people and/or organizations who run the nodes of a BigchainDB network. A consortium requires some form of governance to make decisions such as membership and policies. The exact details of the governance process are determined by each consortium, but it can be very decentralized. - -A consortium can increase its decentralization (and its resilience) by increasing its jurisdictional diversity, geographic diversity, and other kinds of diversity. This idea is expanded upon in [the section on node diversity](diversity). - -There’s no node that has a long-term special position in the BigchainDB network. All nodes run the same software and perform the same duties. - -If someone has (or gets) admin access to a node, they can mess with that node (e.g. change or delete data stored on that node), but those changes should remain isolated to that node. The BigchainDB network can only be compromised if more than one third of the nodes get compromised. See the [Tendermint documentation](https://tendermint.com/docs/introduction/introduction.html) for more details. - -It’s worth noting that not even the admin or superuser of a node can transfer assets. The only way to create a valid transfer transaction is to fulfill the current crypto-conditions on the asset, and the admin/superuser can’t do that because the admin user doesn’t have the necessary information (e.g. private keys). diff --git a/docs/root/source/diversity.md b/docs/root/source/diversity.md deleted file mode 100644 index db6adf49..00000000 --- a/docs/root/source/diversity.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# Kinds of Node Diversity - -Steps should be taken to make it difficult for any one actor or event to control or damage “enough” of the nodes. (Because BigchainDB Server uses Tendermint, "enough" is ⅓.) There are many kinds of diversity to consider, listed below. It may be quite difficult to have high diversity of all kinds. - -1. **Jurisdictional diversity.** The nodes should be controlled by entities within multiple legal jurisdictions, so that it becomes difficult to use legal means to compel enough of them to do something. -1. **Geographic diversity.** The servers should be physically located at multiple geographic locations, so that it becomes difficult for a natural disaster (such as a flood or earthquake) to damage enough of them to cause problems. -1. **Hosting diversity.** The servers should be hosted by multiple hosting providers (e.g. Amazon Web Services, Microsoft Azure, Digital Ocean, Rackspace), so that it becomes difficult for one hosting provider to influence enough of the nodes. -1. **Diversity in general.** In general, membership diversity (of all kinds) confers many advantages on a consortium. For example, it provides the consortium with a source of various ideas for addressing challenges. - -Note: If all the nodes are running the same code, i.e. the same implementation of BigchainDB, then a bug in that code could be used to compromise all of the nodes. Ideally, there would be several different, well-maintained implementations of BigchainDB Server (e.g. one in Python, one in Go, etc.), so that a consortium could also have a diversity of server implementations. Similar remarks can be made about the operating system. diff --git a/docs/server/source/drivers-clients/index.rst b/docs/root/source/drivers/index.rst similarity index 85% rename from docs/server/source/drivers-clients/index.rst rename to docs/root/source/drivers/index.rst index 3c7cbe1b..f7338441 100644 --- a/docs/server/source/drivers-clients/index.rst +++ b/docs/root/source/drivers/index.rst @@ -4,8 +4,10 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 -Drivers & Tools -=============== +Drivers +======= + +Connectors to BigchainDB are referred to as drivers within the community. A driver is used to create valid transactions, to generate key pairs, to sign transactions and to post the transaction to the BigchainDB API. These drivers were originally created by the original BigchainDB team: diff --git a/docs/root/source/immutable.md b/docs/root/source/immutable.md deleted file mode 100644 index 896afb2f..00000000 --- a/docs/root/source/immutable.md +++ /dev/null @@ -1,27 +0,0 @@ - - -# How BigchainDB is Immutable - -The word _immutable_ means "unchanging over time or unable to be changed." For example, the decimal digits of π are immutable (3.14159…). - -The blockchain community often describes blockchains as “immutable.” If we interpret that word literally, it means that blockchain data is unchangeable or permanent, which is absurd. The data _can_ be changed. For example, a plague might drive humanity extinct; the data would then get corrupted over time due to water damage, thermal noise, and the general increase of entropy. - -It’s true that blockchain data is more difficult to change (or delete) than usual. It's more than just "tamper-resistant" (which implies intent), blockchain data also resists random changes that can happen without any intent, such as data corruption on a hard drive. Therefore, in the context of blockchains, we interpret the word “immutable” to mean *practically* immutable, for all intents and purposes. (Linguists would say that the word “immutable” is a _term of art_ in the blockchain community.) - -Blockchain data can be made immutable in several ways: - -1. **No APIs for changing or deleting data.** Blockchain software usually doesn't expose any APIs for changing or deleting the data stored in the blockchain. BigchainDB has no such APIs. This doesn't prevent changes or deletions from happening in _other_ ways; it's just one line of defense. -1. **Replication.** All data is replicated (copied) to several different places. The higher the replication factor, the more difficult it becomes to change or delete all replicas. -1. **Internal watchdogs.** All nodes monitor all changes and if some unallowed change happens, then appropriate action can be taken. -1. **External watchdogs.** A consortium may opt to have trusted third-parties to monitor and audit their data, looking for irregularities. For a consortium with publicly-readable data, the public can act as an auditor. -1. **Economic incentives.** Some blockchain systems make it very expensive to change old stored data. Examples include proof-of-work and proof-of-stake systems. BigchainDB doesn't use explicit incentives like those. -1. Data can be stored using fancy techniques, such as error-correction codes, to make some kinds of changes easier to undo. -1. **Cryptographic signatures** are often used as a way to check if messages (e.g. transactions) have been tampered with enroute, and as a way to verify who signed the messages. In BigchainDB, each transaction must be signed by one or more parties. -1. **Full or partial backups** may be recorded from time to time, possibly on magnetic tape storage, other blockchains, printouts, etc. -1. **Strong security.** Node owners can adopt and enforce strong security policies. -1. **Node diversity.** Diversity makes it so that no one thing (e.g. natural disaster or operating system bug) can compromise enough of the nodes. See [the section on the kinds of node diversity](diversity). diff --git a/docs/root/source/index.rst b/docs/root/source/index.rst index c7ca2048..f0c5cbd5 100644 --- a/docs/root/source/index.rst +++ b/docs/root/source/index.rst @@ -9,75 +9,11 @@ BigchainDB Documentation Meet BigchainDB. The blockchain database. -It has some database characteristics and some blockchain characteristics, -including `decentralization `_, -`immutability `_ -and `native support for assets `_. +It has some database characteristics and some blockchain `properties `_, +including decentralization, immutability and native support for assets. At a high level, one can communicate with a BigchainDB network (set of nodes) using the BigchainDB HTTP API, or a wrapper for that API, such as the BigchainDB Python Driver. Each BigchainDB node runs BigchainDB Server and various other software. The `terminology page `_ explains some of those terms in more detail. -.. raw:: html - - - -
- HTTP API Docs -
-
- Contributing to BigchainDB -
-
- Python Driver Docs -
-
- JavaScript Driver Docs -
-
- Server Docs -
-
- Server Quickstart -
- - More About BigchainDB --------------------- @@ -85,18 +21,13 @@ More About BigchainDB :maxdepth: 1 BigchainDB Docs Home - production-ready + about-bigchaindb terminology - decentralized - diversity - immutable - bft + properties + basic-usage + installation/index + drivers/index query - assets - smart-contracts - transaction-concepts - store-files - permissions - private-data - Data Models + contributing/index korean/index + diff --git a/docs/server/source/_static/Conditions_Circuit_Diagram.png b/docs/root/source/installation/_static/Conditions_Circuit_Diagram.png similarity index 100% rename from docs/server/source/_static/Conditions_Circuit_Diagram.png rename to docs/root/source/installation/_static/Conditions_Circuit_Diagram.png diff --git a/docs/server/source/_static/Node-components.png b/docs/root/source/installation/_static/Node-components.png similarity index 100% rename from docs/server/source/_static/Node-components.png rename to docs/root/source/installation/_static/Node-components.png diff --git a/docs/server/source/_static/arch.jpg b/docs/root/source/installation/_static/arch.jpg similarity index 100% rename from docs/server/source/_static/arch.jpg rename to docs/root/source/installation/_static/arch.jpg diff --git a/docs/server/source/_static/cc_escrow_execute_abort.png b/docs/root/source/installation/_static/cc_escrow_execute_abort.png similarity index 100% rename from docs/server/source/_static/cc_escrow_execute_abort.png rename to docs/root/source/installation/_static/cc_escrow_execute_abort.png diff --git a/docs/server/source/_static/models_diagrams.odg b/docs/root/source/installation/_static/models_diagrams.odg similarity index 100% rename from docs/server/source/_static/models_diagrams.odg rename to docs/root/source/installation/_static/models_diagrams.odg diff --git a/docs/server/source/_static/mongodb_cloud_manager_1.png b/docs/root/source/installation/_static/mongodb_cloud_manager_1.png similarity index 100% rename from docs/server/source/_static/mongodb_cloud_manager_1.png rename to docs/root/source/installation/_static/mongodb_cloud_manager_1.png diff --git a/docs/server/source/_static/monitoring_system_diagram.png b/docs/root/source/installation/_static/monitoring_system_diagram.png similarity index 100% rename from docs/server/source/_static/monitoring_system_diagram.png rename to docs/root/source/installation/_static/monitoring_system_diagram.png diff --git a/docs/server/source/_static/stories_3_assets.png b/docs/root/source/installation/_static/stories_3_assets.png similarity index 100% rename from docs/server/source/_static/stories_3_assets.png rename to docs/root/source/installation/_static/stories_3_assets.png diff --git a/docs/server/source/_static/tx_escrow_execute_abort.png b/docs/root/source/installation/_static/tx_escrow_execute_abort.png similarity index 100% rename from docs/server/source/_static/tx_escrow_execute_abort.png rename to docs/root/source/installation/_static/tx_escrow_execute_abort.png diff --git a/docs/server/source/_static/tx_multi_condition_multi_fulfillment_v1.png b/docs/root/source/installation/_static/tx_multi_condition_multi_fulfillment_v1.png similarity index 100% rename from docs/server/source/_static/tx_multi_condition_multi_fulfillment_v1.png rename to docs/root/source/installation/_static/tx_multi_condition_multi_fulfillment_v1.png diff --git a/docs/server/source/_static/tx_schematics.odg b/docs/root/source/installation/_static/tx_schematics.odg similarity index 100% rename from docs/server/source/_static/tx_schematics.odg rename to docs/root/source/installation/_static/tx_schematics.odg diff --git a/docs/server/source/_static/tx_single_condition_single_fulfillment_v1.png b/docs/root/source/installation/_static/tx_single_condition_single_fulfillment_v1.png similarity index 100% rename from docs/server/source/_static/tx_single_condition_single_fulfillment_v1.png rename to docs/root/source/installation/_static/tx_single_condition_single_fulfillment_v1.png diff --git a/docs/server/source/http-client-server-api.rst b/docs/root/source/installation/api/http-client-server-api.rst similarity index 99% rename from docs/server/source/http-client-server-api.rst rename to docs/root/source/installation/api/http-client-server-api.rst index dd487b7d..0c41324e 100644 --- a/docs/server/source/http-client-server-api.rst +++ b/docs/root/source/installation/api/http-client-server-api.rst @@ -49,8 +49,8 @@ that allows you to discover the BigchainDB API endpoints: :language: http -Transactions ------------- +Transactions Endpoint +--------------------- .. note:: @@ -713,7 +713,7 @@ so you can access it from the same machine, but it won't be directly accessible from the outside world. (The outside world could connect via a SOCKS proxy or whatnot.) -The documentation about BigchainDB Server :doc:`Configuration Settings ` +The documentation about BigchainDB Server :doc:`Configuration Settings <../../installation/node-setup/configuration>` has a section about how to set ``server.bind`` so as to make the HTTP API publicly accessible. diff --git a/docs/root/source/installation/api/http-samples/api-index-response.http b/docs/root/source/installation/api/http-samples/api-index-response.http new file mode 100644 index 00000000..fae85377 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/api-index-response.http @@ -0,0 +1,13 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "assets": "/assets/", + "blocks": "/blocks/", + "docs": "https://docs.bigchaindb.com/projects/server/en/v2.2.1/http-client-server-api.html", + "metadata": "/metadata/", + "outputs": "/outputs/", + "streams": "ws://localhost:9985/api/v1/streams/valid_transactions", + "transactions": "/transactions/", + "validators": "/validators" +} diff --git a/docs/root/source/installation/api/http-samples/get-block-request.http b/docs/root/source/installation/api/http-samples/get-block-request.http new file mode 100644 index 00000000..596e19b8 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-block-request.http @@ -0,0 +1,3 @@ +GET /api/v1/blocks/1 HTTP/1.1 +Host: example.com + diff --git a/docs/root/source/installation/api/http-samples/get-block-response.http b/docs/root/source/installation/api/http-samples/get-block-response.http new file mode 100644 index 00000000..a816c2b2 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-block-response.http @@ -0,0 +1,45 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "height": 1, + "transactions": [ + { + "asset": { + "data": { + "msg": "Hello BigchainDB!" + } + }, + "id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317", + "inputs": [ + { + "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCy4BR6gKaYT-tdyAGPPpknIqI4JYQQ-p2nCg3_9BfOI-15vzldhyz-j_LZVpqAlRmbTzKS-Q5gs7ZIFaZCA_UD", + "fulfills": null, + "owners_before": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "metadata": { + "sequence": 0 + }, + "operation": "CREATE", + "outputs": [ + { + "amount": "1", + "condition": { + "details": { + "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", + "type": "ed25519-sha-256" + }, + "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" + }, + "public_keys": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "version": "2.0" + } + ] +} diff --git a/docs/root/source/installation/api/http-samples/get-block-txid-request.http b/docs/root/source/installation/api/http-samples/get-block-txid-request.http new file mode 100644 index 00000000..1f17c6bb --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-block-txid-request.http @@ -0,0 +1,3 @@ +GET /api/v1/blocks?transaction_id=4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317 HTTP/1.1 +Host: example.com + diff --git a/docs/root/source/installation/api/http-samples/get-block-txid-response.http b/docs/root/source/installation/api/http-samples/get-block-txid-response.http new file mode 100644 index 00000000..377f0e7c --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-block-txid-response.http @@ -0,0 +1,6 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +[ + 1 +] diff --git a/docs/root/source/installation/api/http-samples/get-tx-by-asset-request.http b/docs/root/source/installation/api/http-samples/get-tx-by-asset-request.http new file mode 100644 index 00000000..a5c8f3f9 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-tx-by-asset-request.http @@ -0,0 +1,3 @@ +GET /api/v1/transactions?operation=TRANSFER&asset_id=4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317 HTTP/1.1 +Host: example.com + diff --git a/docs/root/source/installation/api/http-samples/get-tx-by-asset-response.http b/docs/root/source/installation/api/http-samples/get-tx-by-asset-response.http new file mode 100644 index 00000000..63f99123 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-tx-by-asset-response.http @@ -0,0 +1,79 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +[{ + "asset": { + "id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317" + }, + "id": "79ef6803210c941903d63d08b40fa17f0a5a04f11ac0ff04451553a187d97a30", + "inputs": [ + { + "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUAYRI8kzKaZcrW-_avQrAIk5q-7o_7U6biBvoHk1ioBLqHSBcE_PAdNEaeWesAAW_HeCqNUWKaJ5Lzo5Nfz7QgN", + "fulfills": { + "output_index": 0, + "transaction_id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317" + }, + "owners_before": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "metadata": { + "sequence": 1 + }, + "operation": "TRANSFER", + "outputs": [ + { + "amount": "1", + "condition": { + "details": { + "public_key": "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9", + "type": "ed25519-sha-256" + }, + "uri": "ni:///sha-256;lu6ov4AKkee6KWGnyjOVLBeyuP0bz4-O6_dPi15eYUc?fpt=ed25519-sha-256&cost=131072" + }, + "public_keys": [ + "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9" + ] + } + ], + "version": "2.0" +}, +{ + "asset": { + "id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317" + }, + "id": "1fec726a3b426498147f1a1f19a92c187d551a7f66db4b88d666d7dcc10e86a4", + "inputs": [ + { + "fulfillment": "pGSAICw7Ul-c2lG6NFbHp3FbKRC7fivQcNGO7GS4wV3A-1QggUARCMty2JBK_OyPJntWEFxDG4-VbKMy853NtqwnPib5QUJIuwPQa1Y4aN2iIBuoqGE85Pmjcc1ScG9FCPSQHacK", + "fulfills": { + "output_index": 0, + "transaction_id": "79ef6803210c941903d63d08b40fa17f0a5a04f11ac0ff04451553a187d97a30" + }, + "owners_before": [ + "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9" + ] + } + ], + "metadata": { + "sequence": 2 + }, + "operation": "TRANSFER", + "outputs": [ + { + "amount": "1", + "condition": { + "details": { + "public_key": "3Af3fhhjU6d9WecEM9Uw5hfom9kNEwE7YuDWdqAUssqm", + "type": "ed25519-sha-256" + }, + "uri": "ni:///sha-256;Ll1r0LzgHUvWB87yIrNFYo731MMUEypqvrbPATTbuD4?fpt=ed25519-sha-256&cost=131072" + }, + "public_keys": [ + "3Af3fhhjU6d9WecEM9Uw5hfom9kNEwE7YuDWdqAUssqm" + ] + } + ], + "version": "2.0" +}] diff --git a/docs/root/source/installation/api/http-samples/get-tx-id-request.http b/docs/root/source/installation/api/http-samples/get-tx-id-request.http new file mode 100644 index 00000000..87bd1233 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-tx-id-request.http @@ -0,0 +1,3 @@ +GET /api/v1/transactions/4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317 HTTP/1.1 +Host: example.com + diff --git a/docs/root/source/installation/api/http-samples/get-tx-id-response.http b/docs/root/source/installation/api/http-samples/get-tx-id-response.http new file mode 100644 index 00000000..df077703 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/get-tx-id-response.http @@ -0,0 +1,40 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "asset": { + "data": { + "msg": "Hello BigchainDB!" + } + }, + "id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317", + "inputs": [ + { + "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCy4BR6gKaYT-tdyAGPPpknIqI4JYQQ-p2nCg3_9BfOI-15vzldhyz-j_LZVpqAlRmbTzKS-Q5gs7ZIFaZCA_UD", + "fulfills": null, + "owners_before": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "metadata": { + "sequence": 0 + }, + "operation": "CREATE", + "outputs": [ + { + "amount": "1", + "condition": { + "details": { + "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", + "type": "ed25519-sha-256" + }, + "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" + }, + "public_keys": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "version": "2.0" +} diff --git a/docs/root/source/installation/api/http-samples/index-response.http b/docs/root/source/installation/api/http-samples/index-response.http new file mode 100644 index 00000000..5b17a040 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/index-response.http @@ -0,0 +1,20 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "api": { + "v1": { + "assets": "/api/v1/assets/", + "blocks": "/api/v1/blocks/", + "docs": "https://docs.bigchaindb.com/projects/server/en/v2.2.1/http-client-server-api.html", + "metadata": "/api/v1/metadata/", + "outputs": "/api/v1/outputs/", + "streams": "ws://localhost:9985/api/v1/streams/valid_transactions", + "transactions": "/api/v1/transactions/", + "validators": "/api/v1/validators" + } + }, + "docs": "https://docs.bigchaindb.com/projects/server/en/v2.2.1/", + "software": "BigchainDB", + "version": "2.2.1" +} diff --git a/docs/root/source/installation/api/http-samples/post-tx-request.http b/docs/root/source/installation/api/http-samples/post-tx-request.http new file mode 100644 index 00000000..55b64df4 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/post-tx-request.http @@ -0,0 +1,41 @@ +POST /api/v1/transactions?mode=async HTTP/1.1 +Host: example.com +Content-Type: application/json + +{ + "asset": { + "data": { + "msg": "Hello BigchainDB!" + } + }, + "id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317", + "inputs": [ + { + "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCy4BR6gKaYT-tdyAGPPpknIqI4JYQQ-p2nCg3_9BfOI-15vzldhyz-j_LZVpqAlRmbTzKS-Q5gs7ZIFaZCA_UD", + "fulfills": null, + "owners_before": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "metadata": { + "sequence": 0 + }, + "operation": "CREATE", + "outputs": [ + { + "amount": "1", + "condition": { + "details": { + "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", + "type": "ed25519-sha-256" + }, + "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" + }, + "public_keys": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "version": "2.0" +} diff --git a/docs/root/source/installation/api/http-samples/post-tx-response.http b/docs/root/source/installation/api/http-samples/post-tx-response.http new file mode 100644 index 00000000..4cd84ac9 --- /dev/null +++ b/docs/root/source/installation/api/http-samples/post-tx-response.http @@ -0,0 +1,40 @@ +HTTP/1.1 202 Accepted +Content-Type: application/json + +{ + "asset": { + "data": { + "msg": "Hello BigchainDB!" + } + }, + "id": "4957744b3ac54434b8270f2c854cc1040228c82ea4e72d66d2887a4d3e30b317", + "inputs": [ + { + "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCy4BR6gKaYT-tdyAGPPpknIqI4JYQQ-p2nCg3_9BfOI-15vzldhyz-j_LZVpqAlRmbTzKS-Q5gs7ZIFaZCA_UD", + "fulfills": null, + "owners_before": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "metadata": { + "sequence": 0 + }, + "operation": "CREATE", + "outputs": [ + { + "amount": "1", + "condition": { + "details": { + "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", + "type": "ed25519-sha-256" + }, + "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" + }, + "public_keys": [ + "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" + ] + } + ], + "version": "2.0" +} diff --git a/docs/server/source/events/index.rst b/docs/root/source/installation/api/index.rst similarity index 87% rename from docs/server/source/events/index.rst rename to docs/root/source/installation/api/index.rst index 5c4025cb..6ed5d06e 100644 --- a/docs/server/source/events/index.rst +++ b/docs/root/source/installation/api/index.rst @@ -4,10 +4,13 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 -The Events API -============== + + +API +=== .. toctree:: :maxdepth: 1 + http-client-server-api websocket-event-stream-api diff --git a/docs/server/source/events/websocket-event-stream-api.rst b/docs/root/source/installation/api/websocket-event-stream-api.rst similarity index 97% rename from docs/server/source/events/websocket-event-stream-api.rst rename to docs/root/source/installation/api/websocket-event-stream-api.rst index 49efc7ac..73e11553 100644 --- a/docs/server/source/events/websocket-event-stream-api.rst +++ b/docs/root/source/installation/api/websocket-event-stream-api.rst @@ -66,7 +66,7 @@ BigchainDB node will be ignored. Streams will always be under the WebSocket protocol (so ``ws://`` or ``wss://``) and accessible as extensions to the ``/api/v/streams/`` -API root URL (for example, `valid transactions <#valid-transactions>`_ +API root URL (for example, valid transactions would be accessible under ``/api/v1/streams/valid_transactions``). If you're running your own BigchainDB instance and need help determining its root URL, then see the page titled :ref:`determining-the-api-root-url`. diff --git a/docs/server/source/appendices/cryptography.rst b/docs/root/source/installation/appendices/cryptography.rst similarity index 100% rename from docs/server/source/appendices/cryptography.rst rename to docs/root/source/installation/appendices/cryptography.rst diff --git a/docs/server/source/appendices/firewall-notes.md b/docs/root/source/installation/appendices/firewall-notes.md similarity index 96% rename from docs/server/source/appendices/firewall-notes.md rename to docs/root/source/installation/appendices/firewall-notes.md index c00434dc..2cde9b35 100644 --- a/docs/server/source/appendices/firewall-notes.md +++ b/docs/root/source/installation/appendices/firewall-notes.md @@ -49,7 +49,7 @@ Port 443 is the default HTTPS port (TCP). Package managers might also get some p Port 9984 is the default port for the BigchainDB client-server HTTP API (TCP), which is served by Gunicorn HTTP Server. It's _possible_ allow port 9984 to accept inbound traffic from anyone, but we recommend against doing that. Instead, set up a reverse proxy server (e.g. using Nginx) and only allow traffic from there. Information about how to do that can be found [in the Gunicorn documentation](http://docs.gunicorn.org/en/stable/deploy.html). (They call it a proxy.) -If Gunicorn and the reverse proxy are running on the same server, then you'll have to tell Gunicorn to listen on some port other than 9984 (so that the reverse proxy can listen on port 9984). You can do that by setting `server.bind` to 'localhost:PORT' in the [BigchainDB Configuration Settings](../server-reference/configuration), where PORT is whatever port you chose (e.g. 9983). +If Gunicorn and the reverse proxy are running on the same server, then you'll have to tell Gunicorn to listen on some port other than 9984 (so that the reverse proxy can listen on port 9984). You can do that by setting `server.bind` to 'localhost:PORT' in the [BigchainDB Configuration Settings](../../installation/node-setup/configuration), where PORT is whatever port you chose (e.g. 9983). You may want to have Gunicorn and the reverse proxy running on different servers, so that both can listen on port 9984. That would also help isolate the effects of a denial-of-service attack. diff --git a/docs/server/source/appendices/generate-key-pair-for-ssh.md b/docs/root/source/installation/appendices/generate-key-pair-for-ssh.md similarity index 100% rename from docs/server/source/appendices/generate-key-pair-for-ssh.md rename to docs/root/source/installation/appendices/generate-key-pair-for-ssh.md diff --git a/docs/server/source/appendices/index.rst b/docs/root/source/installation/appendices/index.rst similarity index 85% rename from docs/server/source/appendices/index.rst rename to docs/root/source/installation/appendices/index.rst index 12e87fee..2ee88916 100755 --- a/docs/server/source/appendices/index.rst +++ b/docs/root/source/installation/appendices/index.rst @@ -10,12 +10,10 @@ Appendices .. toctree:: :maxdepth: 1 - json-serialization - cryptography - aws-setup generate-key-pair-for-ssh + cryptography firewall-notes ntp-notes - licenses - all-in-one-bigchaindb log-rotation + licenses + diff --git a/docs/server/source/appendices/licenses.md b/docs/root/source/installation/appendices/licenses.md similarity index 100% rename from docs/server/source/appendices/licenses.md rename to docs/root/source/installation/appendices/licenses.md diff --git a/docs/server/source/appendices/log-rotation.md b/docs/root/source/installation/appendices/log-rotation.md similarity index 91% rename from docs/server/source/appendices/log-rotation.md rename to docs/root/source/installation/appendices/log-rotation.md index 4539fff0..f63b15d4 100644 --- a/docs/server/source/appendices/log-rotation.md +++ b/docs/root/source/installation/appendices/log-rotation.md @@ -32,7 +32,7 @@ BigchainDB Server writes its logs to two files: normal logs and error logs. The Log rotation is baked into BigchainDB Server using Python's `logging` module. The logs for BigchainDB Server are rotated when any of the above mentioned files exceeds 209715200 bytes (i.e. approximately 209 MB). -For more information, see the docs about [the BigchainDB Server configuration settings related to logging](../server-reference/configuration#log). +For more information, see the docs about [the BigchainDB Server configuration settings related to logging](../../installation/node-setup/configuration#log). ## Tendermint Logging and Log Rotation @@ -42,7 +42,7 @@ Tendermint writes its logs to the files: - `tendermint.err.log` If you started BigchainDB Server and Tendermint using Monit, as suggested by our guide on -[How to Set Up a BigchainDB Network](../simple-deployment-template/network-setup), +[How to Set Up a BigchainDB Network](../network-setup/network-setup), then the logs will be written to `$HOME/.bigchaindb-monit/logs/`. Moreover, if you started BigchainDB Server and Tendermint using Monit, diff --git a/docs/server/source/appendices/ntp-notes.md b/docs/root/source/installation/appendices/ntp-notes.md similarity index 100% rename from docs/server/source/appendices/ntp-notes.md rename to docs/root/source/installation/appendices/ntp-notes.md diff --git a/docs/server/source/code-reference/backend.rst b/docs/root/source/installation/commands-and-backend/backend.rst similarity index 100% rename from docs/server/source/code-reference/backend.rst rename to docs/root/source/installation/commands-and-backend/backend.rst diff --git a/docs/server/source/code-reference/commands.rst b/docs/root/source/installation/commands-and-backend/commands.rst similarity index 100% rename from docs/server/source/code-reference/commands.rst rename to docs/root/source/installation/commands-and-backend/commands.rst diff --git a/docs/server/source/code-reference/index.rst b/docs/root/source/installation/commands-and-backend/index.rst similarity index 92% rename from docs/server/source/code-reference/index.rst rename to docs/root/source/installation/commands-and-backend/index.rst index 3dc8332f..2cbc2fcd 100644 --- a/docs/server/source/code-reference/index.rst +++ b/docs/root/source/installation/commands-and-backend/index.rst @@ -4,8 +4,8 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 -Code Reference -============== +Commands And Backend +==================== This section contains auto-generated documentation of various functions, classes and methods in the BigchainDB Server code, based on Python docstrings in the code itself. @@ -19,7 +19,8 @@ in the BigchainDB Server code, based on Python docstrings in the code itself. .. toctree:: :maxdepth: 1 + commands the-bigchaindb-class backend - commands + \ No newline at end of file diff --git a/docs/server/source/code-reference/the-bigchaindb-class.rst b/docs/root/source/installation/commands-and-backend/the-bigchaindb-class.rst similarity index 100% rename from docs/server/source/code-reference/the-bigchaindb-class.rst rename to docs/root/source/installation/commands-and-backend/the-bigchaindb-class.rst diff --git a/docs/root/source/installation/index.rst b/docs/root/source/installation/index.rst new file mode 100644 index 00000000..b16c9eda --- /dev/null +++ b/docs/root/source/installation/index.rst @@ -0,0 +1,20 @@ + +.. Copyright © 2020 Interplanetary Database Association e.V., + BigchainDB and IPDB software contributors. + SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) + Code is Apache-2.0 and docs are CC-BY-4.0 + +Installation +============ + +You can install a single node to test out BigchainDB, connect it to a network or setup a network of nodes. + +.. toctree:: + :maxdepth: 1 + + quickstart + node-setup/index + network-setup/index + api/index + commands-and-backend/index + appendices/index diff --git a/docs/root/source/installation/network-setup/bigchaindb-node-ansible.md b/docs/root/source/installation/network-setup/bigchaindb-node-ansible.md new file mode 100644 index 00000000..08627731 --- /dev/null +++ b/docs/root/source/installation/network-setup/bigchaindb-node-ansible.md @@ -0,0 +1,7 @@ +# Network of nodes with the Ansible script + +You can find one of the installation methods with Ansible on GitHub at: + +[Ansible script](https://github.com/bigchaindb/bigchaindb-node-ansible) + +It allows to install BigchainDB, MongoDB, Tendermint, and python, and then connect nodes into a network. Current tested machine is Ubuntu 18.04. \ No newline at end of file diff --git a/docs/root/source/installation/network-setup/index.rst b/docs/root/source/installation/network-setup/index.rst new file mode 100644 index 00000000..386920e6 --- /dev/null +++ b/docs/root/source/installation/network-setup/index.rst @@ -0,0 +1,19 @@ + +.. Copyright © 2020 Interplanetary Database Association e.V., + BigchainDB and IPDB software contributors. + SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) + Code is Apache-2.0 and docs are CC-BY-4.0 + +Network setup +============= + +There are several ways to setup a network. You can use the Kubernetes deployment template in this section, or use the Ansible solution in the Contributing section. Also, you can setup a single node on your machine and connect to an existing network. + +.. toctree:: + :maxdepth: 1 + + networks + network-setup + k8s-deployment-template/index + bigchaindb-node-ansible.md + \ No newline at end of file diff --git a/docs/server/source/k8s-deployment-template/architecture.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/architecture.rst similarity index 99% rename from docs/server/source/k8s-deployment-template/architecture.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/architecture.rst index b692f4a2..c996eaff 100644 --- a/docs/server/source/k8s-deployment-template/architecture.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/architecture.rst @@ -13,7 +13,7 @@ Architecture of a BigchainDB Node Running in a Kubernetes Cluster (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. @@ -34,8 +34,8 @@ as described in these docs, it will include: .. _bigchaindb-node: -BigchainDB Node ---------------- +BigchainDB Node Diagram +----------------------- .. aafig:: :aspect: 60 diff --git a/docs/server/source/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst similarity index 99% rename from docs/server/source/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst index 4a358c89..e50502bf 100644 --- a/docs/server/source/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst @@ -15,7 +15,7 @@ Kubernetes Template: Deploying a BigchainDB network (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/k8s-deployment-template/ca-installation.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/ca-installation.rst similarity index 100% rename from docs/server/source/k8s-deployment-template/ca-installation.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/ca-installation.rst diff --git a/docs/server/source/k8s-deployment-template/client-tls-certificate.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/client-tls-certificate.rst similarity index 100% rename from docs/server/source/k8s-deployment-template/client-tls-certificate.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/client-tls-certificate.rst diff --git a/docs/server/source/k8s-deployment-template/cloud-manager.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/cloud-manager.rst similarity index 93% rename from docs/server/source/k8s-deployment-template/cloud-manager.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/cloud-manager.rst index 60d5e23e..95bd88ab 100644 --- a/docs/server/source/k8s-deployment-template/cloud-manager.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/cloud-manager.rst @@ -13,8 +13,8 @@ This document details the steps required to configure MongoDB Cloud Manager to enable monitoring of data in a MongoDB Replica Set. -Configure MongoDB Cloud Manager for Monitoring ----------------------------------------------- +Configure MongoDB Cloud Manager for Monitoring Step by Step +----------------------------------------------------------- * Once the Monitoring Agent is up and running, open `MongoDB Cloud Manager `_. @@ -60,7 +60,7 @@ Configure MongoDB Cloud Manager for Monitoring * Verify that you see your process on the Cloud Manager UI. It should look something like this: - .. image:: /_static/mongodb_cloud_manager_1.png + .. image:: ../../_static/mongodb_cloud_manager_1.png * Click ``Continue``. diff --git a/docs/server/source/k8s-deployment-template/easy-rsa.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/easy-rsa.rst similarity index 100% rename from docs/server/source/k8s-deployment-template/easy-rsa.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/easy-rsa.rst diff --git a/docs/server/source/k8s-deployment-template/index.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/index.rst similarity index 96% rename from docs/server/source/k8s-deployment-template/index.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/index.rst index 0b8fbe7f..a79b95ab 100644 --- a/docs/server/source/k8s-deployment-template/index.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/index.rst @@ -15,7 +15,7 @@ Kubernetes Deployment Template (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/k8s-deployment-template/log-analytics.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/log-analytics.rst similarity index 99% rename from docs/server/source/k8s-deployment-template/log-analytics.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/log-analytics.rst index cb7fc0fc..fd056f5b 100644 --- a/docs/server/source/k8s-deployment-template/log-analytics.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/log-analytics.rst @@ -179,7 +179,7 @@ Then see `Microsoft's instructions to obtain your workspace ID and key Once you have the workspace id and key, you can include them in the following YAML file (:download:`oms-daemonset.yaml -<../../../../k8s/logging-and-monitoring/oms-daemonset.yaml>`): +<../../../../../../k8s/logging-and-monitoring/oms-daemonset.yaml>`): .. code-block:: yaml diff --git a/docs/server/source/k8s-deployment-template/node-config-map-and-secrets.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/node-config-map-and-secrets.rst similarity index 98% rename from docs/server/source/k8s-deployment-template/node-config-map-and-secrets.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/node-config-map-and-secrets.rst index c90ba3bc..c40058b8 100644 --- a/docs/server/source/k8s-deployment-template/node-config-map-and-secrets.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/node-config-map-and-secrets.rst @@ -15,7 +15,7 @@ How to Configure a BigchainDB Node (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/k8s-deployment-template/node-on-kubernetes.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/node-on-kubernetes.rst similarity index 99% rename from docs/server/source/k8s-deployment-template/node-on-kubernetes.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/node-on-kubernetes.rst index 1f4492ea..88a469c2 100644 --- a/docs/server/source/k8s-deployment-template/node-on-kubernetes.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/node-on-kubernetes.rst @@ -15,7 +15,7 @@ Kubernetes Template: Deploy a Single BigchainDB Node (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/k8s-deployment-template/revoke-tls-certificate.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/revoke-tls-certificate.rst similarity index 100% rename from docs/server/source/k8s-deployment-template/revoke-tls-certificate.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/revoke-tls-certificate.rst diff --git a/docs/server/source/k8s-deployment-template/server-tls-certificate.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/server-tls-certificate.rst similarity index 100% rename from docs/server/source/k8s-deployment-template/server-tls-certificate.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/server-tls-certificate.rst diff --git a/docs/server/source/k8s-deployment-template/tectonic-azure.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/tectonic-azure.rst similarity index 98% rename from docs/server/source/k8s-deployment-template/tectonic-azure.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/tectonic-azure.rst index aa998d2d..fffddd25 100644 --- a/docs/server/source/k8s-deployment-template/tectonic-azure.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/tectonic-azure.rst @@ -13,7 +13,7 @@ Walkthrough: Deploy a Kubernetes Cluster on Azure using Tectonic by CoreOS (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/k8s-deployment-template/template-kubernetes-azure.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/template-kubernetes-azure.rst similarity index 98% rename from docs/server/source/k8s-deployment-template/template-kubernetes-azure.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/template-kubernetes-azure.rst index 042d4303..c1fc5692 100644 --- a/docs/server/source/k8s-deployment-template/template-kubernetes-azure.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/template-kubernetes-azure.rst @@ -13,7 +13,7 @@ Template: Deploy a Kubernetes Cluster on Azure (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. @@ -50,7 +50,7 @@ for your Kubernetes VMs and nothing else.) See the :doc:`page about how to generate a key pair for SSH -<../appendices/generate-key-pair-for-ssh>`. +<../../appendices/generate-key-pair-for-ssh>`. Step 3: Deploy an Azure Container Service (ACS) diff --git a/docs/server/source/k8s-deployment-template/troubleshoot.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/troubleshoot.rst similarity index 100% rename from docs/server/source/k8s-deployment-template/troubleshoot.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/troubleshoot.rst diff --git a/docs/server/source/k8s-deployment-template/upgrade-on-kubernetes.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/upgrade-on-kubernetes.rst similarity index 98% rename from docs/server/source/k8s-deployment-template/upgrade-on-kubernetes.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/upgrade-on-kubernetes.rst index 701b05c2..179d7cd1 100644 --- a/docs/server/source/k8s-deployment-template/upgrade-on-kubernetes.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/upgrade-on-kubernetes.rst @@ -13,7 +13,7 @@ Kubernetes Template: Upgrade all Software in a BigchainDB Node (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/k8s-deployment-template/workflow.rst b/docs/root/source/installation/network-setup/k8s-deployment-template/workflow.rst similarity index 99% rename from docs/server/source/k8s-deployment-template/workflow.rst rename to docs/root/source/installation/network-setup/k8s-deployment-template/workflow.rst index 365cf4ae..fd08a86d 100644 --- a/docs/server/source/k8s-deployment-template/workflow.rst +++ b/docs/root/source/installation/network-setup/k8s-deployment-template/workflow.rst @@ -15,7 +15,7 @@ Overview (three for the master and two for your app's containers). Therefore we don't recommend using Kubernetes to run a BigchainDB node if that's the only thing the Kubernetes cluster will be running. - Instead, see our :ref:`simple-deployment-template`. + Instead, see our `Node Setup <../../node_setup>`_. If your organization already *has* a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful. diff --git a/docs/server/source/simple-deployment-template/network-setup.md b/docs/root/source/installation/network-setup/network-setup.md similarity index 96% rename from docs/server/source/simple-deployment-template/network-setup.md rename to docs/root/source/installation/network-setup/network-setup.md index a7b97b4b..c081c529 100644 --- a/docs/server/source/simple-deployment-template/network-setup.md +++ b/docs/root/source/installation/network-setup/network-setup.md @@ -7,6 +7,7 @@ Code is Apache-2.0 and docs are CC-BY-4.0 # How to Set Up a BigchainDB Network +You can setup or connect to a network once you have a single node running. Until now, everything could be done by a node operator, by themselves. Now the node operators, also called **Members**, must share some information with each other, so they can form a network. @@ -198,7 +199,7 @@ If you want to start and manage the BigchainDB and Tendermint processes yourself ## How Others Can Access Your Node -If you followed the above instructions, then your node should be publicly-accessible with BigchainDB Root URL `https://hostname` or `http://hostname:9984`. That is, anyone can interact with your node using the [BigchainDB HTTP API](../../http-client-server-api) exposed at that address. The most common way to do that is to use one of the [BigchainDB Drivers](../../drivers-clients/index). +If you followed the above instructions, then your node should be publicly-accessible with BigchainDB Root URL `https://hostname` or `http://hostname:9984`. That is, anyone can interact with your node using the [BigchainDB HTTP API](../api/http-client-server-api) exposed at that address. The most common way to do that is to use one of the [BigchainDB Drivers](../../drivers/index). [bdb:software]: https://github.com/bigchaindb/bigchaindb/ [bdb:pypi]: https://pypi.org/project/BigchainDB/#history diff --git a/docs/server/source/networks.md b/docs/root/source/installation/network-setup/networks.md similarity index 94% rename from docs/server/source/networks.md rename to docs/root/source/installation/network-setup/networks.md index 8e0d91fe..058df075 100644 --- a/docs/server/source/networks.md +++ b/docs/root/source/installation/network-setup/networks.md @@ -25,7 +25,7 @@ We now describe how *we* set up the external (public-facing) DNS records for a B There were several goals: * Allow external users/clients to connect directly to any BigchainDB node in the network (over the internet), if they want. -* Each BigchainDB node operator should get an SSL certificate for their BigchainDB node, so that their BigchainDB node can serve the [BigchainDB HTTP API](http-client-server-api) via HTTPS. (The same certificate might also be used to serve the [WebSocket API](events/websocket-event-stream-api).) +* Each BigchainDB node operator should get an SSL certificate for their BigchainDB node, so that their BigchainDB node can serve the [BigchainDB HTTP API](../api/http-client-server-api) via HTTPS. (The same certificate might also be used to serve the [WebSocket API](../api/websocket-event-stream-api).) * There should be no sharing of SSL certificates among BigchainDB node operators. * Optional: Allow clients to connect to a "random" BigchainDB node in the network at one particular domain (or subdomain). diff --git a/docs/server/source/appendices/all-in-one-bigchaindb.md b/docs/root/source/installation/node-setup/all-in-one-bigchaindb.md similarity index 97% rename from docs/server/source/appendices/all-in-one-bigchaindb.md rename to docs/root/source/installation/node-setup/all-in-one-bigchaindb.md index cd5067ee..4585c058 100644 --- a/docs/server/source/appendices/all-in-one-bigchaindb.md +++ b/docs/root/source/installation/node-setup/all-in-one-bigchaindb.md @@ -71,7 +71,7 @@ Let's analyze that command: $ docker ps | grep bigchaindb ``` -Send your first transaction using [BigchainDB drivers](../drivers-clients/index). +Send your first transaction using [BigchainDB drivers](../../drivers/index). ## Building Your Own Image diff --git a/docs/server/source/appendices/aws-setup.md b/docs/root/source/installation/node-setup/aws-setup.md similarity index 96% rename from docs/server/source/appendices/aws-setup.md rename to docs/root/source/installation/node-setup/aws-setup.md index c161507f..2ae61172 100644 --- a/docs/server/source/appendices/aws-setup.md +++ b/docs/root/source/installation/node-setup/aws-setup.md @@ -48,7 +48,7 @@ This writes two files: `~/.aws/credentials` and `~/.aws/config`. AWS tools and p Eventually, you'll have one or more instances (virtual machines) running on AWS and you'll want to SSH to them. To do that, you need a public/private key pair. The public key will be sent to AWS, and you can tell AWS to put it in any instances you provision there. You'll keep the private key on your local workstation. -See the [page about how to generate a key pair for SSH](generate-key-pair-for-ssh). +See the appendix [page about how to generate a key pair for SSH](../appendices/generate-key-pair-for-ssh). ## Send the Public Key to AWS diff --git a/docs/server/source/server-reference/bigchaindb-cli.md b/docs/root/source/installation/node-setup/bigchaindb-cli.md similarity index 100% rename from docs/server/source/server-reference/bigchaindb-cli.md rename to docs/root/source/installation/node-setup/bigchaindb-cli.md diff --git a/docs/root/source/installation/node-setup/bigchaindb-node-ansible.md b/docs/root/source/installation/node-setup/bigchaindb-node-ansible.md new file mode 100644 index 00000000..c28421f5 --- /dev/null +++ b/docs/root/source/installation/node-setup/bigchaindb-node-ansible.md @@ -0,0 +1,7 @@ +# Setting up a network of nodes with the Ansible script + +You can find one of the installation methods with Ansible on GitHub at: + +[Ansible script](https://github.com/bigchaindb/bigchaindb-node-ansible) + +It allows to install BigchainDB, MongoDB, Tendermint, and python, and then connect nodes into a network. Current tested machine is Ubuntu 18.04. \ No newline at end of file diff --git a/docs/server/source/server-reference/configuration.md b/docs/root/source/installation/node-setup/configuration.md similarity index 98% rename from docs/server/source/server-reference/configuration.md rename to docs/root/source/installation/node-setup/configuration.md index 7bb5959a..68189084 100644 --- a/docs/server/source/server-reference/configuration.md +++ b/docs/root/source/installation/node-setup/configuration.md @@ -109,7 +109,7 @@ If (no environment variables were set and there's no local config file), or you ## server.* `server.bind`, `server.loglevel` and `server.workers` -are settings for the [Gunicorn HTTP server](http://gunicorn.org/), which is used to serve the [HTTP client-server API](../http-client-server-api). +are settings for the [Gunicorn HTTP server](http://gunicorn.org/), which is used to serve the [HTTP client-server API](../api/http-client-server-api). `server.bind` is where to bind the Gunicorn HTTP server socket. It's a string. It can be any valid value for [Gunicorn's bind setting](http://docs.gunicorn.org/en/stable/settings.html#bind). For example: @@ -166,7 +166,7 @@ export BIGCHAINDB_SERVER_WORKERS=5 These settings are for the [aiohttp server](https://aiohttp.readthedocs.io/en/stable/index.html), which is used to serve the -[WebSocket Event Stream API](../events/websocket-event-stream-api). +[WebSocket Event Stream API](../api/websocket-event-stream-api). `wsserver.scheme` should be either `"ws"` or `"wss"` (but setting it to `"wss"` does *not* enable SSL/TLS). `wsserver.host` is where to bind the aiohttp server socket and diff --git a/docs/server/source/simple-deployment-template/deploy-a-machine.md b/docs/root/source/installation/node-setup/deploy-a-machine.md similarity index 88% rename from docs/server/source/simple-deployment-template/deploy-a-machine.md rename to docs/root/source/installation/node-setup/deploy-a-machine.md index 95593443..3e35eb96 100644 --- a/docs/server/source/simple-deployment-template/deploy-a-machine.md +++ b/docs/root/source/installation/node-setup/deploy-a-machine.md @@ -8,7 +8,8 @@ Code is Apache-2.0 and docs are CC-BY-4.0 # Deploy a Machine for Your BigchainDB Node The first step is to deploy a machine for your BigchainDB node. -It might be a virtual machine (VM) or a real machine. +It might be a virtual machine (VM) or a real machine, for example, +an EC2 on AWS or a droplet on Digital Ocean. If you follow this simple deployment template, all your node's software will run on that one machine. @@ -55,13 +56,6 @@ sudo apt update sudo apt full-upgrade ``` -## Node Security - -If you're going to use your node in production, -then you should take additional steps to secure it. -We don't cover that here; there are many books and websites -about securing Linux machines. - ## DNS Setup * Register a domain name for your BigchainDB node, such as `example.com` diff --git a/docs/root/source/installation/node-setup/index.rst b/docs/root/source/installation/node-setup/index.rst new file mode 100644 index 00000000..74bc4b4b --- /dev/null +++ b/docs/root/source/installation/node-setup/index.rst @@ -0,0 +1,25 @@ + +.. Copyright © 2020 Interplanetary Database Association e.V., + BigchainDB and IPDB software contributors. + SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) + Code is Apache-2.0 and docs are CC-BY-4.0 + +Node setup +========== + +You can use the all-in-one docker solution, or install Tendermint, MongoDB, and BigchainDB step by step. For more advanced users and for development, the second option is recommended. + +.. toctree:: + :maxdepth: 1 + + deploy-a-machine + aws-setup + all-in-one-bigchaindb + bigchaindb-node-ansible + set-up-node-software + set-up-nginx + configuration + bigchaindb-cli + troubleshooting + production-node/index + release-notes diff --git a/docs/server/source/production-nodes/index.rst b/docs/root/source/installation/node-setup/production-node/index.rst similarity index 100% rename from docs/server/source/production-nodes/index.rst rename to docs/root/source/installation/node-setup/production-node/index.rst diff --git a/docs/server/source/production-nodes/node-assumptions.md b/docs/root/source/installation/node-setup/production-node/node-assumptions.md similarity index 54% rename from docs/server/source/production-nodes/node-assumptions.md rename to docs/root/source/installation/node-setup/production-node/node-assumptions.md index 052d1735..15133b64 100644 --- a/docs/server/source/production-nodes/node-assumptions.md +++ b/docs/root/source/installation/node-setup/production-node/node-assumptions.md @@ -10,7 +10,14 @@ Code is Apache-2.0 and docs are CC-BY-4.0 Be sure you know the key BigchainDB terminology: * [BigchainDB node, BigchainDB network and BigchainDB consortium](https://docs.bigchaindb.com/en/latest/terminology.html) -* [dev/test node, bare-bones node and production node](../introduction) + +Note that there are a few kinds of nodes: + +- A **dev/test node** is a node created by a developer working on BigchainDB Server, e.g. for testing new or changed code. A dev/test node is typically run on the developer's local machine. + +- A **bare-bones node** is a node deployed in the cloud, either as part of a testing network or as a starting point before upgrading the node to be production-ready. + +- A **production node** is a node that is part of a consortium's BigchainDB network. A production node has the most components and requirements. We make some assumptions about production nodes: diff --git a/docs/server/source/production-nodes/node-components.md b/docs/root/source/installation/node-setup/production-node/node-components.md similarity index 92% rename from docs/server/source/production-nodes/node-components.md rename to docs/root/source/installation/node-setup/production-node/node-components.md index c39ab29b..c1f5dd31 100644 --- a/docs/server/source/production-nodes/node-components.md +++ b/docs/root/source/installation/node-setup/production-node/node-components.md @@ -27,4 +27,4 @@ It could also include several other components, including: The relationship between the main components is illustrated below. -![Components of a production node](../_static/Node-components.png) +![Components of a production node](../../_static/Node-components.png) diff --git a/docs/server/source/production-nodes/node-requirements.md b/docs/root/source/installation/node-setup/production-node/node-requirements.md similarity index 100% rename from docs/server/source/production-nodes/node-requirements.md rename to docs/root/source/installation/node-setup/production-node/node-requirements.md diff --git a/docs/server/source/production-nodes/node-security-and-privacy.md b/docs/root/source/installation/node-setup/production-node/node-security-and-privacy.md similarity index 94% rename from docs/server/source/production-nodes/node-security-and-privacy.md rename to docs/root/source/installation/node-setup/production-node/node-security-and-privacy.md index d2df5c97..155fb778 100644 --- a/docs/server/source/production-nodes/node-security-and-privacy.md +++ b/docs/root/source/installation/node-setup/production-node/node-security-and-privacy.md @@ -15,4 +15,4 @@ Here are some references about how to secure an Ubuntu 18.04 server: Also, here are some recommendations a node operator can follow to enhance the privacy of the data coming to, stored on, and leaving their node: - Ensure that all data stored on a node is encrypted at rest, e.g. using full disk encryption. This can be provided as a service by the operating system, transparently to BigchainDB, MongoDB and Tendermint. -- Ensure that all data is encrypted in transit, i.e. enforce using HTTPS for the HTTP API and the Websocket API. This can be done using NGINX or similar, as we do with the BigchainDB Testnet. +- Ensure that all data is encrypted in transit, i.e. enforce using HTTPS for the HTTP API and the Websocket API. This can be done using NGINX or similar, as we do with the IPDB Testnet. diff --git a/docs/server/source/production-nodes/reverse-proxy-notes.md b/docs/root/source/installation/node-setup/production-node/reverse-proxy-notes.md similarity index 100% rename from docs/server/source/production-nodes/reverse-proxy-notes.md rename to docs/root/source/installation/node-setup/production-node/reverse-proxy-notes.md diff --git a/docs/server/source/release-notes.md b/docs/root/source/installation/node-setup/release-notes.md similarity index 100% rename from docs/server/source/release-notes.md rename to docs/root/source/installation/node-setup/release-notes.md diff --git a/docs/server/source/simple-deployment-template/set-up-nginx.md b/docs/root/source/installation/node-setup/set-up-nginx.md similarity index 100% rename from docs/server/source/simple-deployment-template/set-up-nginx.md rename to docs/root/source/installation/node-setup/set-up-nginx.md diff --git a/docs/server/source/simple-deployment-template/set-up-node-software.md b/docs/root/source/installation/node-setup/set-up-node-software.md similarity index 100% rename from docs/server/source/simple-deployment-template/set-up-node-software.md rename to docs/root/source/installation/node-setup/set-up-node-software.md diff --git a/docs/server/source/simple-deployment-template/tips.md b/docs/root/source/installation/node-setup/troubleshooting.md similarity index 71% rename from docs/server/source/simple-deployment-template/tips.md rename to docs/root/source/installation/node-setup/troubleshooting.md index 7c78c24e..2d347b49 100644 --- a/docs/server/source/simple-deployment-template/tips.md +++ b/docs/root/source/installation/node-setup/troubleshooting.md @@ -1,10 +1,37 @@ -# Tips +# Troubleshooting + +## General Tips + +- Check the BigchainDB, Tendermint and MongoDB logs. + For help with that, see the page about [Logging and Log Rotation](../appendices/log-rotation). +- Try Googling the error message. ## Tendermint Tips * [Configure Tendermint to create no empty blocks](https://tendermint.com/docs/tendermint-core/using-tendermint.html#no-empty-blocks). * Store the Tendermint data on a fast drive. You can do that by changing [the location of TMHOME](https://tendermint.com/docs/tendermint-core/using-tendermint.html#directory-root) to be on the fast drive. +See the [Tendermint tips in the vrde/notes repository](https://github.com/vrde/notes/tree/master/tendermint). + +## Resolving Tendermint Connectivity Problems + +To check which nodes your node is connected to (via Tendermint protocols), do: + +```text +# if you don't have jq installed, then install it +sudo apt install jq +# then do +curl -s localhost:26657/net_info | jq ".result.peers[].node_info | {id, listen_addr, moniker}" +``` + +Note: Tendermint has other endpoints besides `/net_info`: see [the Tendermint RPC docs](https://tendermint.github.io/slate/?shell#introduction). + +If you're running your network inside a [private network](https://en.wikipedia.org/wiki/Private_network), e.g. with IP addresses of the form 192.168.x.y, then you may have to change the following setting in `config.toml`: + +```text +addr_book_strict = false +``` + ## Refreshing Your Node If you want to refresh your node back to a fresh empty state, then your best bet is to terminate it and deploy a new machine, but if that's not an option, then you can: @@ -59,6 +86,10 @@ If you started BigchainDB in the foreground, a `Ctrl + C` or `Ctrl + Z` would sh One member can make a proposal to call an election to add a validator, remove a validator, or change the voting power of a validator. They then share the election/proposal ID with all the other members. Once more than 2/3 of the voting power votes yes, the proposed change comes into effect. The commands to create a new election/proposal, to approve an election/proposal, and to get the current status of an election/proposal can be found in the documentation about the [bigchaindb election](../server-reference/bigchaindb-cli#bigchaindb-election) subcommands. -## Logging and Log Rotation +## Logging -See the page in the Appendices about [logging and log rotation](../appendices/log-rotation). \ No newline at end of file +See the page in the Appendices about [logging and log rotation](../appendices/log-rotation). + +## Other Problems + +If you're stuck, maybe [file a new issue on GitHub](https://github.com/bigchaindb/bigchaindb/issues/new). If your problem occurs often enough, we'll write about it here. \ No newline at end of file diff --git a/docs/server/source/quickstart.md b/docs/root/source/installation/quickstart.md similarity index 63% rename from docs/server/source/quickstart.md rename to docs/root/source/installation/quickstart.md index 24091f5c..2e756d0c 100644 --- a/docs/server/source/quickstart.md +++ b/docs/root/source/installation/quickstart.md @@ -5,7 +5,27 @@ SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 ---> -# Quickstart + +# Introduction + +This is the documentation for BigchainDB Server, or in other words, node - +the BigchainDB software that is on servers (but not on clients). + +## Setup Instructions for Various Cases + +- Quickstart link below +- [Set up a local BigchainDB node for development, experimenting and testing](node-setup/index) +- [Set up and run a BigchainDB network](network-setup/index) + +## Develop an App Test + +To develop an app that talks to a BigchainDB network, you'll want a test network to test it against. You have a few options: + +1. The IPDB Test Network (or "Testnet") is a free-to-use, publicly-available test network that you can test against. It is available at [IPDB testnet](https://test.ipdb.io/). +1. You could also run a BigchainDB node on you local machine. One way is to use this node setup guide with a one-node "network" by using the all-in-one docker solution, or manual installation and configuration of the components. Another way is to use one of the deployment methods listed in the [network setup guide](network-setup/index) or in the [the docs about contributing to BigchainDB](../contributing/index). + + +## (WIP) Quickstart