description: Pantheon private network quickstart tutorial # Private Network Quickstart Tutorial The Private Network Quickstart uses the Pantheon Docker image to run a private network of Pantheon nodes managed by Docker Compose. !!! important The Private Network Quickstart runs a private network suitable for education or demonstration purposes. The Private Network Quickstart is not intended for running production networks. ## Prerequisites To run this tutorial, you must have the following installed: - MacOS or Linux !!! important The Private Network Quickstart is not supported on Windows. If using Windows, run the quickstart inside a Linux VM such as Ubuntu. - [Docker and Docker-compose](https://docs.docker.com/compose/install/) - [Git command line](https://git-scm.com/) - [Curl command line](https://curl.haxx.se/download.html) - A web browser that supports [Metamask](https://metamask.io/) (currently Chrome, Firefox, Opera, and Brave), and has the MetaMask plug-in installed. This tutorial uses screenshots from Brave. ## Clone Pantheon Quickstart Source Code Clone the repository from the `pantheon-quickstart` with the version matching Pantheon version, currently `{{ versions.quickstart }}`: ```bash tab="Linux/MacOS" git clone --branch {{ versions.quickstart }} https://github.com/PegaSysEng/pantheon-quickstart.git ``` ## Build Docker Images and Start Services and Network This tutorial uses [Docker Compose](https://docs.docker.com/compose/) to assemble the images and run the private network. To build the docker images and run the containers, go to the `pantheon-quickstart` directory and run: ```bash tab="Linux/MacOS" ./run.sh ``` The `run.sh` script builds the images, and runs the containers. It also scales the regular node container to four containers to simulate a network with enough peers to synchronize. When the process ends, it lists the running services: !!! example "Docker-compose services list example" ```log ************************************* Pantheon Quickstart {{ versions.quickstart }} ************************************* List endpoints and services ---------------------------------- Name Command State Ports ----------------------------------------------------------------------------------------------------------------------------- quickstart_bootnode_1 /opt/pantheon/bootnode_sta ... Up 30303/tcp, 8545/tcp, 8546/tcp quickstart_explorer_1 nginx -g daemon off; Up 0.0.0.0:32770->80/tcp quickstart_minernode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp quickstart_node_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp quickstart_node_2 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp quickstart_node_3 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp quickstart_node_4 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp quickstart_rpcnode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 0.0.0.0:32769->8545/tcp, 0.0.0.0:32768->8546/tcp ``` Followed by a list of the endpoints: !!! example "Endpoint list example" ```log **************************************************************** JSON-RPC HTTP service endpoint : http://localhost:32770/jsonrpc * JSON-RPC WebSocket service endpoint : ws://localhost:32770/jsonws * Web block explorer address : http://localhost:32770 * **************************************************************** ``` - Use the **JSON-RPC HTTP service endpoint** to access the RPC node service from your Dapp or from cryptocurrency wallets such as Metamask. - Use the **JSON-RPC WebSocket service endpoint** to access the web socket node service from your Dapp. - Use the **Web block explorer address** to display the block explorer web application. View the block explorer by entering the URL in your web browser. To display the list of endpoints again, run: ```bash tab="Linux/MacOS" ./list.sh ``` ## Block Explorer This tutorial uses the [Alethio](https://aleth.io/) light block explorer. ### Run the Block Explorer Access the explorer by copying and pasting the `Web block explorer address` displayed when starting the private network to your browser. The block explorer displays a summary of the private network: ![Block Explorer](../Getting-Started/ExplorerSummary.png) Notice that the explorer indicates 6 peers: the 4 regular nodes, the mining node and the bootnode. Click the block number to the right of **Best Block** to display the block details: ![Block Details](../Getting-Started/ExplorerBlockDetails.png) You can explore blocks by clicking on the blocks under **Bk** on the left-hand side. You can search for a specific block, transaction hash, or address by clicking the magnifying glass in the top left-hand corner. ![Explorer Search](../Getting-Started/ExplorerSearch.png) ## Run JSON-RPC Requests You can run RPC requests on `rpcnode`, the node exposed to the host in order to listen for requests. This tutorial uses [cURL](https://curl.haxx.se/download.html) to make JSON-RPC requests. For the RPC URL, this tutorial uses the placeholder ``. When you run the tutorial, replace this placeholder with the JSON-RPC HTTP service endpoint provided when you list the endpoints. (For example, `http://localhost:32770/jsonrpc`.) The dynamic docker port mapping changes each time you run the network. ### Requesting the Node Version Run the following command from the host shell: ```bash curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' ``` The result specifies the client version: ```json { "jsonrpc" : "2.0", "id" : 1, "result" : "pantheon/{{ versions.pantheon_stable }}" } ``` Here we simply query the version of the Pantheon node, which confirms the node is running. Successfully calling this method shows that you can connect to the nodes via RPC. From here, you can walk through more interesting requests demonstrated in the rest of this section, or skip ahead to [Creating a Transaction Using MetaMask](#creating-a-transaction-using-metamask). ### Counting Peers Peers are the number of other nodes connected to the RPC node. Poll the peer count using `net_peerCount`: ```bash curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' ``` The result indicates that there are 6 peers: ```json { "jsonrpc" : "2.0", "id" : 1, "result" : "0x6" } ``` ### Requesting the Most Recently Mined Block Number Call `eth_blockNumber` to retrieve the number of the most recent block: ```bash curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``` The result provides the most recently mined block: ```json { "jsonrpc" : "2.0", "id" : 1, "result" : "0x8b8" } ``` The hexadecimal value `0x8b8` translates to `2232` in decimal, the number of blocks that have been mined so far. ### Checking the Miner Account Balance Call `eth_getBalance` to retrieve the balance of the mining address (coinbase) defined in the miner node: ```bash curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","latest"],"id":1}' ``` The result specifies the miner account balance: ```json { "jsonrpc" : "2.0", "id" : 1, "result" : "0x79f905c6fd34e80000" } ``` !!!info 0x79f905c6fd34e80000 = 2250000000000000000000 Wei (2250 Ether). !!!tip Use a [unit converter](https://etherconverter.online/) to easily translate values from Wei to Ether. Wait several seconds until new blocks are mined and call `eth_getBalance` again. The balance increases, meaning the miner address successfully received the mining reward. You can also view this information in the block explorer. It does exactly the same thing as this call, connecting to the RPC node using HTTP JSON-RPC, and displaying information on a web page. ## Creating a Transaction Using MetaMask Now let's use [MetaMask](https://metamask.io/) to send transactions. Before sending transactions, you need to create an account or use one of the accounts below created during the genesis of this private test network. {!global/test_accounts.md!} !!!note Pantheon doesn't implement [account management](../Using-Pantheon/Account-Management.md). To create your own account, you have to use a third-party tool such as MetaMask. After you sign in to MetaMask, connect to the private network RPC endpoint: 1. In the MetaMask network list, select **Custom RPC**. 1. In the **New RPC URL** field, enter the JSON-RPC HTTP service endpoint displayed when you started the private network. Save the configuration and return to the MetaMask main screen. Your current network is now set to the private network RPC node. [Import one of the existing accounts above into MetaMask](https://metamask.zendesk.com/hc/en-us/articles/360015489331-Importing-an-Account-New-UI-) using the corresponding private key. !!!note In this tutorial, we don't need to secure the keys, because we're using a private test network to send valueless Ether. However, be sure to secure your accounts in a real use case on the main Ethereum network (MainNet). Once this is done, [create another account from scratch](https://metamask.zendesk.com/hc/en-us/articles/360015289452-Creating-Additional-MetaMask-Wallets-New-UI-) to send Ether to. In MetaMask, select the new account and copy the account address by clicking the **...** gadget and selecting **Copy Address to clipboard**. In the block explorer, search for the new account by clicking on the magnifying glass and pasting the account address into the search box. The account is displayed with a zero balance. [Send Ether](https://metamask.zendesk.com/hc/en-us/articles/360015488991-Sending-Ether-New-UI-) from the first account (containing ether) to the new one (which has a zero balance). Refresh the browser page that displays the new account. The updated balance is displayed and reflects the transaction completed using MetaMask. ## Truffle Pet Shop Tutorial With a few modifications, we can use the private network in this tutorial as the blockchain for the [PetShop tutorial on Truffle website](https://truffleframework.com/tutorials/pet-shop). #### Prerequisites * [Node.js v6+ LTS and npm](https://nodejs.org/en/) (comes with Node) #### Install Truffle and Unpack Truffle Box Install Truffle : ```bash npm install -g truffle ``` !!! note `npm` requires `sudo` on Linux. Create a `pet-shop-tutorial` directory and move into it: ```bash mkdir pet-shop-tutorial cd pet-shop-tutorial ``` Unpack Pet Shop [Truffle box](https://truffleframework.com/boxes): `truffle unbox pet-shop` Install the [Truffle wallet](https://github.com/trufflesuite/truffle-hdwallet-provider): Note with Truffle 5, you must use a Web3 1.0 enabled wallet or the Truffle tasks will hang. ```bash npm install --save truffle-hdwallet-provider@web3-one ``` !!!note `npm` requires `sudo` on Linux. #### Modify the Pet Shop Example Modify the `truffle-config.js` file in the `pet-shop-tutorial` directory to add our wallet provider. The following shows the code with placeholders to change as directed below: ```javascript const PrivateKeyProvider = require("truffle-hdwallet-provider"); const privateKey = "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63"; const privateKeyProvider = new PrivateKeyProvider(privateKey, ""); module.exports = { // See // for more about customizing your Truffle configuration! networks: { development: { host: "127.0.0.1", port: 7545, network_id: "*" // Match any network id }, quickstartWallet: { provider: privateKeyProvider, network_id: "*" }, } }; ``` Replace `` with your HTTP RPC node endpoint (for example, `http://localhost:32770/jsonrpc`). The private key is the miner address, which contains Ether. Once this is done, follow the [Truffle tutorial steps](https://truffleframework.com/tutorials/pet-shop#directory-structure) up to Step 3 in the [Migration section](https://truffleframework.com/tutorials/pet-shop#migration). We're using the private network instead of [Ganache](https://truffleframework.com/ganache), so skip steps 3, 4, and 5 in the [Migration section](https://truffleframework.com/tutorials/pet-shop#migration). In step 4, specify the private network: ```bash truffle migrate --network quickstartWallet ``` Output similar to the following is displayed (your addresses will differ): ```log Using network 'quickstartWallet'. Running migration: 1_initial_migration.js Deploying Migrations... ... 0xfc1dbc1eaa14fa283c2c4415364579da0d195b3f2f2fefd7e0edb600a6235bdb Migrations: 0x9a3dbca554e9f6b9257aaa24010da8377c57c17e Saving successful migration to network... ... 0x77cc6e9966b886fb74268f118b3ff44cf973d32b616ed4f050b3eabf0a31a30e Saving artifacts... Running migration: 2_deploy_contracts.js Deploying Adoption... ... 0x5035fe3ea7dab1d81482acc1259450b8bf8fefecfbe1749212aca86dc765660a Adoption: 0x2e1f232a9439c3d459fceca0beef13acc8259dd8 Saving successful migration to network... ... 0xa7b5a36e0ebc9c25445ce29ff1339a19082d0dda516e5b72c06ee6b99a901ec0 Saving artifacts... ``` Search for the deployed contracts and transactions in the block explorer using the addresses displayed in your output. Continue with the Truffle tutorial steps in the [Testing the smart contract](https://truffleframework.com/tutorials/pet-shop#testing-the-smart-contract) section. To run the tests in the [Running the tests](https://truffleframework.com/tutorials/pet-shop#running-the-tests) section, specify the private network: ```bash truffle test --network quickstartWallet ``` Output similar to the following is displayed: ```log Using network 'quickstartWallet'. Compiling ./contracts/Adoption.sol... Compiling ./test/TestAdoption.sol... Compiling truffle/Assert.sol... Compiling truffle/DeployedAddresses.sol... TestAdoption ✓ testUserCanAdoptPet (2071ms) ✓ testGetAdopterAddressByPetId (6070ms) ✓ testGetAdopterAddressByPetIdInArray (6077ms) 3 passing (37s) ``` Continue with the Truffle tutorial steps in the [Creating a user interface to interact with the smart contract](https://truffleframework.com/tutorials/pet-shop#creating-a-user-interface-to-interact-with-the-smart-contract) section. We've already connected the private network to MetaMask, so you can skip the [Installing and configuring MetaMask](https://truffleframework.com/tutorials/pet-shop#installing-and-configuring-metamask) section. Continue with the regular tutorial steps from the [Installing and configuring lite-server](https://truffleframework.com/tutorials/pet-shop#installing-and-configuring-lite-server) section and finish the tutorial. When you adopt pets in the browser and approve the transaction in MetaMask, you'll be able to see the transactions in the block explorer. ## Stop / Restart Private Network without Removing Containers To shut down the private network without deleting the containers: ```bash tab="Linux/MacOS" ./stop.sh ``` This command stops the containers related to the services specified in the `docker-compose.yml` file. To restart the private network: ```bash tab="Linux/MacOS" ./start.sh ``` ## Stop Private Network and Remove Containers To shut down the private network and delete all containers and images created during the quickstart: ```bash tab="Linux/MacOS" ./remove.sh ```