ligo/docs/introduction/howto.rst

.. _howto:

How to build and run
====================

Get the sources
---------------

Tezos *git* repository is hosted at `GitLab
<https://gitlab.com/tezos/tezos/>`_. All development happens here. Do
**not** use our `GitHub mirror <https://github.com/tezos/tezos>`_
which we don't use anymore and only mirrors what happens at GitLab.

You also need to **choose a branch**:

- The *master* branch is where code is merged, but there is no test
  network using the *master* branch directly.
- The *alphanet* and *alphanet-lmdb* is what you want to use if you want
  to connect to Tezos' test network, the *Alphanet*. The
  *-lmdb* version uses LMDB instead of LevelDB.

**TL;DR**: Typically you want to do:

::

   git clone git@gitlab.com:tezos/tezos.git
   git checkout alphanet

Install OPAM
------------

To compile Tezos, you need an OCaml compiler (version 4.06.1) and all
the libraries listed in the various ``tezos-*.opam`` files.

The simplest way to install all dependencies is by using `OPAM
<https://opam.ocaml.org/>`__, the OCaml package manager.


**IMPORTANT**: Please use `version 2
<https://github.com/ocaml/opam/releases/tag/2.0.0-rc>`_ of OPAM. That
is what the Tezos Core team uses. Most distribution probably ship
**version 1** of OPAM out of the box, but installing version 2 is
preferable for many reasons.

Then, you need to create a new switch alias for Tezos. A switch is your
own version of the OPAM configuration, including the OCaml compiler, all
packages, and package manager configuration related to your project.
This is necessary so that the project doesn’t conflict with other OCaml
projects or other versions of Tezos.

::

    opam update
    opam switch create tezos 4.06.1
    eval $(opam env)

If you are stuck with OPAM1:

::

    opam update
    opam switch tezos --alias-of 4.06.1
    eval $(opam config env)

The last command-line activates the switch.

Note that if you previously created a switch named ``tezos`` but with
an older OCaml version you need to remove the switch with ``opam
switch remove tezos``.


Install Tezos dependencies with OPAM
------------------------------------

Install the libraries which Tezos depends on:

::

    make build-deps

While building the dependencies, ``opam`` is able to handle correctly
the OCaml libraries but it is not always able to handle all external C
libraries we depend on. On most system, it is able to suggest a call to
the system package manager but it currently does not handle version
check.

At last, compile the project:

::

    make

This should produce three binaries:

-  ``tezos-node``: the tezos daemon itself;
-  ``tezos-client``: a command-line client;
-  ``tezos-admin-client``: a command-line administration tool for the node;
-  ``tezos-alpha-baker``: a client and daemon to bake on the Tezos network;
-  ``tezos-protocol-compiler``: a protocol compiler used for developing
   new version of the economic protocol.

Currently Tezos is being developed for Linux only. It should work on
macOS, but it has not been tested recently. A Windows port is feasible
and might be developed in the future.

Note that, when executing ``make build-deps``, OPAM will detect if
required system dependencies are installed. However, it is not able to
detect which versions you actually have.

If after a ``git pull``, the build fails (either at ``make
build-deps`` or ``make``), you might try to clean up a little bit the
opam internal state with the following commands:

::

    opam update
    opam pin list -s | xargs opam pin remove
    make build-deps
    make


Join the Alphanet!
------------------

If you succesfully built Tezos on the *alphanet* or *alphanet-lmdb*
branch, then your node is elligible to join Tezos'
:ref:`Alphanet<alphanet>`.

Command-line basics
~~~~~~~~~~~~~~~~~~~

The `tezos-node` executable uses subcommands. You can obtain help on a
subcommand by using `./tezos-node <subcommand> --help`. There are
three subcommands:

::

   ./tezos-node identity --help
   ./tezos-node config --help
   ./tezos-node run --help


The `identity` and `config` serve the purpose of managing
configuration files for the node, we will describe them below. The
`run` command is for running the node.

Pretty much all configuration parameters can be overriden by a
command-line argument. Check out `./tezos-node run --help` to discover
them.

Configure your node
~~~~~~~~~~~~~~~~~~~

The following steps are required to connect to Alphanet.

::

    ./tezos-node identity generate

This will generate a new node identity and compute the associated
stamp of proof-of-work. The identity comprises a pair of cryptographic
keys that nodes use to encrypt messages sent to each other, and an
antispam-PoW stamp proving that enough computing power has been
dedicated to creating this identity.

The identity will be stored in `$HOME/.tezos-node/identity.json`.

::

   ./tezos-node config init

This will initialize an configuration file for the node in
`$HOME/.tezos-node/config.json`, using default values. It only
specifies that the node will listen to incoming connections on socket
address ``[::]:9732``.

The easiest way to amend this default configuration is to use

::

   # Update the config file
   ./tezos-node config update <…>
   # Start from an empty cfg file
   ./tezos-node config reset <…>


All blockchain data is stored under ``$HOME/.tezos-node/``.  You can
change this by doing `./tezos-node config update --data-dir
</somewhere/in/your/disk>`.

To run multiple nodes on the same machine, you can duplicate and edit
``$HOME/.tezos-node/config.json`` while making sure they don't share
the same ``data-dir``. Then run your node with `./tezos-node
run --config-file=</path/to/alternate_cfg>`.

Lastly, you want to enable RPC communication with clients. Use:

::

   ./tezos-node config update --rpc-addr=127.0.0.1:8732

This is the default socket address that the client will try, so
`./tezos-client` will work out-of-the-box that way.

Run your node
~~~~~~~~~~~~~

You are all set! Now you just need to do:

::

   ./tezos-node run

To interact with your node, read the doc of clients:

::

   ./tezos-client man
   ./tezos-admin-client man
   ./tezos-alpha-baker man

And read :ref:`this page<alphanet>` to get alphanet tezzies.

Use sandboxed mode
------------------

To run a ‘localhost-only’ instance of a Tezos network, we provide two
helper scripts:

-  ``./src/bin_node/tezos-sandboxed-node.sh``
-  ``./src/bin_client/tezos-init-sandboxed-client.sh``

Run a sandboxed node
~~~~~~~~~~~~~~~~~~~~

For instance, if you want to run local network with two nodes, in a
first terminal, the following command will initialize a node listening
for peers on port ``19731`` and listening for RPC on port ``18731``.

::

    ./src/bin_node/tezos-sandboxed-node.sh 1

This node will store its data in a temporary directory which will be
removed when the node is killed.

To launch the second node, just run the following command, it will
listen on port ``19739`` and ``18739``:

::

    ./src/bin_node/tezos-sandboxed-node.sh 9

You might replace ``1`` or ``9`` by any number in between if you want to
run more than two nodes. But, if you intend to run a single node
network, you might remove the spurious “Too few connections” warnings by
lowering the number of expected connection, by running the following
command instead:

::

    ./src/bin_node/tezos-sandboxed-node.sh 1 --connections 0

Use the sandboxed client
~~~~~~~~~~~~~~~~~~~~~~~~

Once your node(s) is/are running, open a new terminal and initialize the
“sandboxed” client data:

::

    eval `./src/bin_client/tezos-init-sandboxed-client.sh 1`

It will initialize the client data in a temporary directory. It will
also defines in the current shell session an alias ``tezos-client``
preconfigured for communicating the same-numbered node. For instance:

::

    $ tezos-client rpc post blocks/head/hash
    { "hash": "BLockGenesisGenesisGenesisGenesisGenesisGeneskvg68z" }

When you bootstrap a new network, the network is initialized with a
dummy economic protocol, called “genesis”. If you want to run the same
protocol than the alphanet, ``init-sandboxed-client`` also defines an
alias ``tezos-activate-alpha``, that you need to execute once for
activating the whole network. For instance:

::

    $ tezos-client rpc post blocks/head/protocol
    { "protocol": "ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im" }
    $ tezos-activate-alpha
    Injected BMBcK869jaHQDc
    $ tezos-client rpc post blocks/head/protocol
    { "protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" }

Tune protocol alpha parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``tezos-active-alpha`` alias use parameters from
``scripts/protocol_parameters.json`` to activate protocol alpha. It can
be useful to tune these parameters when you need to debug something,
for example, change the number of blocks per cycle, the time between
blocks, etc.

Configuration options
---------------------

Here is an example configuration file with all parameters specified.
Most of the time it uses default values, except for cases where the
default is not explanatory enough (i.e. “bootstrap-peers” is an empty
list by default). Comments are not allowed in JSON, so this
configuration file would not parse. They are just provided here to help
writing your own configuration file if needed.

::

    {

      /* Location of the data dir on disk. */

      "data-dir": "/home/tezos/my_data_dir"

      /* Configuration of net parameters */

      "net": {

        /* Floating point number between 0 and 256 that represents a
        difficulty, 24 signifies for example that at least 24 leading
        zeroes are expected in the hash. */

        "expected-proof-of-work": 24.5,

        /* List of hosts. Tezos can connect to both IPv6 and IPv4
        hosts. If the port is not specified, default port 9732 will be
        assumed. */

        "bootstrap-peers": ["::1:10732", "::ffff:192.168.1.3:9733", "mynode.tezos.com"],

        /* Specify if the network is closed or not. A closed network
        allows only peers listed in "bootstrap-peers". */

        "closed": false,

        /* Network limits */

        "limits": {

          /* Delay granted to a peer to perform authentication, in
          seconds. */

          "authentication-timeout": 5,

          /* Strict minimum number of connections (triggers an urgent
          maintenance). */

          "min-connections": 50,

          /* Targeted number of connections to reach when bootstraping /
          maintaining. */

          "expected-connections": 100,

          /* Maximum number of connections (exceeding peers are
          disconnected). */

          "max-connections": 200,

          /* Number above which pending incoming connections are
          immediately rejected. */

          "backlog": 20,

          /* Maximum allowed number of incoming connections that are
          pending authentication. */

          "max-incoming-connections": 20,

          /* Max download and upload speeds in KiB/s. */

          "max-download-speed": 1024,
          "max-upload-speed": 1024,

          /* Size of the buffer passed to read(2). */

          "read-buffer-size": 16384,
        }
      },

      /* Configuration of rpc parameters */

      "rpc": {

        /* Host to listen to. If the port is not specified, the default
        port 8732 will be assumed. */

        "listen-addr": "localhost:8733",

        /* Cross Origin Resource Sharing parameters, see
        https://en.wikipedia.org/wiki/Cross-origin_resource_sharing. */

        "cors-origin": [],
        "cors-headers": [],

        /* Certificate and key files (necessary when TLS is used). */

        "crt": "tezos-node.crt",
        "key": "tezos-node.key"
      },

      /* Configuration of log parameters */

      "log": {

        /* Output for the logging function. Either "stdout", "stderr" or
        the name of a log file . */

        "output": "tezos-node.log",

        /* Verbosity level: one of 'fatal', 'error', 'warn', 'notice',
        'info', 'debug'. */

        "level": "info",

        /* Fine-grained logging instructions. Same format as described in
        `tezos-node run --help`, DEBUG section. In the example below,
        sections "net" and all sections starting by "client" will have
        their messages logged up to the debug level, whereas the rest of
        log sections will be logged up to the notice level. */

        "rules": "client* -> debug, net -> debug, * -> notice",

        /* Format for the log file, see
        http://ocsigen.org/lwt/dev/api/Lwt_log_core#2_Logtemplates. */

        "template": "$(date) - $(section): $(message)"
      },

      /* Configuration for the validator and mempool parameters */

      "shell": {

         /* The number of peers to synchronize with
            before declaring the node 'bootstrapped'. */

         "bootstrap_threshold": 4

      }
    }

Debugging
---------

It is possible to set independent log levels for different logging
sections in Tezos, as well as specifying an output file for logging. See
the description of log parameters above as well as documentation under
the DEBUG section displayed by `tezos-node run –-help`.

JSON/RPC interface
------------------

The Tezos node provides a JSON/RPC interface. Note that it is an RPC,
and it is JSON based, but it does not follow the “JSON-RPC” protocol. It
is not active by default and it must be explicitly activated with the
``--rpc-addr`` option. Typically, if you are not trying to run a local
network and just want to explore the RPC, you would run:

::

    ./tezos-node run --rpc-addr localhost

The RPC interface is self-documented and the ``tezos-client`` executable
is able to pretty-print the RPC API. For instance, to see the API
provided by the Tezos Shell:

::

    ./tezos-client rpc list

To get API attached to the “genesis” block, including the remote
procedures provided by the associated economic protocol version:

::

    ./tezos-client rpc list /blocks/genesis/

You might also want the JSON schema describing the expected input and
output of a RPC. For instance:

::

    ./tezos-client rpc schema /blocks/genesis/hash

Note: you can get the same information, but as a raw JSON object, with a
simple HTTP request:

::

    wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe
    wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe/blocks/genesis
    wget -O - http://localhost:8732/describe/blocks/genesis/hash

The minimal CLI client
----------------------

Tezos is distributed with two command line tools: a minimal command
line wallet ``tezos-client``, and an administration tool
``tezos-admin-client``.

Their command line interfaces are described
:ref:`here<tezos_client_commands>` and
:ref:`here<tezos_admin_client_commands>`.