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

31 restructue documentation (#138)

Browse Source 
* removed korean documentation

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* removed CN and KOR readme

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* changed to the press theme

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* first changes

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* fixe H3 vs H1 issues

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* added missing png

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* added missing file

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* fixed warnings

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* moved documents

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* removed obsolete files

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* removed obsolete folder

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* removed obs. file

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* added some final changes

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>

* removed obs. reference

Signed-off-by: Jürgen Eckel <juergen@riddleandcode.com>
This commit is contained in:
Jürgen Eckel
2022-06-09 15:00:11 +02:00
committed by GitHub
parent fa2c8a5cc5
commit 4ffd8ca9df
117 changed files with 314 additions and 1139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/root/source/node-setup/all-in-one-planetmint.md Normal file
View File

@@ -0,0 +1,92 @@
<!---
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 Planetmint with all-in-one Docker
For those who like using Docker and wish to experiment with Planetmint in
non-production environments, we currently maintain a Planetmint all-in-one
Docker image and a
`Dockerfile-all-in-one` that can be used to build an image for `planetmint`.
This image contains all the services required for a Planetmint node i.e.
- Planetmint Server
- MongoDB
- Tendermint
**Note:** **NOT for Production Use:** *This is an single node opinionated image not well suited for a network deployment.*
*This image is to help quick deployment for early adopters, for a more standard approach please refer to one of our deployment guides:*
- [Planetmint developer setup guides](https://docs.planetmint.io/projects/contributing/en/latest/dev-setup-coding-and-contribution-process/index.html).
- [Planetmint with Kubernetes](http://docs.planetmint.io/projects/server/en/latest/k8s-deployment-template/index.html).
## Prerequisite(s)
- [Docker](https://docs.docker.com/engine/installation/)
## Pull and Run the Image from Docker Hub
With Docker installed, you can proceed as follows.
In a terminal shell, pull the latest version of the Planetmint all-in-one Docker image using:
```text
$ docker pull planetmint/planetmint:all-in-one
$ docker run \
--detach \
--name planetmint \
--publish 9984:9984 \
--publish 9985:9985 \
--publish 27017:27017 \
--publish 26657:26657 \
--volume $HOME/planetmint_docker/mongodb/data/db:/data/db \
--volume $HOME/planetmint_docker/mongodb/data/configdb:/data/configdb \
--volume $HOME/planetmint_docker/tendermint:/tendermint \
planetmint/planetmint:all-in-one
```
Let's analyze that command:
* `docker run` tells Docker to run some image
* `--detach` run the container in the background
* `publish 9984:9984` map the host port `9984` to the container port `9984`
(the Planetmint API server)
* `9985` Planetmint Websocket server
* `27017` Default port for MongoDB
* `26657` Tendermint RPC server
* `--volume "$HOME/planetmint_docker/mongodb:/data"` map the host directory
`$HOME/planetmint_docker/mongodb` to the container directory `/data`;
this allows us to have the data persisted on the host machine,
you can read more in the [official Docker
documentation](https://docs.docker.com/engine/tutorials/dockervolumes)
* `$HOME/planetmint_docker/tendermint:/tendermint` to persist Tendermint data.
* `planetmint/planetmint:all-in-one` the image to use. All the options after the container name are passed on to the entrypoint inside the container.
## Verify
```text
$ docker ps | grep planetmint
```
Send your first transaction using [Planetmint drivers](../connecting/drivers).
## Building Your Own Image
Assuming you have Docker installed, you would proceed as follows.
In a terminal shell:
```text
git clone git@github.com:planetmint/planetmint.git
cd planetmint/
```
Build the Docker image:
```text
docker build --file Dockerfile-all-in-one --tag <tag/name:latest> .
```
Now you can use your own image to run Planetmint all-in-one container.

65
docs/root/source/node-setup/aws-setup.md Normal file
View File

@@ -0,0 +1,65 @@
<!---
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
--->
# Basic AWS Setup
Before you can deploy anything on AWS, you must do a few things.
## Get an AWS Account
If you don't already have an AWS account, you can [sign up for one for free at aws.amazon.com](https://aws.amazon.com/).
## Install the AWS Command-Line Interface
To install the AWS Command-Line Interface (CLI), just do:
```text
pip install awscli
```
## Create an AWS Access Key
The next thing you'll need is AWS access keys (access key ID and secret access key). If you don't have those, see [the AWS documentation about access keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
You should also pick a default AWS region name (e.g. `eu-central-1`). The AWS documentation has [a list of them](http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region).
Once you've got your AWS access key, and you've picked a default AWS region name, go to a terminal session and enter:
```text
aws configure
```
and answer the four questions. For example:
```text
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: eu-central-1
Default output format [None]: [Press Enter]
```
This writes two files: `~/.aws/credentials` and `~/.aws/config`. AWS tools and packages look for those files.
## Generate an RSA Key Pair for SSH
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 appendix [page about how to generate a key pair for SSH](../appendices/generate-key-pair-for-ssh).
## Send the Public Key to AWS
To send the public key to AWS, use the AWS Command-Line Interface:
```text
aws ec2 import-key-pair \
--key-name "<key-name>" \
--public-key-material file://~/.ssh/<key-name>.pub
```
If you're curious why there's a `file://` in front of the path to the public key, see issue [aws/aws-cli#41 on GitHub](https://github.com/aws/aws-cli/issues/41).
If you want to verify that your key pair was imported by AWS, go to [the Amazon EC2 console](https://console.aws.amazon.com/ec2/v2/home), select the region you gave above when you did `aws configure` (e.g. eu-central-1), click on **Key Pairs** in the left sidebar, and check that `<key-name>` is listed.

398
docs/root/source/node-setup/configuration.md Normal file
View File

@@ -0,0 +1,398 @@
<!---
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
--->
# Configuration Settings
Every Planetmint Server configuration setting has two names: a config-file name and an environment variable name. For example, one of the settings has the config-file name `database.host` and the environment variable name `PLANETMINT_DATABASE_HOST`. Here are some more examples:
`database.port` ↔ `PLANETMINT_DATABASE_PORT`
`database.keyfile_passphrase` ↔ `PLANETMINT_DATABASE_KEYFILE_PASSPHRASE`
`server.bind` ↔ `PLANETMINT_SERVER_BIND`
The value of each setting is determined according to the following rules:
* If it's set by an environment variable, then use that value
* Otherwise, if it's set in a local config file, then use that value
* Otherwise, use the default value
The local config file is `$HOME/.planetmint` by default (a file which might not even exist), but you can tell Planetmint to use a different file by using the `-c` command-line option, e.g. `planetmint -c path/to/config_file.json start`
or using the `PLANETMINT_CONFIG_PATH` environment variable, e.g. `BIGHAINDB_CONFIG_PATH=.my_planetmint_config planetmint start`.
Note that the `-c` command line option will always take precedence if both the `PLANETMINT_CONFIG_PATH` and the `-c` command line option are used.
You can read the current default values in the file [planetmint/\_\_init\_\_.py](https://github.com/planetmint/planetmint/blob/master/planetmint/__init__.py). (The link is to the latest version.)
Running `planetmint -y configure localmongodb` will generate a local config file in `$HOME/.planetmint` with all the default values.
## database.*
The settings with names of the form `database.*` are for the backend database
(currently only MongoDB). They are:
* `database.backend` can only be `localmongodb`, currently.
* `database.host` is the hostname (FQDN) of the backend database.
* `database.port` is self-explanatory.
* `database.name` is a user-chosen name for the database inside MongoDB, e.g. `planetmint`.
* `database.connection_timeout` is the maximum number of milliseconds that Planetmint will wait before giving up on one attempt to connect to the backend database.
* `database.max_tries` is the maximum number of times that Planetmint will try to establish a connection with the backend database. If 0, then it will try forever.
* `database.replicaset` is the name of the MongoDB replica set. The default value is `null` because in Planetmint 2.0+, each Planetmint node has its own independent MongoDB database and no replica set is necessary. Replica set must already exist if this option is configured, Planetmint will not create it.
* `database.ssl` must be `true` or `false`. It tells Planetmint Server whether it should connect to MongoDB using TLS/SSL or not. The default value is `false`.
There are three ways for Planetmint Server to authenticate itself with MongoDB (or a specific MongoDB database): no authentication, username/password, and x.509 certificate authentication.
**No Authentication**
If you use all the default Planetmint configuration settings, then no authentication will be used.
**Username/Password Authentication**
To use username/password authentication, a MongoDB instance must already be running somewhere (maybe in another machine), it must already have a database for use by Planetmint (usually named `planetmint`, which is the default `database.name`), and that database must already have a "readWrite" user with associated username and password. To create such a user, login to your MongoDB instance as Admin and run the following commands:
```text
use <database.name>
db.createUser({user: "<database.login>", pwd: "<database.password>", roles: [{role: "readWrite", db: "<database.name>"}]})
```
* `database.login` is the user's username.
* `database.password` is the user's password, given in plaintext.
* `database.ca_cert`, `database.certfile`, `database.keyfile`, `database.crlfile`, and `database.keyfile_passphrase` are not used so they can have their default values.
**x.509 Certificate Authentication**
To use x.509 certificate authentication, a MongoDB instance must be running somewhere (maybe in another machine), it must already have a database for use by Planetmint (usually named `planetmint`, which is the default `database.name`), and that database must be set up to use x.509 authentication. See the MongoDB docs about how to do that.
* `database.login` is the user's username.
* `database.password` isn't used so the default value (`null`) is fine.
* `database.ca_cert`, `database.certfile`, `database.keyfile` and `database.crlfile` are the paths to the CA, signed certificate, private key and certificate revocation list files respectively.
* `database.keyfile_passphrase` is the private key decryption passphrase, specified in plaintext.
**Example using environment variables**
```text
export PLANETMINT_DATABASE_BACKEND=localmongodb
export PLANETMINT_DATABASE_HOST=localhost
export PLANETMINT_DATABASE_PORT=27017
export PLANETMINT_DATABASE_NAME=database8
export PLANETMINT_DATABASE_CONNECTION_TIMEOUT=5000
export PLANETMINT_DATABASE_MAX_TRIES=3
```
**Default values**
If (no environment variables were set and there's no local config file), or you used `planetmint -y configure localmongodb` to create a default local config file for a `localmongodb` backend, then the defaults will be:
```js
"database": {
"backend": "localmongodb",
"host": "localhost",
"port": 27017,
"name": "planetmint",
"connection_timeout": 5000,
"max_tries": 3,
"replicaset": null,
"login": null,
"password": null
"ssl": false,
"ca_cert": null,
"certfile": null,
"keyfile": null,
"crlfile": null,
"keyfile_passphrase": null,
}
```
## 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](../connecting/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:
* If you want to allow IPv4 connections from anyone, on port 9984, use `0.0.0.0:9984`
* If you want to allow IPv6 connections from anyone, on port 9984, use `[::]:9984`
In a production setting, we recommend you use Gunicorn behind a reverse proxy server such as NGINX. If Gunicorn and the reverse proxy are running on the same machine, then you can use `localhost:9984` (the default value), meaning Gunicorn will talk to the reverse proxy on port 9984. The reverse proxy could then be bound to port 80 (for HTTP) or port 443 (for HTTPS), so that external clients would connect using that port. For example:
[External clients]---(port 443)---[NGINX]---(port 9984)---[Gunicorn / Planetmint Server]
If Gunicorn and the reverse proxy are running on different machines, then `server.bind` should be `hostname:9984`, where hostname is the IP address or [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of the reverse proxy.
There's [more information about deploying behind a reverse proxy in the Gunicorn documentation](http://docs.gunicorn.org/en/stable/deploy.html). (They call it a proxy.)
`server.loglevel` sets the log level of Gunicorn's Error log outputs. See
[Gunicorn's documentation](http://docs.gunicorn.org/en/latest/settings.html#loglevel)
for more information.
`server.workers` is [the number of worker processes](http://docs.gunicorn.org/en/stable/settings.html#workers) for handling requests. If set to `None`, the value will be (2 × cpu_count + 1). Each worker process has a single thread. The HTTP server will be able to handle `server.workers` requests simultaneously.
**Example using environment variables**
```text
export PLANETMINT_SERVER_BIND=0.0.0.0:9984
export PLANETMINT_SERVER_LOGLEVEL=debug
export PLANETMINT_SERVER_WORKERS=5
```
**Example config file snippet**
```js
"server": {
"bind": "0.0.0.0:9984",
"loglevel": "debug",
"workers": 5,
}
```
**Default values (from a config file)**
```js
"server": {
"bind": "localhost:9984",
"loglevel": "info",
"workers": null,
}
```
## wsserver.*
### wsserver.scheme, wsserver.host and wsserver.port
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](../connecting/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
`wsserver.port` is the corresponding port.
If you want to allow connections from anyone, on port 9985,
set `wsserver.host` to 0.0.0.0 and `wsserver.port` to 9985.
**Example using environment variables**
```text
export PLANETMINT_WSSERVER_SCHEME=ws
export PLANETMINT_WSSERVER_HOST=0.0.0.0
export PLANETMINT_WSSERVER_PORT=9985
```
**Example config file snippet**
```js
"wsserver": {
"scheme": "wss",
"host": "0.0.0.0",
"port": 65000
}
```
**Default values (from a config file)**
```js
"wsserver": {
"scheme": "ws",
"host": "localhost",
"port": 9985
}
```
### wsserver.advertised_scheme, wsserver.advertised_host and wsserver.advertised_port
These settings are for the advertising the Websocket URL to external clients in
the root API endpoint. These configurations might be useful if your deployment
is hosted behind a firewall, NAT, etc. where the exposed public IP or domain is
different from where Planetmint is running.
**Example using environment variables**
```text
export PLANETMINT_WSSERVER_ADVERTISED_SCHEME=wss
export PLANETMINT_WSSERVER_ADVERTISED_HOST=myplanetmint.io
export PLANETMINT_WSSERVER_ADVERTISED_PORT=443
```
**Example config file snippet**
```js
"wsserver": {
"advertised_scheme": "wss",
"advertised_host": "myplanetmint.io",
"advertised_port": 443
}
```
**Default values (from a config file)**
```js
"wsserver": {
"advertised_scheme": "ws",
"advertised_host": "localhost",
"advertised_port": 9985
}
```
## log.*
The `log.*` settings are to configure logging.
**Example**
```js
{
"log": {
"file": "/var/log/planetmint.log",
"error_file": "/var/log/planetmint-errors.log",
"level_console": "info",
"level_logfile": "info",
"datefmt_console": "%Y-%m-%d %H:%M:%S",
"datefmt_logfile": "%Y-%m-%d %H:%M:%S",
"fmt_console": "%(asctime)s [%(levelname)s] (%(name)s) %(message)s",
"fmt_logfile": "%(asctime)s [%(levelname)s] (%(name)s) %(message)s",
"granular_levels": {}
}
```
**Default values**
```js
{
"log": {
"file": "~/planetmint.log",
"error_file": "~/planetmint-errors.log",
"level_console": "info",
"level_logfile": "info",
"datefmt_console": "%Y-%m-%d %H:%M:%S",
"datefmt_logfile": "%Y-%m-%d %H:%M:%S",
"fmt_logfile": "[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)",
"fmt_console": "[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)",
"granular_levels": {}
}
```
### log.file
The full path to the file where logs should be written.
The user running `planetmint` must have write access to the
specified path.
**Log rotation:** Log files have a size limit of about 200 MB
and will be rotated up to five times.
For example, if `log.file` is set to `"~/planetmint.log"`, then
logs would always be written to `planetmint.log`. Each time the file
`planetmint.log` reaches 200 MB it will be closed and renamed
`planetmint.log.1`. If `planetmint.log.1` and `planetmint.log.2` already exist they
would be renamed `planetmint.log.2` and `planetmint.log.3`. This pattern would be
applied up to `planetmint.log.5` after which `planetmint.log.5` would be
overwritten by `planetmint.log.4`, thus ending the rotation cycle of whatever
logs were in `planetmint.log.5`.
### log.error_file
Similar to `log.file` (see above), this is the
full path to the file where error logs should be written.
### log.level_console
The log level used to log to the console. Possible allowed values are the ones
defined by [Python](https://docs.python.org/3.9/library/logging.html#levels),
but case-insensitive for the sake of convenience:
```text
"critical", "error", "warning", "info", "debug", "notset"
```
### log.level_logfile
The log level used to log to the log file. Possible allowed values are the ones
defined by [Python](https://docs.python.org/3.9/library/logging.html#levels),
but case-insensitive for the sake of convenience:
```text
"critical", "error", "warning", "info", "debug", "notset"
```
### log.datefmt_console
The format string for the date/time portion of a message, when logged to the
console.
For more information on how to construct the format string please consult the
table under [Python's documentation of time.strftime(format[, t])](https://docs.python.org/3.9/library/time.html#time.strftime).
### log.datefmt_logfile
The format string for the date/time portion of a message, when logged to a log
file.
For more information on how to construct the format string please consult the
table under [Python's documentation of time.strftime(format[, t])](https://docs.python.org/3.9/library/time.html#time.strftime).
### log.fmt_console
A string used to format the log messages when logged to the console.
For more information on possible formatting options please consult Python's
documentation on
[LogRecord attributes](https://docs.python.org/3.9/library/logging.html#logrecord-attributes).
### log.fmt_logfile
A string used to format the log messages when logged to a log file.
For more information on possible formatting options please consult Python's
documentation on
[LogRecord attributes](https://docs.python.org/3.9/library/logging.html#logrecord-attributes).
### log.granular_levels
Log levels for Planetmint's modules. This can be useful to control the log
level of specific parts of the application. As an example, if you wanted the
logging of the `core.py` module to be more verbose, you would set the
configuration shown in the example below.
**Example**
```js
{
"log": {
"granular_levels": {
"bichaindb.core": "debug"
}
}
```
**Default value**
```js
{}
```
## tendermint.*
The settings with names of the form `tendermint.*` tell Planetmint Server
where it can connect to the node's Tendermint instance.
* `tendermint.host` is the hostname (FQDN)/IP address of the Tendermint instance.
* `tendermint.port` is self-explanatory.
**Example using environment variables**
```text
export PLANETMINT_TENDERMINT_HOST=tendermint
export PLANETMINT_TENDERMINT_PORT=26657
```Planetmint
**Default values**
```js
"tendermint": {
"host": "localhost",
"port": 26657
}
```

64
docs/root/source/node-setup/deploy-a-machine.md Normal file
View File

@@ -0,0 +1,64 @@
<!---
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
--->
# Deploy a Machine for Your Planetmint Node
The first step is to deploy a machine for your Planetmint node.
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.
We don't make any assumptions about _where_ you run the machine.
It might be in Azure, AWS, your data center or a Raspberry Pi.
## IP Addresses
The following instructions assume all the nodes
in the network (including yours) have public IP addresses.
(A Planetmint network _can_ be run inside a private network,
using private IP addresses, but we don't cover that here.)
## Operating System
**Use Ubuntu 18.04 or Ubuntu Server 18.04 as the operating system.**
Similar instructions will work on other versions of Ubuntu,
and other recent Debian-like Linux distros,
but you may have to change the names of the packages,
or install more packages.
## Network Security Group
If your machine is in AWS or Azure, for example, _and_
you want users to connect to Planetmint via HTTPS,
then you should configure its network security group
to allow all incoming and outgoing traffic for:
* TCP on port 22 (SSH)
* TCP on port 80 (HTTP)
* TCP on port 443 (HTTPS)
* Any protocol on port 26656 (Tendermint P2P)
If you don't care about HTTPS, then forget about port 443,
and replace port 80 with port 9984 (the default Planetmint HTTP port).
## Update Your System
SSH into your machine and update all its OS-level packages:
```
sudo apt update
sudo apt full-upgrade
```
## DNS Setup
* Register a domain name for your Planetmint node, such as `example.com`
* Pick a subdomain of that domain for your Planetmint node, such as `bnode.example.com`
* Create a DNS "A Record" pointing your chosen subdomain (such as `bnode.example.com`)
at your machine's IP address.

31
docs/root/source/node-setup/index.rst Normal file
View File

@@ -0,0 +1,31 @@
.. 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
Node setup
==========
You can use the all-in-one docker solution, or install Tendermint, MongoDB, and Planetmint step by step. For more advanced users and for development, the second option is recommended.
.. include:: deploy-a-machine.md
:parser: myst_parser.sphinx_
.. include:: aws-setup.md
:parser: myst_parser.sphinx_
.. include:: all-in-one-planetmint.md
:parser: myst_parser.sphinx_
.. include:: planetmint-node-ansible.md
:parser: myst_parser.sphinx_
.. include:: set-up-node-software.md
:parser: myst_parser.sphinx_
.. include:: set-up-nginx.md
:parser: myst_parser.sphinx_
.. include:: configuration.md
:parser: myst_parser.sphinx_
.. include:: production-node/index.rst
:parser: myst_parser.sphinx_

7
docs/root/source/node-setup/planetmint-node-ansible.md Normal file
View File

@@ -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/planetmint/planetmint-node-ansible)
It allows to install Planetmint, MongoDB, Tendermint, and python, and then connect nodes into a network. Current tested machine is Ubuntu 18.04.

20
docs/root/source/node-setup/production-node/index.rst Normal file
View File

@@ -0,0 +1,20 @@
.. 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
Production Nodes
================
.. include:: node-requirements.md
:parser: myst_parser.sphinx_
.. include:: node-assumptions.md
:parser: myst_parser.sphinx_
.. include:: node-components.md
:parser: myst_parser.sphinx_
.. include:: node-security-and-privacy.md
:parser: myst_parser.sphinx_
.. include:: reverse-proxy-notes.md
:parser: myst_parser.sphinx_

25
docs/root/source/node-setup/production-node/node-assumptions.md Normal file
View File

@@ -0,0 +1,25 @@
<!---
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
--->
# Production Node Assumptions
Be sure you know the key Planetmint terminology:
* [Planetmint node, Planetmint network and Planetmint consortium](https://docs.planetmint.io/en/latest/terminology.html)
Note that there are a few kinds of nodes:
- A **dev/test node** is a node created by a developer working on Planetmint 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 Planetmint network. A production node has the most components and requirements.
We make some assumptions about production nodes:
1. Each production node is set up and managed by an experienced professional system administrator or a team of them.
1. Each production node in a network is managed by a different person or team.

30
docs/root/source/node-setup/production-node/node-components.md Normal file
View File

@@ -0,0 +1,30 @@
<!---
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
--->
# Production Node Components
A production Planetmint node must include:
* Planetmint Server
* MongoDB Server 3.4+ (mongod)
* Tendermint
* Storage for MongoDB and Tendermint
It could also include several other components, including:
* NGINX or similar, to provide authentication, rate limiting, etc.
* An NTP daemon running on all machines running Planetmint Server or mongod, and possibly other machines
* Probably _not_ MongoDB Automation Agent. It's for automating the deployment of an entire MongoDB cluster.
* MongoDB Monitoring Agent
* MongoDB Backup Agent
* Log aggregation software
* Monitoring software
* Maybe more
The relationship between the main components is illustrated below.
![Components of a production node](../../_static/Node-components.png)

22
docs/root/source/node-setup/production-node/node-requirements.md Normal file
View File

@@ -0,0 +1,22 @@
<!---
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
--->
# Production Node Requirements
**This page is about the requirements of Planetmint Server.** You can find the requirements of MongoDB, Tendermint and other [production node components](node-components) in the documentation for that software.
## OS Requirements
Planetmint Server requires Python 3.9+ and Python 3.9+ [will run on any modern OS](https://docs.python.org/3.5/using/index.html), but we recommend using an LTS version of [Ubuntu Server](https://www.ubuntu.com/server) or a similarly server-grade Linux distribution.
_Don't use macOS_ (formerly OS X, formerly Mac OS X), because it's not a server-grade operating system. Also, Planetmint Server uses the Python multiprocessing package and [some functionality in the multiprocessing package doesn't work on Mac OS X](https://docs.python.org/3.9/library/multiprocessing.html#multiprocessing.Queue.qsize).
## General Considerations
Planetmint Server runs many concurrent processes, so more RAM and more CPU cores is better.
As mentioned on the page about [production node components](node-components), every machine running Planetmint Server should be running an NTP daemon.

18
docs/root/source/node-setup/production-node/node-security-and-privacy.md Normal file
View File

@@ -0,0 +1,18 @@
<!---
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
--->
# Production Node Security & Privacy
Here are some references about how to secure an Ubuntu 18.04 server:
- [Ubuntu 18.04 - Ubuntu Server Guide - Security](https://help.ubuntu.com/lts/serverguide/security.html.en)
- [Ubuntu Blog: National Cyber Security Centre publish Ubuntu 18.04 LTS Security Guide](https://blog.ubuntu.com/2018/07/30/national-cyber-security-centre-publish-ubuntu-18-04-lts-security-guide)
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 Planetmint, 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 IPDB Testnet.

58
docs/root/source/node-setup/production-node/reverse-proxy-notes.md Normal file
View File

@@ -0,0 +1,58 @@
<!---
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
--->
# Using a Reverse Proxy
You may want to:
* rate limit inbound HTTP requests,
* authenticate/authorize inbound HTTP requests,
* block requests with an HTTP request body that's too large, or
* enable HTTPS (TLS) between your users and your node.
While we could have built all that into Planetmint Server,
we didn't, because you can do all that (and more)
using a reverse proxy such as NGINX or HAProxy.
(You would put it in front of your Planetmint Server,
so that all inbound HTTP requests would arrive
at the reverse proxy before *maybe* being proxied
onwards to your Planetmint Server.)
For detailed instructions, see the documentation
for your reverse proxy.
Below, we note how a reverse proxy can be used
to do some Planetmint-specific things.
You may also be interested in
[our NGINX configuration file template](https://github.com/planetmint/nginx_3scale/blob/master/nginx.conf.template)
(open source, on GitHub).
## Enforcing a Max Transaction Size
The Planetmint HTTP API has several endpoints,
but only one of them, the `POST /transactions` endpoint,
expects a non-empty HTTP request body:
the transaction being submitted by the user.
If you want to enforce a maximum-allowed transaction size
(discarding any that are larger),
then you can do so by configuring a maximum request body size
in your reverse proxy.
For example, NGINX has the `client_max_body_size`
configuration setting. You could set it to 15 kB
with the following line in your NGINX config file:
```text
client_max_body_size 15k;
```
For more information, see
[the NGINX docs about client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size).
Note: By enforcing a maximum transaction size, you
[indirectly enforce a maximum crypto-conditions complexity](https://github.com/planetmint/planetmint/issues/356#issuecomment-288085251).

43
docs/root/source/node-setup/set-up-nginx.md Normal file
View File

@@ -0,0 +1,43 @@
<!---
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
--->
# Set Up NGINX
If you don't want HTTPS
(for communications between the external world and your node),
then you can skip all the NGINX steps on this page.
Note: This simple deployment template uses NGINX for more than just HTTPS.
For example, it also does basic rate limiting.
## Install NGINX
SSH into your machine and install NGINX:
```
sudo apt update
sudo apt install nginx
```
## Configure & Reload NGINX
Get an SSL certificate for your node's subdomain (such as `bnode.example.com`).
* Copy the SSL private key into `/etc/nginx/ssl/cert.key`
* Create a "PEM file" (text file) by concatenating your SSL certificate with all intermediate certificates (_in that order, with the intermediate certs last_).
* Copy that PEM file into `/etc/nginx/ssl/cert.pem`
* In the
[planetmint/planetmint repository on GitHub](https://github.com/planetmint/planetmint),
find the file `nginx/nginx.conf` and copy its contents to
`/etc/nginx/nginx.conf` on your machine (i.e. replace the existing file there).
* Edit that file (`/etc/nginx/nginx.conf`): replace the two instances of
the string `example.testnet2.com`
with your chosen subdomain (such as `bnode.example.com`).
* Reload NGINX by doing:
```
sudo service nginx reload
```

112
docs/root/source/node-setup/set-up-node-software.md Normal file
View File

@@ -0,0 +1,112 @@
<!---
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
--->
# Set Up Planetmint, MongoDB and Tendermint
We now install and configure software that must run
in every Planetmint node: Planetmint Server,
MongoDB and Tendermint.
## Install Planetmint Server
Planetmint Server requires **Python 3.9+**, so make sure your system has it.
Install the required OS-level packages:
```
# For Ubuntu 18.04:
sudo apt install -y python3-pip libssl-dev
# Ubuntu 16.04, and other Linux distros, may require other packages or more packages
```
Planetmint Server requires [gevent](http://www.gevent.org/), and to install gevent, you must use pip 19 or later (as of 2019, because gevent now uses manylinux2010 wheels). Upgrade pip to the latest version:
```
sudo pip3 install -U pip
```
Now install the latest version of Planetmint Server.
You can find the latest version by going
to the [Planetmint project release history page on PyPI](https://pypi.org/project/Planetmint/#history).
For example, to install version 2.2.2, you would do:
```
# Change 2.0.0 to the latest version as explained above:
sudo pip3 install planetmint==2.2.2
```
Check that you installed the correct version of Planetmint Server using `planetmint --version`.
## Configure Planetmint Server
To configure Planetmint Server, run:
```
planetmint configure
```
The first question is ``API Server bind? (default `localhost:9984`)``.
* If you're using NGINX (e.g. if you want HTTPS),
then accept the default value (`localhost:9984`).
* If you're not using NGINX, then enter the value `0.0.0.0:9984`
You can accept the default value for all other Planetmint config settings.
If you're using NGINX, then you should edit your Planetmint config file
(in `$HOME/.planetmint` by default) and set the following values
under `"wsserver"`:
```
"advertised_scheme": "wss",
"advertised_host": "bnode.example.com",
"advertised_port": 443
```
where `bnode.example.com` should be replaced by your node's actual subdomain.
## Install (and Start) MongoDB
Install a recent version of MongoDB.
Planetmint Server requires version 3.4 or newer.
```
sudo apt install mongodb
```
If you install MongoDB using the above command (which installs the `mongodb` package),
it also configures MongoDB, starts MongoDB (in the background),
and installs a MongoDB startup script
(so that MongoDB will be started automatically when the machine is restarted).
Note: The `mongodb` package is _not_ the official MongoDB package
from MongoDB the company. If you want to install the official MongoDB package,
please see
[the MongoDB documentation](https://docs.mongodb.com/manual/installation/).
Note that installing the official package _doesn't_ also start MongoDB.
## Install Tendermint
The version of Planetmint Server described in these docs only works well
with Tendermint 0.31.5 (not a higher version number). Install that:
```
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
```
## Start Configuring Tendermint
You won't be able to finish configuring Tendermint until you have some information
from the other nodes in the network, but you can start by doing:
```
tendermint init
```