Mirroristas/planetmint
2
0
Fork 0
mirror of https://github.com/planetmint/planetmint.git synced 2026-02-25 20:49:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial Migration

Browse Source
This commit is contained in:
Sangat Das
2022-01-13 16:29:35 +00:00
parent 3ad513ed14
commit ed1d4b82ad
454 changed files with 42542 additions and 723 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/root/source/contributing/dev-setup-coding-and-contribution-process/index.rst Normal file
View File

@@ -0,0 +1,17 @@
.. Copyright © 2020 Interplanetary Database Association e.V.,
Planetmint 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
Developer Setup, Coding & Contribution Process
==============================================
.. toctree::
:maxdepth: 2
write-code
run-node-with-docker-compose
run-node-as-processes
run-dev-network-stack
run-dev-network-ansible

170
docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-ansible.md Normal file
View File

@@ -0,0 +1,170 @@
<!---
Copyright © 2020 Interplanetary Database Association e.V.,
Planetmint 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
--->
# Run a Planetmint network with Ansible
**NOT for Production Use**
You can use the following instructions to deploy a single or multi node
Planetmint network for dev/test using Ansible. Ansible will configure the Planetmint node(s).
Currently, this workflow is only supported for the following distributions:
- Ubuntu >= 16.04
- CentOS >= 7
- Fedora >= 24
- MacOSX
## Minimum Requirements
Minimum resource requirements for a single node Planetmint dev setup. **The more the better**:
- Memory >= 512MB
- VCPUs >= 1
## Clone the Planetmint repository
```text
$ git clone https://github.com/bigchaindb/bigchaindb.git
```
## Install dependencies
- [Ansible](http://docs.ansible.com/ansible/latest/intro_installation.html)
You can also install `ansible` and other dependencies, if any, using the `boostrap.sh` script
inside the Planetmint repository.
Navigate to `bigchaindb/pkg/scripts` and run the `bootstrap.sh` script to install the dependencies
for your OS. The script also checks if the OS you are running is compatible with the
supported versions.
**Note**: `bootstrap.sh` only supports Ubuntu >= 16.04, CentOS >= 7 and Fedora >=24 and MacOSX.
```text
$ cd bigchaindb/pkg/scripts/
$ bash bootstrap.sh --operation install
```
### Planetmint Setup Configuration(s)
#### Local Setup
You can run the Ansible playbook `bigchaindb-start.yml` on your local dev machine and set up the Planetmint node where
Planetmint can be run as a process or inside a Docker container(s) depending on your configuration.
Before, running the playbook locally, you need to update the `hosts` and `stack-config.yml` configuration, which will notify Ansible that we need to run the play locally.
##### Update Hosts
Navigate to `bigchaindb/pkg/configuration/hosts` inside the Planetmint repository.
```text
$ cd bigchaindb/pkg/configuration/hosts
```
Edit `all` configuration file:
```text
# Delete any existing configuration in this file and insert
# Hostname of dev machine
<HOSTNAME> ansible_connection=local
```
##### Update Configuration
Navigate to `bigchaindb/pkg/configuration/vars` inside the Planetmint repository.
```text
$ cd bigchaindb/pkg/configuration/vars/stack-config.yml
```
Edit `bdb-config.yml` configuration file as per your requirements, sample configuration file(s):
```text
---
stack_type: "docker"
stack_size: "4"
OR
---
stack_type: "local"
stack_type: "1"
```
### Planetmint Setup
Now, You can safely run the `bigchaindb-start.yml` playbook and everything will be taken care of by `Ansible`. To run the playbook please navigate to the `bigchaindb/pkg/configuration` directory inside the Planetmint repository and run the `bigchaindb-start.yml` playbook.
```text
$ cd bigchaindb/pkg/configuration/
$ ansible-playbook bigchaindb-start.yml -i hosts/all --extra-vars "operation=start home_path=$(pwd)"
```
After successful execution of the playbook, you can verify that Planetmint docker(s)/process(es) is(are) running.
Verify Planetmint process(es):
```text
$ ps -ef | grep bigchaindb
```
OR
Verify Planetmint Docker(s):
```text
$ docker ps | grep bigchaindb
```
You can now send transactions and verify the functionality of your Planetmint node.
See the [Planetmint Python Driver documentation](https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html)
for details on how to use it.
**Note**: The `bdb_root_url` can be be one of the following:
```text
# Planetmint is running as a process
bdb_root_url = http://<HOST-IP>:9984
OR
# Planetmint is running inside a docker container
bdb_root_url = http://<HOST-IP>:<DOCKER-PUBLISHED-PORT>
```
**Note**: Planetmint has [other drivers as well](http://docs.bigchaindb.com/projects/server/en/latest/drivers-clients/index.html).
### Experimental: Running Ansible a Remote Dev/Host
#### Remote Setup
You can also run the Ansible playbook `bigchaindb-start.yml` on remote machine(s) and set up the Planetmint node where
Planetmint can run as a process or inside a Docker container(s) depending on your configuration.
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 Remote Hosts
Navigate to `bigchaindb/pkg/configuration/hosts` inside the Planetmint repository.
```text
$ cd bigchaindb/pkg/configuration/hosts
```
Edit `all` configuration file:
```text
# Delete any existing configuration in this file and insert
<Remote_Host_IP/Hostname> ansible_ssh_user=<USERNAME> ansible_sudo_pass=<PASSWORD>
```
**Note**: You can add multiple hosts to the `all` configuration file. Non-root user with sudo enabled password is needed because ansible will run some tasks that require those permissions.
**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 Remote Configuration
Navigate to `bigchaindb/pkg/configuration/vars` inside the Planetmint repository.
```text
$ cd bigchaindb/pkg/configuration/vars/stack-config.yml
```
Edit `stack-config.yml` configuration file as per your requirements, sample configuration file(s):
```text
---
stack_type: "docker"
stack_size: "4"
OR
---
stack_type: "local"
stack_type: "1"
```
After, the configuration of remote hosts, [run the Ansible playbook and verify your deployment](#bigchaindb-setup-ansible).

324
docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-dev-network-stack.md Normal file
View File

@@ -0,0 +1,324 @@
<!---
Copyright © 2020 Interplanetary Database Association e.V.,
Planetmint 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
--->
# Run a Planetmint network
**NOT for Production Use**
You can use the following instructions to deploy a single or multi node
Planetmint network for dev/test using the extensible `stack` script(s).
Currently, this workflow is only supported for the following Operating systems:
- Ubuntu >= 16.04
- CentOS >= 7
- Fedora >= 24
- MacOSX
## Machine Minimum Requirements
Minimum resource requirements for a single node Planetmint dev setup. **The more the better**:
- Memory >= 512MB
- VCPUs >= 1
## Download the scripts
> **Note**: If you're working on Planetmint Server code, on a branch based on
> recent code, then you already have local recent versions of *stack.sh* and
> *unstack.sh* in your bigchaindb/pkg/scripts/ directory. Otherwise you can
> get them using:
```text
$ export GIT_BRANCH=master
$ curl -fOL https://raw.githubusercontent.com/bigchaindb/bigchaindb/${GIT_BRANCH}/pkg/scripts/stack.sh
# Optional
$ curl -fOL https://raw.githubusercontent.com/bigchaindb/bigchaindb/${GIT_BRANCH}/pkg/scripts/unstack.sh
```
## Quick Start
If you run `stack.sh` out of the box i.e. without any configuration changes, you will be able to deploy a 4 node
Planetmint network with Docker containers, created from `master` branch of `bigchaindb/bigchaindb` repo and Tendermint version `0.22.8`.
**Note**: Run `stack.sh` with either root or non-root user with sudo enabled.
```text
$ bash stack.sh
...Logs..
.........
.........
Finished stacking!
```
## Configure the Planetmint network
The `stack.sh` script has multiple deployment methods and parameters and they can be explored using: `bash stack.sh -h`
```text
$ bash stack.sh -h
Usage: $ bash stack.sh [-h]
Deploys the Planetmint network.
ENV[STACK_SIZE]
Set STACK_SIZE environment variable to the size of the network you desire.
Network mimics a production network environment with single or multiple BDB
nodes. (default: 4).
ENV[STACK_TYPE]
Set STACK_TYPE environment variable to the type of deployment you desire.
You can set it one of the following: ["docker", "local", "cloud"].
(default: docker)
ENV[STACK_TYPE_PROVIDER]
Set only when STACK_TYPE="cloud". Only "azure" is supported.
(default: )
ENV[STACK_VM_MEMORY]
(Optional) Set only when STACK_TYPE="local". This sets the memory
of the instance(s) spawned. (default: 2048)
ENV[STACK_VM_CPUS]
(Optional) Set only when STACK_TYPE="local". This sets the number of VCPUs
of the instance(s) spawned. (default: 2)
ENV[STACK_BOX_NAME]
(Optional) Set only when STACK_TYPE="local". This sets the box Vagrant box name
of the instance(s) spawned. (default: ubuntu/xenial64)
ENV[STACK_REPO]
(Optional) To configure bigchaindb repo to use, set STACK_REPO environment
variable. (default: bigchaindb/bigchaindb)
ENV[STACK_BRANCH]
(Optional) To configure bigchaindb repo branch to use set STACK_BRANCH environment
variable. (default: master)
ENV[TM_VERSION]
(Optional) Tendermint version to use for the setup. (default: 0.22.8)
ENV[MONGO_VERSION]
(Optional) MongoDB version to use with the setup. (default: 3.6)
ENV[AZURE_CLIENT_ID]
Only required when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure". Steps to generate:
https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application
ENV[AZURE_TENANT_ID]
Only required when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure". Steps to generate:
https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application
ENV[AZURE_SUBSCRIPTION_ID]
Only required when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure". Steps to generate:
https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application
ENV[AZURE_CLIENT_SECRET]
Only required when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure". Steps to generate:
https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application
ENV[AZURE_REGION]
(Optional) Only applicable, when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure".
Azure region for the Planetmint instance. Get list of regions using Azure CLI.
e.g. az account list-locations. (default: westeurope)
ENV[AZURE_IMAGE_URN]
(Optional) Only applicable, when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure".
Azure image to use. Get list of available images using Azure CLI.
e.g. az vm image list --output table. (default: Canonical:UbuntuServer:16.04-LTS:latest)
ENV[AZURE_RESOURCE_GROUP]
(Optional) Only applicable, when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure".
Name of Azure resource group for the instance.
(default: bdb-vagrant-rg-2018-05-30)
ENV[AZURE_DNS_PREFIX]
(Optional) Only applicable, when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure".
DNS Prefix of the instance. (default: bdb-instance-2018-05-30)
ENV[AZURE_ADMIN_USERNAME]
(Optional) Only applicable, when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure".
Admin username of the the instance. (default: vagrant)
ENV[AZURE_VM_SIZE]
(Optional) Only applicable, when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure".
Azure VM size. (default: Standard_D2_v2)
ENV[SSH_PRIVATE_KEY_PATH]
Only required when STACK_TYPE="cloud" and STACK_TYPE_PROVIDER="azure". Absolute path of
SSH keypair required to log into the Azure instance.
-h
Show this help and exit.
```
The parameter that differentiates between the deployment type is `STACK_TYPE` which currently, supports
an opinionated deployment of Planetmint on `docker`, `local` and `cloud`.
### STACK_TYPE: docker
This configuration deploys a docker based Planetmint 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: docker
Deploy a 4 node docker based Planetmint network on your host.
```text
#Optional, since 4 is the default size.
$ export STACK_SIZE=4
#Optional, since docker is the default type.
$ export STACK_TYPE=docker
#Optional, repo to use for the network deployment
# Default: bigchaindb/bigchaindb
$ export STACK_REPO=bigchaindb/bigchaindb
#Optional, codebase to use for the network deployment
# Default: master
$ export STACK_BRANCH=master
#Optional, since 0.22.8 is the default tendermint version.
$ export TM_VERSION=0.22.8
#Optional, since 3.6 is the default MongoDB version.
$ export MONGO_VERSION=3.6
$ bash stack.sh
```
**Note**: For MacOSX users, the script will not install `Docker for Mac`, it only detects if `docker` is installed on the system, if not make sure to install [Docker for Mac](https://docs.docker.com/docker-for-mac/). Also make sure Docker API Version > 1.25. To check Docker API Version:
`docker version --format '{{.Server.APIVersion}}'`
### STACK_TYPE: local
This configuration deploys a VM based Planetmint network on your host/dev. All the services are running as processes on the VMs. For `local` deployments the following dependencies must be installed i.e.
- Vagrant
- Vagrant plugins.
- vagrant-cachier
- vagrant-vbguest
- vagrant-hosts
- vagrant-azure
- `vagrant plugin install vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure`
- [Virtualbox](https://www.virtualbox.org/wiki/Downloads)
#### Example: VM
Deploy a 4 node VM based Planetmint network.
```text
$ export STACK_TYPE=local
# Optional, since 4 is the default size.
$ export STACK_SIZE=4
# Optional, default is 2048
$ export STACK_VM_MEMORY=2048
#Optional, default is 1
$ export STACK_VM_CPUS=1
#Optional, default is ubuntu/xenial64. Supported/tested images: bento/centos-7, fedora/25-cloud-base
$ export STACK_BOX_NAME=ubuntu/xenial64
#Optional, repo to use for the network deployment
# Default: bigchaindb/bigchaindb
$ export STACK_REPO=bigchaindb/bigchaindb
#Optional, codebase to use for the network deployment
# Default: master
$ export STACK_BRANCH=master
#Optional, since 0.22.8 is the default tendermint version
$ export TM_VERSION=0.22.8
#Optional, since 3.6 is the default MongoDB version.
$ export MONGO_VERSION=3.6
$ bash stack.sh
```
### STACK_TYPE: cloud
This configuration deploys a docker based Planetmint network on a cloud instance. Currently, only Azure is supported.
For `cloud` deployments the following dependencies must be installed i.e.
- Vagrant
- Vagrant plugins.
- vagrant-cachier
- vagrant-vbguest
- vagrant-hosts
- vagrant-azure
- `vagrant plugin install vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure`
#### Example: stack
Deploy a 4 node docker based Planetmint network on an Azure instance.
- [Create an Azure Active Directory(AAD) Application](https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application)
- Generate or specify an SSH keypair to login to the Azure instance.
- **Example:**
```text
$ ssh-keygen -t rsa -C "<name>" -f /path/to/key/<name>
```
- Configure parameters for `stack.sh`
```text
# After creating the AAD application with access to Azure Resource
# Group Manager for your subscription, it will return a JSON object
$ export AZURE_CLIENT_ID=<value from azure.appId>
$ export AZURE_TENANT_ID=<value from azure.tenant>
# Can be retrieved via
# az account list --query "[?isDefault].id" -o tsv
$ export AZURE_SUBSCRIPTION_ID=<your Azure subscription ID>
$ export AZURE_CLIENT_SECRET=<value from azure.password>
$ export STACK_TYPE=cloud
# Currently on azure is supported
$ export STACK_TYPE_PROVIDER=azure
$ export SSH_PRIVATE_KEY_PATH=</path/to/private/key>
# Optional, Azure region of the instance. Default: westeurope
$ export AZURE_REGION=westeurope
# Optional, Azure image urn of the instance. Default: Canonical:UbuntuServer:16.04-LTS:latest
$ export AZURE_IMAGE_URN=Canonical:UbuntuServer:16.04-LTS:latest
# Optional, Azure resource group. Default: bdb-vagrant-rg-yyyy-mm-dd(current date)
$ export AZURE_RESOURCE_GROUP=bdb-vagrant-rg-2018-01-01
# Optional, DNS prefix of the Azure instance. Default: bdb-instance-yyyy-mm-dd(current date)
$ export AZURE_DNS_PREFIX=bdb-instance-2018-01-01
# Optional, Admin username of the Azure instance. Default: vagrant
$ export AZURE_ADMIN_USERNAME=vagrant
# Optional, Azure instance size. Default: Standard_D2_v2
$ export AZURE_VM_SIZE=Standard_D2_v2
$ bash stack.sh
```
## Delete/Unstack a Planetmint network
Export all the variables exported for the corresponding `stack.sh` script and
run `unstack.sh` to delete/remove/unstack the Planetmint network/stack.
```text
$ bash unstack.sh
OR
# -s implies soft unstack. i.e. Only applicable for local and cloud based
# networks. Only deletes/stops the docker(s)/process(es) and does not
# delete the instances created via Vagrant or on Cloud. Default: hard
$ bash unstack.sh -s
```

138
docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-node-as-processes.md Normal file
View File

@@ -0,0 +1,138 @@
<!---
Copyright © 2020 Interplanetary Database Association e.V.,
Planetmint 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
--->
# Notes on Running a Local Dev Node as Processes
The following doc describes how to run a local node for developing Planetmint Tendermint version.
There are two crucial dependencies required to start a local node:
- MongoDB
- Tendermint
and of course you also need to install Planetmint Sever from the local code you just developed.
## Install and Run MongoDB
MongoDB can be easily installed, just refer to their [installation documentation](https://docs.mongodb.com/manual/installation/) for your distro.
We know MongoDB 3.4 and 3.6 work with Planetmint.
After the installation of MongoDB is complete, run MongoDB using `sudo mongod`
## Install and Run Tendermint
### Installing a Tendermint Executable
The version of Planetmint Server described in these docs only works well with Tendermint 0.31.5 (not a higher version number). Install that:
```bash
$ sudo apt install -y unzip
$ wget https://github.com/tendermint/tendermint/releases/download/v0.31.5/tendermint_v0.31.5_linux_amd64.zip
$ unzip tendermint_v0.31.5_linux_amd64.zip
$ rm tendermint_v0.31.5_linux_amd64.zip
$ sudo mv tendermint /usr/local/bin
```
### Installing Tendermint Using Docker
Tendermint can be run directly using the docker image. Refer [here](https://hub.docker.com/r/tendermint/tendermint/) for more details.
### Installing Tendermint from Source
Before we can begin installing Tendermint one should ensure that the Golang is installed on system and `$GOPATH` should be set in the `.bashrc` or `.zshrc`. An example setup is shown below
```bash
$ echo $GOPATH
/home/user/Documents/go
$ go -h
Go is a tool for managing Go source code.
Usage:
go command [arguments]
The commands are:
build compile packages and dependencies
clean remove object files
...
```
- We can drop `GOPATH` in `PATH` so that installed Golang packages are directly available in the shell. To do that add the following to your `.bashrc`
```bash
export PATH=${PATH}:${GOPATH}/bin
```
Follow [the Tendermint docs](https://tendermint.com/docs/introduction/install.html#from-source) to install Tendermint from source.
If the installation is successful then Tendermint is installed at `$GOPATH/bin`. To ensure Tendermint's installed fine execute the following command,
```bash
$ tendermint -h
Tendermint Core (BFT Consensus) in Go
Usage:
tendermint [command]
Available Commands:
gen_validator Generate new validator keypair
help Help about any command
init Initialize Tendermint
...
```
### Running Tendermint
- We can initialize and run tendermint as follows,
```bash
$ tendermint init
...
$ tendermint node --consensus.create_empty_blocks=false
```
The argument `--consensus.create_empty_blocks=false` specifies that Tendermint should not commit empty blocks.
- To reset all the data stored in Tendermint execute the following command,
```bash
$ tendermint unsafe_reset_all
```
## Install Planetmint
To install Planetmint from source (for dev), clone the repo and execute the following command, (it is better that you create a virtual env for this)
```bash
$ git clone https://github.com/bigchaindb/bigchaindb.git
$ cd bigchaindb
$ pip install -e .[dev] # or pip install -e '.[dev]' # for zsh
```
## Running All Tests
To execute tests when developing a feature or fixing a bug one could use the following command,
```bash
$ pytest -v
```
NOTE: MongoDB and Tendermint should be running as discussed above.
One could mark a specific test and execute the same by appending `-m my_mark` to the above command.
Although the above should prove sufficient in most cases but in case tests are failing on Travis CI then the following command can be used to possibly replicate the failure locally,
```bash
$ docker-compose run --rm --no-deps bdb pytest -v --cov=bigchaindb
```
NOTE: before executing the above command the user must ensure that they reset the Tendermint container by executing `tendermint usafe_reset_all` command in the Tendermint container.

108
docs/root/source/contributing/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md Normal file
View File

@@ -0,0 +1,108 @@
<!---
Copyright © 2020 Interplanetary Database Association e.V.,
Planetmint 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
--->
# Notes on Running a Local Dev Node with Docker Compose
## Setting up a single node development environment with ``docker-compose``
### Using the Planetmint 2.0 developer toolbox
We grouped all useful commands under a simple `Makefile`.
Run a Planetmint node in the foreground:
```bash
$ make run
```
There are also other commands you can execute:
- `make start`: Run Planetmint from source and daemonize it (stop it with `make stop`).
- `make stop`: Stop Planetmint.
- `make logs`: Attach to the logs.
- `make test`: Run all unit and acceptance tests.
- `make test-unit-watch`: Run all tests and wait. Every time you change code, tests will be run again.
- `make cov`: Check code coverage and open the result in the browser.
- `make doc`: Generate HTML documentation and open it in the browser.
- `make clean`: Remove all build, test, coverage and Python artifacts.
- `make reset`: Stop and REMOVE all containers. WARNING: you will LOSE all data stored in Planetmint.
### Using `docker-compose` directly
The Planetmint `Makefile` is a wrapper around some `docker-compose` commands we use frequently. If you need a finer granularity to manage the containers, you can still use `docker-compose` directly. This part of the documentation explains how to do that.
```bash
$ docker-compose build bigchaindb
$ docker-compose up -d bdb
```
The above command will launch all 3 main required services/processes:
* ``mongodb``
* ``tendermint``
* ``bigchaindb``
To follow the logs of the ``tendermint`` service:
```bash
$ docker-compose logs -f tendermint
```
To follow the logs of the ``bigchaindb`` service:
```bash
$ docker-compose logs -f bigchaindb
```
To follow the logs of the ``mongodb`` service:
```bash
$ docker-compose logs -f mdb
```
Simple health check:
```bash
$ docker-compose up curl-client
```
Post and retrieve a transaction -- copy/paste a driver basic example of a
``CREATE`` transaction:
```bash
$ docker-compose -f docker-compose.yml run --rm bdb-driver ipython
```
**TODO**: A python script to post and retrieve a transaction(s).
### Running Tests
Run all the tests using:
```bash
$ docker-compose run --rm --no-deps bigchaindb pytest -v
```
Run tests from a file:
```bash
$ docker-compose run --rm --no-deps bigchaindb pytest /path/to/file -v
```
Run specific tests:
```bash
$ docker-compose run --rm --no-deps bigchaindb pytest /path/to/file -k "<test_name>" -v
```
### Building Docs
You can also develop and build the Planetmint docs using ``docker-compose``:
```bash
$ docker-compose build bdocs
$ 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)
OR http:/HOST_IP:33333.

157
docs/root/source/contributing/dev-setup-coding-and-contribution-process/write-code.rst Normal file
View File

@@ -0,0 +1,157 @@
.. Copyright © 2020 Interplanetary Database Association e.V.,
Planetmint 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
Write Code
==========
Know What You Want to Write Code to Do
--------------------------------------
Do you want to write code to resolve an open issue (bug)? Which one?
Do you want to implement a Planetmint Enhancement Proposal (PEP)? Which one?
You should know why you want to write code before you go any farther.
Refresh Yourself about the C4 Process
-------------------------------------
C4 is the Collective Code Construction Contract. It's quite short:
`re-reading it will only take a few minutes <https://github.com/bigchaindb/BEPs/tree/master/1>`_.
Set Up Your Local Machine. Here's How.
--------------------------------------
- Make sure you have Git installed.
- Get a text editor. Internally, we like:
- Vim
- PyCharm
- Visual Studio Code
- Atom
- GNU Emacs (Trent is crazy)
- GNU nano (Troy has lost his mind)
- If you plan to do JavaScript coding, get the latest JavaScript stuff (npm etc.).
- If you plan to do Python coding, get `the latest Python <https://www.python.org/downloads/>`_, and
get the latest ``pip``.
.. warning::
Don't use apt or apt-get to get the latest ``pip``. It won't work properly. Use ``get-pip.py``
from `the pip website <https://pip.pypa.io/en/stable/installing/>`_.
- Use the latest ``pip`` to get the latest ``virtualenv``:
.. code::
$ pip install virtualenv
- Create a Python Virttual Environment (virtualenv) for doing Planetmint Server development. There are many ways to do that. Google around and pick one.
An old-fashioned but fine way is:
.. code::
$ virtualenv -p $(which python3.6) NEW_ENV_NAME
$ . NEW_ENV_NAME/bin/activate
Be sure to use Python 3.6.x as the Python version for your virtualenv. The virtualenv creation process will actually get the
latest ``pip``, ``wheel`` and ``setuptools`` and put them inside the new virtualenv.
Before You Start Writing Code
-----------------------------
Read `BEP-24 <https://github.com/bigchaindb/BEPs/tree/master/24>`_
so you know what to do to ensure that your changes (i.e. your future pull request) can be merged.
It's easy and will save you some hassle later on.
Start Writing Code
------------------
Use the Git `Fork and Pull Request Workflow <https://github.com/susam/gitpr>`_. Tip: You could print that page for reference.
Your Python code should follow `our Python Style Guide <https://github.com/bigchaindb/bigchaindb/blob/master/PYTHON_STYLE_GUIDE.md>`_.
Similarly for JavaScript.
Make sure `pre-commit <https://pre-commit.com/>`_ actually checks commits. Do:
.. code::
$ pip install pre-commit # might not do anything if it is already installed, which is okay
$ pre-commit install
That will load the pre-commit settings in the file ``.pre-commit-config.yaml``. Now every time you do ``git commit <stuff>``, pre-commit
will run all those checks.
To install Planetmint Server from the local code, and to keep it up to date with the latest code in there, use:
.. code::
$ pip install -e .[dev]
The ``-e`` tells it to use the latest code. The ``.`` means use the current directory, which should be the one containing ``setup.py``.
The ``[dev]`` tells it to install some extra Python packages. Which ones? Open ``setup.py`` and look for ``dev`` in the ``extras_require`` section.
Remember to Write Tests
-----------------------
We like to test everything, if possible. Unit tests and also integration tests. We use the `pytest <https://docs.pytest.org/en/latest/>`_
framework to write Python tests. Read all about it.
Most tests are in the ``tests/`` folder. Take a look around.
Running a Local Node/Network for Dev and Test
---------------------------------------------
This is tricky and personal. Different people do it different ways. We documented some of those on separate pages:
- `Dev node setup and running all tests with Docker Compose <run-node-with-docker-compose.html>`_
- `Dev node setup and running all tests as processes <run-node-as-processes.html>`_
- `Dev network setup with stack.sh <run-dev-network-stack.html>`_
- `Dev network setup with Ansible <run-dev-network-ansible.html>`_
- More to come?
Create the PR on GitHub
-----------------------
Git push your branch to GitHub so as to create a pull request against the branch where the code you want to change *lives*.
Travis and Codecov will run and might complain. Look into the complaints and fix them before merging.
Travis gets its configuration and setup from the files:
- Some environment variables, if they are used. See https://docs.travis-ci.com/user/environment-variables/
- ``.travis.yml``
- ``tox.ini`` - What is tox? See `tox.readthedocs.io <https://tox.readthedocs.io/en/latest/>`_
- ``.ci/`` (as in Travis CI = Continuous Integration)
- ``travis-after-success.sh``
- ``travis-before-install.sh``
- ``travis-before-script.sh``
- ``travis-install.sh``
- ``travis_script.sh``
Read about the `Travis CI build lifecycle <https://docs.travis-ci.com/user/customizing-the-build/>`_ to understand when those scripts run and what they do.
You can have even more scripts!
Codecov gets its configuration from the file `codeocov.yaml <https://github.com/codecov/support/wiki/Codecov-Yaml>`_ which is also documented at
`docs.codecov.io <https://docs.codecov.io/v4.3.6/docs/codecov-yaml>`_. Codecov might also use ``setup.cfg``.
Merge!
------
Ideally, we like your PR and merge it right away. We don't want to keep you waiting.
If we want to make changes, we'll do them in a follow-up PR.