diff --git a/docs/developer/howto-freeze-protocols.rst b/docs/developer/howto-freeze-protocols.rst index 6df7a07e8140699739170aab9e4884d533f320a5..533a4acfc8aa820fedb4959a0bc15fc07adf22ac 100644 --- a/docs/developer/howto-freeze-protocols.rst +++ b/docs/developer/howto-freeze-protocols.rst @@ -92,6 +92,12 @@ the plugin in the file ``proto_XXX/lib_plugin/plugin_registration.ml``. Other plugins should be evaluated case-by-case. At the moment of writing, the ``Mempool`` plugin is the only one that can be safely removed. +Remove Old Docker-Compose Files +------------------------------- + +The docker-compose file with the corresponding protocol name can be removed from the +``scripts/docker`` directory. + Add an Entry in ``CHANGES.rst`` ------------------------------- diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index e612e8db3e439bc5dcb218f3cdba675a02614213..4d46fabfdfc79830723744abcffe079851024053 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -141,22 +141,94 @@ listed by ``dnf repoinfo``. .. _using_docker_images: -Using Docker images -------------------- +Using Docker Images And Docker-Compose +-------------------------------------- For every change committed in the GitLab repository, Docker images are automatically generated and published on `DockerHub `_. This provides a convenient way to run an always up-to-date ``tezos-node``. -One way to run those Docker images is with Docker Compose. -An example Docker Compose script is provided in -:src:`scripts/docker/docker-compose-generic.yml`. -It launches a node, a baker, and an accuser for protocol Alpha. -You can adapt it to run the baker and accuser for other protocols -by replacing all instances of ``alpha`` to e.g. ``014-PtKathma`` for Kathmandu. -Replacing the value of the ``PROTOCOL`` environment variable is enough -but you may want to update the ``hostname`` and the container name too. +One way to run those Docker images is with `docker-compose `_. +We provide ``docker-compose`` files for all active +protocols. You can pick one and start with the following command (we'll assume alpha on this guide): + +:: + + cd scripts/docker + export LIQUIDITY_BAKING_VOTE=pass # You can choose between 'on', 'pass' or 'off'. + docker-compose -f alpha.yml up + +The above command will launch a node, a client, a baker, and an accuser for +the Alpha protocol. + +You can open a new shell session and run ``docker ps`` in it, to display all the available containers, e.g.:: + + 8f3638fae48c docker.io/tezos/tezos:latest tezos-node 3 minutes ago Up 3 minutes ago 0.0.0.0:8732->8732/tcp, 0.0.0.0:9732->9732/tcp node-alpha + 8ba4d6077e2d docker.io/tezos/tezos:latest tezos-baker --liq... 3 minutes ago Up 31 seconds ago baker-alpha + 3ee7fcbc2158 docker.io/tezos/tezos:latest tezos-accuser 3 minutes ago Up 35 seconds ago accuser-alpha + + +The node's RPC interface will be available on localhost and can be queried with ``tezos-client``. + +:: + + docker exec node-alpha tezos-client rpc list + +Building Docker Images Locally +------------------------------ + +The docker image used throughout the docker-compose files is fetched from upstream, but you can also +build one locally and reference it. Run the following commands to build the image: + +:: + + ./scripts/ci/create_docker_image.build.sh + ./scripts/ci/create_docker_image.minimal.sh + + +And then update the docker-compose file (e.g., ``alpha.yml``) with the docker tag:: + + node: + image: tezos:latest + ... + +Docker Image Configuration +-------------------------- + +Lastly, the entrypoint script (:src:`scripts/docker/entrypoint.sh`) provides the following configurable +environment variables: + +- ``DATA_DIR``: The directory to store the node's data (defaults to ``/var/run/tezos``). +- ``NODE_HOST``: The name of the node container (defaults to ``node``). +- ``NODE_RPC_PORT``: The RPC port to listen to (defaults to ``8732``). +- ``NODE_RPC_ADDR``: The RPC address that the node will listen to (defaults to ``localhost``). +- ``PROTOCOL``: The protocol that will be used. + +These variables can be set in the docker-compose file, as demonstrated in ``alpha.yml``:: + + node: + ... + environment: + PROTOCOL: alpha + ... + +If the above options are not enough, you can always replace the default ``entrypoint`` and ``command`` fields. + +:: + + version: "3" + services: + node: + container_name: node-alpha + entrypoint: /bin/sh + command: /etc/my-init-script.sh + volumes: + - ./my-init-script.sh:/etc/my-init-script.sh + - ... + environment: + PROTOCOL: alpha + ... .. _building_with_opam: diff --git a/scripts/docker/alpha.yml b/scripts/docker/alpha.yml new file mode 100644 index 0000000000000000000000000000000000000000..61e7f58fd304741e6626119ba3cfb68b894cedf4 --- /dev/null +++ b/scripts/docker/alpha.yml @@ -0,0 +1,51 @@ +version: "3" +services: + octez-node: + container_name: octez-node-alpha + image: tezos/tezos:latest + hostname: octez-node + command: tezos-node + ports: + - 9732:9732 + - 8732:8732 + environment: + NODE_RPC_ADDR: "0.0.0.0" + NODE_HOST: octez-node + PROTOCOL: alpha + volumes: + - node_data:/var/run/tezos/node + - client_data:/var/run/tezos/client + restart: on-failure + + octez-baker: + container_name: octez-baker-alpha + image: tezos/tezos:latest + hostname: octez-baker + command: tezos-baker --liquidity-baking-toggle-vote $LIQUIDITY_BAKING_VOTE + environment: + NODE_RPC_ADDR: "0.0.0.0" + NODE_HOST: octez-node + PROTOCOL: alpha + volumes: + - client_data:/var/run/tezos/client + - node_data:/var/run/tezos/node + restart: on-failure + + + octez-accuser: + container_name: octez-accuser-alpha + image: tezos/tezos:latest + hostname: octez-accuser + command: tezos-accuser + environment: + NODE_RPC_ADDR: "0.0.0.0" + NODE_HOST: octez-node + PROTOCOL: alpha + volumes: + - client_data:/var/run/tezos/client + - node_data:/var/run/tezos/node + restart: on-failure + +volumes: + node_data: {} + client_data: {} diff --git a/scripts/docker/docker-compose-generic.yml b/scripts/docker/docker-compose-generic.yml deleted file mode 100644 index 12273c03e7e8b8cf43a1d12ac6b28fd515134ea2..0000000000000000000000000000000000000000 --- a/scripts/docker/docker-compose-generic.yml +++ /dev/null @@ -1,45 +0,0 @@ -version: "2" -services: - - node: - image: tezos/tezos:latest - hostname: node - command: octez-node - ports: - - 9732:9732 - expose: - - '8732' - volumes: - - node_data:/var/run/tezos/node - - client_data:/var/run/tezos/client - restart: on-failure - - ## Duplicate the `baker/accuser` containers for each PROTOCOL - ## in file `active_protocol_versions` - baker-alpha: - image: tezos/tezos:latest - hostname: baker-alpha - environment: - - PROTOCOL=alpha - command: octez-baker - links: - - node - volumes: - - client_data:/var/run/tezos/client - restart: on-failure - - accuser-alpha: - image: tezos/tezos:latest - hostname: accuser-alpha - environment: - - PROTOCOL=alpha - command: octez-accuser - links: - - node - volumes: - - client_data:/var/run/tezos/client - restart: on-failure - -volumes: - node_data: - client_data: diff --git a/scripts/docker/entrypoint.inc.sh b/scripts/docker/entrypoint.inc.sh index 133313a83b1022253ac767f246e23e3cba4fd30d..29e843c9d2a50bbbd9e1a9a0eb35ae1892af97fd 100644 --- a/scripts/docker/entrypoint.inc.sh +++ b/scripts/docker/entrypoint.inc.sh @@ -117,15 +117,15 @@ launch_node() { echo "Configuring the node..." "$node" config init \ --data-dir "$node_data_dir" \ - --rpc-addr "[::]:$NODE_RPC_PORT" \ - --allow-all-rpc "[::]:$NODE_RPC_PORT" \ + --rpc-addr "$NODE_RPC_ADDR:$NODE_RPC_PORT" \ + --allow-all-rpc "$NODE_RPC_ADDR:$NODE_RPC_PORT" \ $config_args else echo "Updating the node configuration..." "$node" config update \ --data-dir "$node_data_dir" \ - --rpc-addr "[::]:$NODE_RPC_PORT" \ - --allow-all-rpc "[::]:$NODE_RPC_PORT" \ + --rpc-addr "$NODE_RPC_ADDR:$NODE_RPC_PORT" \ + --allow-all-rpc "$NODE_RPC_ADDR:$NODE_RPC_PORT" \ $config_args fi diff --git a/scripts/docker/entrypoint.sh b/scripts/docker/entrypoint.sh index 03d1feec77a0b98fb7a25d3b39edfbe503cf8334..bc7fa86c0607ac44f08647101e81abe9f05e2c9c 100755 --- a/scripts/docker/entrypoint.sh +++ b/scripts/docker/entrypoint.sh @@ -9,6 +9,7 @@ bin_dir="$(cd "$(dirname "$0")" && echo "$(pwd -P)/")" : "${NODE_HOST:="node"}" : "${NODE_RPC_PORT:="8732"}" +: "${NODE_RPC_ADDR:="localhost"}" : "${PROTOCOL:="unspecified-PROTOCOL-variable"}" diff --git a/scripts/docker/kathmandu.yml b/scripts/docker/kathmandu.yml new file mode 100644 index 0000000000000000000000000000000000000000..369c7159ce6191c3502d9acf61ad12fd91935442 --- /dev/null +++ b/scripts/docker/kathmandu.yml @@ -0,0 +1,51 @@ +version: "3" +services: + octez-node: + container_name: octez-node-kathmandu + image: tezos/tezos:latest + hostname: octez-node + command: tezos-node + ports: + - 9732:9732 + - 8732:8732 + environment: + NODE_RPC_ADDR: "0.0.0.0" + NODE_HOST: octez-node + PROTOCOL: 014-PtKathma + volumes: + - node_data:/var/run/tezos/node + - client_data:/var/run/tezos/client + restart: on-failure + + octez-baker: + container_name: octez-baker-kathmandu + image: tezos/tezos:latest + hostname: octez-baker + command: tezos-baker --liquidity-baking-toggle-vote $LIQUIDITY_BAKING_VOTE + environment: + NODE_RPC_ADDR: "0.0.0.0" + NODE_HOST: octez-node + PROTOCOL: 014-PtKathma + volumes: + - client_data:/var/run/tezos/client + - node_data:/var/run/tezos/node + restart: on-failure + + + octez-accuser: + container_name: octez-accuser-kathmandu + image: tezos/tezos:latest + hostname: octez-accuser + command: tezos-accuser + environment: + NODE_RPC_ADDR: "0.0.0.0" + NODE_HOST: octez-node + PROTOCOL: 014-PtKathma + volumes: + - client_data:/var/run/tezos/client + - node_data:/var/run/tezos/node + restart: on-failure + +volumes: + node_data: {} + client_data: {}