From e50e48c3feece6c5dda8d77a529253dc390ccdbe Mon Sep 17 00:00:00 2001 From: nsjames Date: Tue, 20 Jun 2023 17:38:49 +0100 Subject: [PATCH 1/3] table of contents, macos steps, docker cleanup --- .idea/.gitignore | 5 ++ .idea/DUNES.iml | 12 +++++ .idea/modules.xml | 8 +++ .idea/vcs.xml | 6 +++ README.md | 129 ++++++++++++++++++++++++---------------------- 5 files changed, 99 insertions(+), 61 deletions(-) create mode 100644 .idea/.gitignore create mode 100644 .idea/DUNES.iml create mode 100644 .idea/modules.xml create mode 100644 .idea/vcs.xml diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 00000000..b58b603f --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,5 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Editor-based HTTP Client requests +/httpRequests/ diff --git a/.idea/DUNES.iml b/.idea/DUNES.iml new file mode 100644 index 00000000..0c8867d7 --- /dev/null +++ b/.idea/DUNES.iml @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 00000000..6c248727 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 00000000..94a25f7f --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/README.md b/README.md index bfce6526..62a33458 100644 --- a/README.md +++ b/README.md @@ -6,19 +6,28 @@ Docker Utilities for Node Execution and Subsystems (DUNES) is a tool to abstract [CDT](https://github.com/AntelopeIO/cdt), and other services/tools to perform the functions of node management, compiling smart contracts, running tests, and several other common tasks required to develop smart contracts on [Antelope](https://github.com/AntelopeIO) blockchains. -## Getting started -First we must install [Docker](https://docs.docker.com/get-docker/). +## Table of Contents -![Get Docker](docs/images/get-docker.png) +- [Docker](#installing-docker) +- [Installing on Linux](#dunes-linux) +- [Installing on Windows](#dunes-windows) +- [Installing on MacOS](#dunes-macos) +- [Post installation](#post-installation) +- [DUNES commands](#dunes-commands) +- [Learn general concepts](#concepts) +- [Node management](#node-management) +- [Account management](#account-management) +- [Bootstrapping nodes](#bootstrapping-nodes) +- [System-level commands](#system-level-commands) -Once you select the Docker Desktop for your operating system the installation process is very straight forward. +## Docker -### Linux - docker setup +DUNES relies on Docker, so you must first install [Docker](https://docs.docker.com/get-docker/) for your operating system. -Start your Docker Desktop, visit its settings and add the root directory of the host system to shared directories. +![Get Docker](docs/images/get-docker.png) -![Docker Desktop settings](docs/images/linux_docker_settings_shares.png) +Once you select the Docker Desktop for your operating system the installation process is very straight forward. Check the installation with the command @@ -26,30 +35,20 @@ Check the installation with the command $ docker --help ``` -This should display the list of commands and features. If it fails with unknown command the installation did not work correctly. - -### Several useful facts for working with Docker in Linux - -The Docker installation package consists of two independent products which install together: Docker Engine and Docker Desktop. +This should display the list of commands and features. +If it fails with unknown command the installation did not work correctly. -It is easy to confuse which system you are currently working with. +### Adding a shared directory -Docker Desktop has a built-in daemon which works in parallel with the `dockerd` daemon. +In order to have a good experience with Docker and DUNES, you should add a root directory of the host +system to the list of shared directories in Docker Desktop settings. -Docker Desktop keeps its settings and storage of images and containers in the user's home directory. +This will allow you to share files between the host system and your Docker containers. -Docker Engine keeps its settings and storage in the system directories. - -Docker Desktop works with userns-remap turned on only. It is hardcoded and can't be changed. - -Docker Desktop has a built-in daemon which works in parallel with the `dockerd` daemon. - -Therefore, to successfully work with DUNES you should: +![Docker Desktop settings](docs/images/linux_docker_settings_shares.png) ->+ Download the latest DUNES release on [Windows](#dunes-windows) or on [Linux](#dunes-linux "Linux") ->+ Add a root directory of the host system to the list of shared directories in Docker Desktop settings. ->+ Keep Docker Desktop running all the time when you work with DUNES. +## Installing on Linux #### Python 3 @@ -62,7 +61,8 @@ Depending on the distro you are using will determine which `python3` package to | Centos | python3 | | Arch | python | -### DUNES installation on Linux + +#### Installation using DEB package This is the fastest way to get started. From the [latest release](https://github.com/AntelopeIO/DUNES/releases/latest) page, download DUNES `*.deb` file or visit the [release tags](https://github.com/AntelopeIO/DUNES/releases) page to download specific version of DUNES deb package. @@ -73,7 +73,7 @@ sudo apt-get install -y ~/Downloads/dunes*.deb ``` Your download path may vary. -#### Alternative: DUNES installation using RPM package +#### Installation using RPM package From the [latest release](https://github.com/AntelopeIO/DUNES/releases/latest) page, download DUNES `*.rpm` file. @@ -83,17 +83,6 @@ sudo rpm -i ~/Downloads/dunes*.rpm ``` Your download path may vary. -#### DUNES installation - verification - -Finally, verify DUNES was installed correctly in `/usr/opt/DUNES/`. First [add DUNES to Path](#add-dunes-to-path) and check: -```bash -dunes --version -``` -You should see a DUNES version number. For example: -``` -v1.0.0 -``` - Latest DUNES docker image will be downloaded automatically when starting the DUNES as described in [Node management](#node-management). #### Add DUNES to PATH @@ -102,15 +91,8 @@ To keep from having to install files to the user's system, the preferred method ```console $ echo "PATH=:$PATH" >> .bashrc ``` -### Rebuild the DUNES image - -If you want to rebuild the DUNES image pick your preferred terminal application and input the following command: - -```console -/DUNES$ python3 ./bootstrap.py -``` -### Windows 10 & 11 +## Installing on Windows In some cases (i.e. running Docker from VirtualBox) you might need to turn on hardware virtualization in the BIOS of your computer. Docker should give an error stating this failure. Because of the variance of motherboards and BIOS implementations we can't give a clear description as to how to turn this on, @@ -133,7 +115,7 @@ Visit the download page for [Python 3](https://python.org/downloads). You should Make sure you mark "Add Python to PATH" during installation. After installation open `cmd.exe` and verify `python --version` returns current Python version. -#### DUNES installation on Windows +#### Installation using Chocolatey 1. Install [Chocolatey](https://docs.chocolatey.org/en-us/choco/setup). 2. Download latest `*.nupkg` from [latest release](https://github.com/AntelopeIO/DUNES/releases/latest) page. @@ -162,25 +144,50 @@ choco install .\dunes.1.1.2.nupkg -y Due to current Docker Desktop limitations DUNES supports only `C:/` disk drive, so all your DUNES projects or workspace needs to be on `C:/` drive. -### Mac OS +## Installing on MacOS + +Download a version of DUNES by heading over to the [releases](https://github.com/AntelopeIO/DUNES/releases) and grabbing a `tar.gz` file. + +Extract the archive and copy the path of the directory to your clipboard. -When finished installing. Check the installation with the command. -```console -$ docker --help -``` #### Python 3 -Python 3 should already be installed. +If you don't already have Python installed, you can install it using homebrew: + +```shell +brew install python +``` #### Add DUNES to PATH -To keep from having to install files to the user's system, the preferred method of usage is to add this directory to your `PATH`. +Replace the `` below with the directory you copied to your clipboard. ```console $ echo "PATH=:$PATH" >> .bashrc ``` -## DUNES commands +## Post installation + +### Verification of your installation + +Finally, verify DUNES was installed correctly in `/usr/opt/DUNES/`. First [add DUNES to Path](#add-dunes-to-path) and check: +```bash +dunes --version +``` +You should see a DUNES version number. For example: +``` +v1.0.0 +``` + +### Rebuild the DUNES image + +If you want to rebuild the DUNES image pick your preferred terminal application and input the following command: + +```console +/DUNES$ python3 ./bootstrap.py +``` + +## DUNES commands --- @@ -383,7 +390,7 @@ Upgrades DUNES docker image to the latest version

-## Concepts and operations +## Concepts and operations The core concept of this utility is to abstract over Leap programs such as `nodeos` and `cleos`, CDT, etc. As such some of the commands might seem restrictive. Please take note that if you find any of the commands to be too @@ -403,7 +410,7 @@ The drive/directory that your workspace is in is mapped into the container and p So on Windows this would be `/host/Users//` (NOTE: on Windows only `C:/` disk drive is supported). On Linux and Mac this would be something like `/host/home//`. -## Node management +## Node management For all of the deployment commands and most of the commands in general you have to have at least one node up and running. @@ -457,7 +464,7 @@ and try to replicate things like an EOS mainnet or the like. These types of topologies are out of the scope of this README but please look at documentation for Leap node configurations. -## Contract development +## Contract development ### CMake contract development @@ -545,7 +552,7 @@ As we move forward we hope to greatly expand upon these utilities. The services through the docker container are exposed at 8888 for http, 9876 for p2p and 8080 for SHiP. You will need to ensure the running node is using those ports. -## Account management +## Account management Earlier we saw a simple way above to create accounts using `--create-account `. @@ -566,7 +573,7 @@ $ dunes --create-account bucky foo EOS7qPSKJhqygQTSNjMy8aH6TL6NtsYJnBJ7fxh7Y4SFL Clearly you don't want to do this with real private keys or sensitive accounts. -## Bootstrapping nodes +## Bootstrapping nodes At some point you will want to activate protocol features for your chain. @@ -599,7 +606,7 @@ This will do the same as `--bootstrap-system` but additionally set the contracts from [reference-contracts](https://github.com/AntelopeIO/reference-contracts) and create the correct accounts needed for those. -## System-level commands +## System-level commands ### Wallet From 847979c70fd5e67a965a2b92051e7012e9a886f0 Mon Sep 17 00:00:00 2001 From: nsjames Date: Tue, 20 Jun 2023 17:44:01 +0100 Subject: [PATCH 2/3] clarify installation steps in toc --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 62a33458..33b96796 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,12 @@ running tests, and several other common tasks required to develop smart contract ## Table of Contents -- [Docker](#installing-docker) -- [Installing on Linux](#dunes-linux) -- [Installing on Windows](#dunes-windows) -- [Installing on MacOS](#dunes-macos) -- [Post installation](#post-installation) +- Installation + - [Docker](#installing-docker) + - [Installing on Linux](#dunes-linux) + - [Installing on Windows](#dunes-windows) + - [Installing on MacOS](#dunes-macos) + - [Post installation](#post-installation) - [DUNES commands](#dunes-commands) - [Learn general concepts](#concepts) - [Node management](#node-management) From e4d186689f672c83442ae4353e0a97df024b3929 Mon Sep 17 00:00:00 2001 From: nsjames Date: Wed, 21 Jun 2023 13:22:41 +0100 Subject: [PATCH 3/3] remove .idea folder and add to gitignore --- .gitignore | 3 +++ .idea/.gitignore | 5 ----- .idea/DUNES.iml | 12 ------------ .idea/modules.xml | 8 -------- .idea/vcs.xml | 6 ------ 5 files changed, 3 insertions(+), 31 deletions(-) delete mode 100644 .idea/.gitignore delete mode 100644 .idea/DUNES.iml delete mode 100644 .idea/modules.xml delete mode 100644 .idea/vcs.xml diff --git a/.gitignore b/.gitignore index 27f6dbe8..66c95cff 100644 --- a/.gitignore +++ b/.gitignore @@ -132,3 +132,6 @@ dmypy.json .pyre/ example/test/build + +# Jetbrains products +.idea diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index b58b603f..00000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml -# Editor-based HTTP Client requests -/httpRequests/ diff --git a/.idea/DUNES.iml b/.idea/DUNES.iml deleted file mode 100644 index 0c8867d7..00000000 --- a/.idea/DUNES.iml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index 6c248727..00000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 94a25f7f..00000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file