docs: move debug, docker and simulation sections to tutorials

docs/docs/kb/13-debug.md → docs/docs/guide/10-debug.md

@@ -1,27 +1,26 @@
 ---
-sidebar_position: 13
-description: Blockchain Debug
+description: Debugging your Cosmos SDK blockchain
 ---
 
-# Blockchain Debug
+# Debugging a chain
 
-Ignite chain debug command can help you to find issues during development.
-It uses [Delve](https://github.com/go-delve/delve) debugger which enables you to
+Ignite chain debug command can help you find issues during development. It uses
+[Delve](https://github.com/go-delve/delve) debugger which enables you to
 interact with your blockchain app by controlling the execution of the process,
 evaluating variables, and providing information of thread / goroutine state, CPU
 register state and more.
 
 ## Debug Command
 
 The debug command requires that the blockchain app binary is build with
-debugging support by removing optimizations and inlining.
-A debug binary is built by default by the `ignite chain serve` command or can
-optionally be created using the `--debug` flag when running `ignite chain init`
-or `ignite chain build` sub-commands.
+debugging support by removing optimizations and inlining. A debug binary is
+built by default by the `ignite chain serve` command or can optionally be
+created using the `--debug` flag when running `ignite chain init` or `ignite
+chain build` sub-commands.
 
 To start a debugging session in the terminal run:
 
-```bash
+```
 ignite chain debug
 ```
 
@@ -33,10 +32,11 @@ Type 'help' for list of commands.
 (dlv)
 ```
 
-At this point the blockchain app blocks execution so you can set one or more
+At this point the blockchain app blocks execution, so you can set one or more
 breakpoints before continuing execution.
 
-Use the [break](https://github.com/go-delve/delve/blob/master/Documentation/cli/README.md#break)
+Use the
+[break](https://github.com/go-delve/delve/blob/master/Documentation/cli/README.md#break)
 (alias `b`) command to set any number of breakpoints using, for example the
 `<filename>:<line>` notation:
 
@@ -47,7 +47,7 @@ Use the [break](https://github.com/go-delve/delve/blob/master/Documentation/cli/
 This command adds a breakpoint to the `x/hello/client/cli/query_say_hello.go`
 file at line 14.
 
-Once all breakpoints are setted resume blockchain execution using the
+Once all breakpoints are set resume blockchain execution using the
 [continue](https://github.com/go-delve/delve/blob/master/Documentation/cli/README.md#continue)
 (alias `c`) command:
 
@@ -71,13 +71,13 @@ client connections.
 
 To start a debug server use the following flag:
 
-```bash
+```
 ignite chain debug --server
 ```
 
 To start a debug server with a custom address use the following flags:
 
-```bash
+```
 ignite chain debug --server --server-address 127.0.0.1:30500
 ```
 
@@ -94,7 +94,7 @@ Using it as debugging client is straightforward as it doesn't require any
 configuration. Once the debug server is running and listening for client
 requests connect to it by running:
 
-```bash
+```
 gdlv connect 127.0.0.1:30500
 ```
 
@@ -112,7 +112,7 @@ extension is installed.
 VS Code debugging is configured using the `launch.json` file which is usually
 located inside the `.vscode` folder in your workspace.
 
-You can use the following launch configuration to set up VS Code as debugging 
+You can use the following launch configuration to set up VS Code as debugging
 client:
 
 ```json title=launch.json
@@ -133,31 +133,36 @@ client:
 ```
 
 Alternatively it's possible to create a custom `launch.json` file from the "Run
-and Debug" panel. When prompted choose the Go debugger option labeled "Go: 
+and Debug" panel. When prompted choose the Go debugger option labeled "Go:
 Connect to Server" and enter the debug host address and then the port number.
 
 ## Example: Debugging a Blockchain App
 
 In this short example we will be using Ignite CLI to create a new blockchain and
 a query to be able to trigger a debugging breakpoint when the query is called.
 
-To create a new blockchain and a query run:
+Create a new blockchain:
 
-```bash
+```
 ignite scaffold chain hello
+```
+
+Scaffold a new query in the `hello` directory:
+
+```
 ignite scaffold query say-hello name --response name
 ```
 
 The next step initializes the blockchain's data directory and compiles a debug
 binary:
 
-```bash
+```
 ignite chain init --debug
 ```
 
 Once the initialization finishes launch the debugger shell:
 
-```bash
+```
 ignite chain debug
 ```
 
@@ -171,7 +176,7 @@ Within the debugger shell create a breakpoint that will be triggered when the
 
 From a different terminal use the `hellod` binary to call the query:
 
-```bash
+```
 hellod query hello say-hello bob
 ```
 
@@ -200,5 +205,5 @@ From then on you can use Delve commands like `next` (alias `n`) or `print`
 "bob"
 ```
 
-Finally use `quit` (alias `q`) to stop the blockchain app and finish the
+Finally, use `quit` (alias `q`) to stop the blockchain app and finish the
 debugging session.

docs/docs/guide/11-docker.md

@@ -0,0 +1,142 @@
+---
+description: Run Ignite CLI using a Docker container.
+---
+
+# Running inside a Docker container
+
+You can run Ignite CLI inside a Docker container without installing the Ignite
+CLI binary directly on your machine.
+
+Running Ignite CLI in Docker can be useful for various reasons; isolating your
+test environment, running Ignite CLI on an unsupported operating system, or
+experimenting with a different version of Ignite CLI without installing it.
+
+Docker containers are like virtual machines because they provide an isolated
+environment to programs that runs inside them. In this case, you can run Ignite
+CLI in an isolated environment.
+
+Experimentation and file system impact is limited to the Docker instance. The
+host machine is not impacted by changes to the container.
+
+## Prerequisites
+
+Docker must be installed. See [Get Started with
+Docker](https://www.docker.com/get-started).
+
+## Ignite CLI Commands in Docker
+
+After you scaffold and start a chain in your Docker container, all Ignite CLI
+commands are available. Just type the commands after `docker run -ti
+ignite/cli`. For example:
+
+```bash
+docker run -ti ignitehq/cli -h
+docker run -ti ignitehq/cli scaffold chain planet
+docker run -ti ignitehq/cli chain serve
+```
+
+## Scaffolding a chain
+
+When Docker is installed, you can build a blockchain with a single command.
+
+Ignite CLI, and the chains you serve with Ignite CLI, persist some files. When
+using the CLI binary directly, those files are located in `$HOME/.ignite` and
+`$HOME/.cache`, but in the context of Docker it's better to use a directory
+different from `$HOME`, so we use `$HOME/sdh`. This folder should be created
+manually prior to the docker commands below, or else Docker creates it with the
+root user.
+
+```bash
+mkdir $HOME/sdh
+```
+
+To scaffold a blockchain `planet` in the `/apps` directory in the container, run
+this command in a terminal window:
+
+```bash
+docker run -ti -v $HOME/sdh:/home/tendermint -v $PWD:/apps ignitehq/cli:0.25.2 scaffold chain planet
+```
+
+Be patient, this command takes a minute or two to run because it does everything
+for you:
+
+- Creates a container that runs from the `ignitehq/cli:0.25.2` image.
+- Executes the Ignite CLI binary inside the image.
+- `-v $HOME/sdh:/home/tendermint` maps the `$HOME/sdh` directory in your local
+  computer (the host machine) to the home directory `/home/tendermint` inside
+  the container.
+- `-v $PWD:/apps` maps the current directory in the terminal window on the host
+  machine to the `/apps` directory in the container. You can optionally specify
+  an absolute path instead of `$PWD`.
+
+  Using `-w` and `-v` together provides file persistence on the host machine.
+  The application source code on the Docker container is mirrored to the file
+  system of the host machine.
+
+  **Note:** The directory name for the `-w` and `-v` flags can be a name other
+  than `/app`, but the same directory must be specified for both flags. If you
+  omit `-w` and `-v`, the changes are made in the container only and are lost
+  when that container is shut down.
+
+## Starting a blockchain
+
+To start the blockchain node in the Docker container you just created, run this
+command:
+
+```bash
+docker run -ti -v $HOME/sdh:/home/tendermint -v $PWD:/apps -p 1317:1317 -p 26657:26657 ignitehq/cli:0.25.2 chain serve -p planet
+```
+
+This command does the following:
+
+- `-v $HOME/sdh:/home/tendermint` maps the `$HOME/sdh` directory in your local
+  computer (the host machine) to the home directory `/home/tendermint` inside
+  the container.
+- `-v $PWD:/apps` persists the scaffolded app in the container to the host
+  machine at current working directory.
+- `serve -p planet` specifies to use the `planet` directory that contains the
+  source code of the blockchain.
+- `-p 1317:1317` maps the API server port (cosmos-sdk) to the host machine to
+  forward port 1317 listening inside the container to port 1317 on the host
+  machine.
+- `-p 26657:26657` maps RPC server port 26657 (tendermint) on the host machine
+  to port 26657 in Docker.
+- After the blockchain is started, open `http://localhost:26657` to see the
+  Tendermint API.
+- The `-v` flag specifies for the container to access the application's source
+  code from the host machine, so it can build and run it.
+
+## Versioning
+
+You can specify which version of Ignite CLI to install and run in your Docker
+container.
+
+### Latest version
+
+- By default, `ignite/cli` resolves to `ignite/cli:latest`.
+- The `latest` image tag is always the latest stable [Ignite CLI
+  release](https://github.com/ignite/cli/releases).
+
+For example, if latest release is
+[v0.25.2](https://github.com/ignite/cli/releases/tag/v0.25.2), the `latest` tag
+points to the `0.25.2` tag.
+
+### Specific version
+
+You can specify to use a specific version of Ignite CLI. All available tags are
+in the [ignite/cli
+image](https://hub.docker.com/r/ignite/cli/tags?page=1&ordering=last_updated) on
+Docker Hub.
+
+For example:
+
+- Use `ignitehq/cli:0.25.2` (without the `v` prefix) to use version `0.25.2`.
+- Use `ignitehq/cli` to use the latest version.
+- Use `ignitehq/cli:main` to use the `main` branch, so you can experiment with
+  the upcoming version.
+
+To get the latest image, run `docker pull`.
+
+```bash
+docker pull ignitehq/cli:main
+```