This repository demonstrates the eosio platform running a blockchain as a local single node test net with a simple DApp, NoteChain.
⚠️ Important! Since Jan 1st 2019, eosio/eos-dev docker image in docker hub is deprecated. Starting from that time, eosio-project-boilerplate-simple is building its own docker image based on eos and eosio.cdt instead of pulling eosio/eos-dev. ⚠️
NoteChain demonstrates the eosio platform running a blockchain as a local single node test net with a simple DApp, NoteChain. NoteChain allows users to create and update notes. This guide uses scripts, containing relevant commands, which will show you how to install, build and run NoteChain, and by doing so will demonstrate:
Github eosio-project-boilerplate-simple (https://github.com/EOSIO/eosio-project-boilerplate-simple) contains the UI and Smart Contract code, as well as setup scripts which will initialise and start all the necessary components.
The sample DApp demonstrates storing data in multi index table and retrieving this data into the web based UI. NoteChain is a simple note taking application, where notes are tied to user accounts. For this example, all accounts are pre-created by scripts and the account details are displayed at the bottom of the NoteChain UI.
Each account can then be used to add a note to the blockchain. The individual notes are saved in a multi-index table and for simplicity are of fixed width. Each account may have one note attached to it, adding a note to an account with an existing note will replace the existing note with a new note.
Any private keys you see in this repository are for demo purposes only. For a real DApp NEVER expose the private keys.
Make sure Docker and Node.js are installed
The DApp and eosio will occupy the ports 3000, 8888 and 9876. Make sure nothing else is already running on these ports.
Clone the repository:
sh git clone https://github.com/EOSIO/eosio-project-boilerplate-simple.git
The following guide assumes you are using macOS.
In this section we provide a single command script to run all the commands needed to start both the blockchain and UI. For more detail on each component see the
The above command will execute the following in sequence:
To stop, press
ctrl+con your keyboard, and execute:
sh docker stop eosio_notechain_container
In this section we will describe in detail each script used to run the NoteChain environment in details.
Executing the above shell script verifies that docker and node.js are installed. It then builds
eosio-notechaindocker image if it has never been built before (which contains a full version of the eosio blockchain), removes any previous instances of this docker container and installs node packages for the frontend react app.
After the initialisation, two terminal windows are required, both opened in the repository directory
running the blockchain
For the first (blockchain) terminal window, running
The log of blockchain will be displayed on your screen. eosio is now running and starts producing blocks.
running the DApp
For the second (frontend) terminal window, running
sh ./start_frontend.shwill open a browser session connecting to http://localhost:3000/ showing the react app. You can try to add or remove notes using one of the pre-created accounts with its key on the website. This react app will interact with the smart contract, performing transactions, which are written to the blockchain, which stores note data in the multi index table of the smart contract running on your local nodeos.
stopping the blockchain
In the first (blockchain) terminal window, press
ctrl+con your keyboard, the log will stop printing. And then execute:
sh docker stop eosio_notechain_container
This action will take a few seconds. The blockchain will be stopped.
stopping the DApp
In the second (frontend) terminal window, press
ctrl+con your keyboard. The frontend react app will be stopped.
restarting the blockchain
In the first (blockchain) terminal window, execute this command:
The blockchain will be resumed automatically and the log will be outputted to the terminal.
restarting the DApp
In the second (frontend) terminal window, you can restart the frontend react app by executing:
First, you need to stop the blockchain (as above) and then execute:
This removes all data on the blockchain, including accounts, deployed smart contracts, etc... The block count will be reset when you start the blockchain again.
noteChain // project directory ├── eosio_docker │ ├── * contracts // this folder will be mounted into docker │ │ └── notechain │ │ └── notechain.cpp // the main smart contract │ ├── * data // blockchain data, generated after first_time_setup.sh │ │ ├── blocks │ │ ├── state │ │ └── initialized // to indicate whether the blockchain has been initialized or not │ └── * scripts // scripts and utilities for docker container │ ├── accounts.json // pre-create account names, public and private keys (for demo only) │ ├── continue_blockchain.sh // continue the stopped blockchain │ ├── create_accounts.sh // create account data │ ├── deploy_contract.sh // deploy contract │ └── init_blockchain.sh // script for creating accounts and deploying contract inside docker container └── frontend ├── node_modules // generated after npm install ├── public │ └── index.html // html skeleton for create react app ├── src │ ├── pages │ │ └── index.jsx // an one-pager jsx, include react component and Material-UI │ └── index.js // for react-dom to render the app ├── package-lock.json // generated after npm install └── package.json // for npm packages
The DApp consists of two parts. eosio blockchain and frontend react app. These can be found in:
Users interact with the UI in client and sign the transaction in frontend. The signed transaction (which is an
updateaction in this demo DApp) is sent to the blockchain directly. After the transaction is accepted in blockchain, the note is added into the multi index table in blockchain.
The UI, index.jsx, reads the notes data directly from nodeos using 'getTableRows()'. The smart contract, notechain.cpp, stores these notes in the multi index table using 'emplace()'' and 'modify()'.
Docker is used to wrap the eosio software inside and run a container (instance) from an image (
eosio-notechain). To work with the blockchain directly, by running the scripts or using a cleos command line, you need to go into the container bash.
Go into container bash:
sh docker exec -it eosio_notechain_container bashWe have already set the container working directory to
/opt/eosio/bin/, you could run cleos command in this directory directly. For documentation of cleos: https://developers.eos.io/eosio-nodeos/docs/cleos-overview
You can also look at the
deploy_contract.shscripts for examples of cleos command lines.
To exit from inside the container bash:
The smart contract can be found at
eosio_docker/contracts/notechain/notechain.cpp(host environment), you can edit this smart contract. You will then need to compile and deploy the contract to the blockchain.
To save time, we prepared some scripts for you. Execute the scripts in the container bash (see above.)
The following script will help you to unlock the wallet, compile the modified contract and deploy to blockchain. 1st parameter is the contract name; 2nd parameter is the account name of the contract owner, 3rd and 4th parameter references wallet related information that was created during the
Inside docker container
sh ./scripts/deploy_contract.sh notechain notechainacc notechainwal $(cat notechain_wallet_password.txt)
After running this script the modified smart contract will be deployed on the blockchain.
Remember to redeploy the NoteChain contract each time you modify it using the steps above!
The UI code can be found at
frontend/src/pages/index.jsx(host environment), once you have edited this code the frontend react app compile automatically and the page on browser will be automatically refreshed. You can see the change on the browser once the browser finishes loading.
If you are more familiar with docker, you could use the docker commands below to have better control with the whole environment. Below are the explanations of each of the commands:
Execute below command in
Run container from
eosio-notechainimage by mounting contracts / scripts to the container with running the initblockchain.sh script as the process. The initblockchain.sh script run the local node of the blockchain and initializes wallets / contract / data.
sh docker run --rm --name eosio_notechain_container \ -p 8888:8888 -p 9876:9876 \ --mount type=bind,src="$(pwd)"/contracts,dst=/opt/eosio/bin/contracts \ --mount type=bind,src="$(pwd)"/scripts,dst=/opt/eosio/bin/scripts \ --mount type=bind,src="$(pwd)"/data,dst=/mnt/dev/data \ -w "/opt/eosio/bin/" eosio-notechain:eos2.0.5-cdt1.6.2 /bin/bash -c "./scripts/init_blockchain.sh"
Output and follow docker console logs:
sh docker logs eosio_notechain_container --follow
Remove the container (will remove all wallets / contracts / data), useful if you want to re-init the whole DApp.
sh docker rm -f eosio_notechain_container
Stop the container (see below troubleshoot section to see how to pause and continue the blockchain):
sh docker stop eosio_notechain_container