Doc: update howto

docs/introduction/howto.rst

@@ -1,14 +1,44 @@
 How to build and run
 ====================
 
-Build instructions
+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 *zeronet* and *zeronet-lmdb* is what you want to use if you want
+  to connect to the most cutting-edge test network, the *Zeronet*. 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 zeronet
+
+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 best way to install all dependencies is by first installing
+The simplest way to install all dependencies is by using `OPAM
-`OPAM <https://opam.ocaml.org/>`__, the OCaml package manager.
+<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
@@ -19,17 +49,26 @@ projects or other versions of Tezos.
 ::
 
     opam update
-    opam switch "tezos" --alias-of 4.06.1
+    opam switch create tezos 4.06.1
+    eval $(opam env)
 
-Note that if you previously created a switch named ``tezos`` but with an
+If you are stuck with OPAM1:
-older OCaml version you need to remove the switch with
-``opam switch remove "tezos"``.
-
-When the switch is ready, you need to activate it:
 
 ::
 
-    eval `opam config env`
+    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:
 
@@ -52,13 +91,15 @@ At last, compile the project:
 This should produce three binaries:
 
 -  ``tezos-node``: the tezos daemon itself;
--  ``tezos-client``: a minimal command-line client;
+-  ``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 in
+macOS, but it has not been tested recently. A Windows port is feasible
-progress.
+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
@@ -76,69 +117,110 @@ opam internal state with the following commands:
     make
 
 
-Running the node
+Join the Zeronet!
-----------------
+-----------------
 
-So far there is no official Tezos network being run, but you might run a
+If you succesfully built Tezos on the *zeronet* or *zeronet-lmdb*
-local test network (the development team is running its own testnet, if
+branch, then your node is elligible to join Tezos'
-you’re interested in joining this network, please make a request on our
+:ref:`Zeronet<zeronet>`.
-slack channel. We have limited support abilities at the moment but we’ll
-try to help you best we can).
 
-Use the following command to run a node that will accept incoming
+Command-line basics
-connections:
+~~~~~~~~~~~~~~~~~~~
+
+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 generate 24.
+   ./tezos-node identity --help
+   ./tezos-node config --help
+   ./tezos-node run --help
 
-This will first generate a new node identity and compute the associated
+
-stamp of proof-of-work. Then, the node will listen to connections coming
+The `identity` and `config` serve the purpose of managing
-in on ``[::]:9732``. All used data is stored at ``$HOME/.tezos-node/``.
+configuration files for the node, we will describe them below. The
-For example, the default configuration file is at
+`run` command is for running the node.
-``$HOME/.tezos-node/config.json``.
+
+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 Zeronet.
+
+::
+
+    ./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 ``[::]:19732``.
+
+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
+``$HOME/.tezos-node/config.json`` while making sure they don't share
-paths to the database or any other data file (cf. options ``db.store`` ;
+the same ``data-dir``. Then run your node with `./tezos-node
-``db.context`` ; ``db.protocol``, ``net.peers-metadata`` and
+run --config-file=</path/to/alternate_cfg>`.
-``net.identity``).
 
-You could also let Tezos generate a config file by specifying options on
+Lastly, you want to enable RPC communication with clients. Use:
-the command line. For instance, if ``$dir/config.json`` does not exist,
-the following command will generate it and replace the default values
-with the values from the command line:
 
 ::
 
-    ./tezos-node run --data-dir "$dir" --net-addr localhost:9733
+   ./tezos-node config update --rpc-addr=127.0.0.1:8732
 
-The Tezos server has a built-in mechanism to discover peers on the local
+This is the default socket address that the client will try, so
-network (using UDP packets broadcasted on port 7732).
+`./tezos-client` will work out-of-the-box that way.
 
-If this mechanism is not sufficient, one can provide Tezos with a list
+Run your node
-of initial peers, either by editing the option ``net.bootstrap-peers``
+~~~~~~~~~~~~~
-in the ``config.json`` file, or by specifying a command line parameter:
+
+You are all set! Now you just need to do:
 
 ::
 
-    ./tezos-node run \
+   ./tezos-node run
-                 --data-dir "$dir" --net-addr localhost:2023 \
-                 --peer localhost:2021 --peer localhost:2022
 
-If ``"$dir"/config.json`` exists, the command line options override
+To interact with your node, read the doc of clients:
-those read in the config file. By default, Tezos won’t modify the
-content of an existing ``"$dir"/config.json`` file. But, you may
-explicit ask the node to reset or to update the file according to the
-command line parameters with the following commands line:
 
 ::
 
-    ./tezos-node config reset --data-dir "$dir" --net-addr localhost:9733
+   ./tezos-client man
-    ./tezos-node config update --data-dir "$dir" --net-addr localhost:9734
+   ./tezos-admin-client man
+   ./tezos-alpha-baker man
 
-Running the node in a sandbox
+And read :ref:`this page<zeronet>` to get zeronet tezzies.
------------------------------
+
+Run the node in a sandbox
+-------------------------
 
 To run a ‘localhost-only’ instance of a Tezos network, we provide two
 helper scripts:
@@ -356,7 +438,7 @@ 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’.
+the DEBUG section displayed by `tezos-node run –-help`.
 
 JSON/RPC interface
 ------------------