Skip to main content

Installing Giveth TRACE for Local Development

This is a comprehensive guide that will walk through new contributors on how to run Giveth TRACE locally. We'll be dealing with 2 repos found in the Giveth Github the giveth-dapp for the front-end and feathers-giveth for smart contract interfacing and the back-end database.

Feathers Installation#

Feathers Installation Header

Packages and Applications Needed:#

  • yarn
  • NodeJS v10.24.0
  • MongoDB
  • Redis
  • MetaMask

Linux#

If your operating system is any distrubution of linux you can use an All-in-One installation scripts special thanks to Dapp contributor Jurek Brisbane, available here along with a youtube video

Any OS#

  1. Click Star on this repo near the top-right corner of this web page (if you want to).
  2. Join our Contributors Discord if you haven't already.
  3. Fork this repo by clicking Fork button in top-right corner of this web page. Continue to follow instruction steps from your own feathers-giveth repo.
  4. The rest of these steps must be done from your machine's command line. Clone your own "feathers-giveth" repo. Copy the link from the "Clone or download" button near the top right of this repo's home page.
    git clone git@github.com:Giveth/feathers-giveth.git
  5. Change directories to feathers-giveth:
    cd feathers-giveth/
  6. Make sure you have NodeJS (v10.24.0), yarn (v0.27.5 or higher), and npm (5.4.1 or higher) installed.
  7. Install dependencies from within feathers-giveth directory:
    yarn install
  8. Install Mongo (we recommend installing via Brew)
  9. Run Mongo in a terminal window mongod or in the background mongod --fork --syslog
  10. Install Redis (we recommend install via Brew brew install redis)
  11. Run Redis in terminal window redis-server or in the background redis-server --daemonize yes
  12. (optionally) Install IPFS (we recommend installing via Brew)
    *If you don't install ipfs, image uploading will be affected. You can update the config ipfsGateway value to use a public ipfs gateway ex. https://ipfs.io/ipfs/, however your uploads will be removed at some point

Run server#

The feathers server will need to connect to an ethereum node via websockets. Typically this will be a local TestRPC instance. The configuration param blockchain.nodeUrl is used to establish a connection. The default nodeUrl is ws://localhost:8545

  1. We need to deploy any contract to that we intend to call. NOTE: The following cmd will clear the data dir, thus starting off in a clean state.

    yarn deploy-local

    After deploying local, make sure to copy-paste the MiniMeToken address in default.json

  2. We provide an easy way to start the bridge & 2 ganache-cli instances. VERY IMPORTANT: this command enables Home Ganache and Foreign Ganache networks, if you are using MetaMask you will need to add a Custom RPC to your networks config,http://localhost:8546 will be Foreign Ganache, and Home Ganache is normally added by default which is http://localhost:8545 if needed.

    yarn start:networks
  3. Since the bridge & ganache-cli is now running, open a new terminal window and navigate to the same feathers-giveth directory.

  4. Optionally open a new terminal window and start the ipfs daemon

    ipfs daemon
  5. Run db migration files ( if this the first time you want to start application, it's not needed to run migrations)

    ./node_modules/.bin/migrate-mongo up
  6. Start your app

    yarn start

Kill Ganache#

If you run into errors like wallet balance not loading, it is very likely that Ganache is stuck netstat -vanp tcp | grep 8545 Find the process that is listening on *.8545 and 127.0.0.1.8545 and kill it with kill -9 PID (which is in the last colomn)

IPFS Support#

If the ipfsApi is a valid ipfs node that we can connect to, we will pin every ipfs hash that is stored in feathers. We currently do not remove any orphaned (hashes with no references in feathers) ipfs hashs. In the future we will provide a script that you can run as a cronjob to unpin any orphaned hashes.

Video Walkthrough#

Video tutorial walkthrough here: https://tinyurl.com/y9lx6jrl

Scripts#

The feathers-giveth/scripts directory contains a few scripts to help development.

  • deploy.js - deploys a new vault & liquidPledging contract

  • getState.js - prints the current state of the deployed vault & liquidPledging contracts.

  • confirm.js - confirms any payments that are pending in the vault

  • makeUserAdmin.js - make a user admin

Testing#

Simply run yarn test and all your tests in the /src directory will be run. It's included some integration tests so for running tests, you need to run a mongodb in your local system (on port 27017)

Debugging#

You can control the logging level with the LOG_LEVEL env variable. Available levels can be found at: https://github.com/winstonjs/winston/tree/2.x#logging-levels

To enable debug logging simply start the server with LOG_LEVEL=debug yarn start

Production#

We use docker-compose for orchestration of our docker containers in our production servers.

  • make Make sure you have a file named production.json in config folder
  • Install docker and docker-compose on your server
  • run this command: docker-compose -f docker-compose-production.yml up -d

PS: It's good to see Github Actions config(./.github/workflows/CI-CD.yml) to better understand the deployment structure

RSK#

  1. You will need to download the rsk node. After installing, you will run the node w/ the regtest network for local development.

    java -jar rskj-core-0.5.2-ORCHID-all.jar co.rsk.Start --regtest

    or

    java -Drsk.conf.file=rsk.conf -jar rskj-core-0.5.2-ORCHID-all.jar co.rsk.Start
  2. We need to deploy any contracts that we intend to call. NOTE: You will also need to ensure that your rsk node is in a clean state (reset) for the configured addresses to be correct.

    npm run deploy-local:rsk
  3. Optionally open a new terminal window and start the ipfs daemon

    ipfs daemon
  4. Start your app

    yarn start:rsk

Audit Log#

The Audit log system logs every Create, Update, Patch and Remove on Campaigns, Traces, Events, Users, PledgeAdmins, Communities, Donations For enabling audit log locally you should change enableAuditLog in config to true, then

  • cd elk
  • docker-compose up

And then after logging in localhost:5601 with user:elastic, password: changeme you can see the logs

Usage#

Each of these services are available via rest or websockets:

campaigns
communities
donations
donationsHistory
traces
uploads
users
emails
homePaymentsTransactions
subscriptions

If the server is using default configurations, you can see data for any of these services through your web browser at http://localhost:3030/SERVICE_NAME

PS: For accessing all features like creating communities and campaigns it's suggested to make isAdmin field true, for your user in you local MongoDb

Giveth DApp (Giveth TRACE front-end) Installation#

Giveth-DApp Installation Header

Getting Started#

In the following sections you will learn all you need to know to run the DApp locally and to start contributing. All the steps are also described in this amazing Video Tutorial Walkthrough by Oz.

Prerequisites#

  • NodeJS v10 LTS.
  • yarn (v1.22.10 or higher)
  • git

Install#

  1. Click Star on the giveth-dapp repo near the top-right corner of this web page (if you want to).
  2. Join us on Element or Discord if you haven't already.
  3. Fork this repo by clicking Fork button in top-right corner of this web page. Continue to follow instruction steps from your own giveth-dapp repo.
  4. Clone your own "giveth-dapp" repo. Copy the link from the "Clone or download" button near the top right of this repo's home page.
  5. The rest of these steps must be done from your machine's command line. See the OSX and Linux or Windows section to continue.

OSX and Linux#

If your operative system is any distribution of linux you can use an All-in-One installation scripts special thanks to Dapp contributor Jurek Brisbane, available here along with a youtube video, otherwise try the following:

  1. From the desired directory you wish to copy the "giveth-dapp" folder with source files to.
    git clone git@github.com:Giveth/giveth-dapp.git
    NOTE: Please use develop branch for contributing.
    git clone -b develop git@github.com:Giveth/giveth-dapp.git
  2. Change directories to giveth-dapp:
    cd giveth-dapp
  3. Make sure you have NodeJS (v10) and yarn (v1.22.10 or higher) installed.
  4. Install dependencies from within giveth-dapp directory:
    yarn install
  5. That is it, you are now ready to run the giveth-dapp! Head to the Run DApp section for further instructions.

Windows#

  1. Install the latest version of Python from this Link. (make sure python is added to $PATH)
  2. Install Microsoft Visual Studio 2017 (double-check the version) from this link. Giveth-Dapp needs the node-gyp module and node-gyp needs VS C++ 2017 Build Tools to be installed.
  3. After downloading, install the packages marked from this image.
  4. Then run command below in command prompt
    npm config set msvs_version 2017
  5. After installing the above, you should install NodeJS version 10 LTS (it is better to be v10.24.1 LTS).
  6. Download and run the node-v10.24.1-x64.msi installer and then continue through the installation as normal. Be sure to have the "Enable in PATH" option enabled before installing.
  7. Open the command line in administrator mode by right-clicking on the cmd.exe application and selecting "Run as administrator"
  8. In the administrator command prompt, change to the directory where you want to store this repository.
    cd C:\some\directory\for\repositories
  9. Double-check the node version with CMD command:
    node -v
  10. After that, install the latest version of Yarn. Be careful not to install packages with NPM. If you have already tried "npm install", you should first delete "node modules" folder.
    yarn install
  11. That is it, you are now ready to run the giveth-dapp!

Run#

  1. The Giveth dapp will need to connect to a feathers-giveth server. Follow the feathers-giveth readme instructions to install and run server before proceeding further. Alternatively, you could change the configuration to connect to the develop environment, see the Configuration section.

  2. Start the dapp.

    yarn start
  3. Once the dapp is up in your browser, click "Sign In" from the main menu.

  4. For testing locally, choose any of the wallet files found in the giveth-dapp/keystores/ folder using the wallet password: password. DO NOT USE THESE ON ANY MAINNET EVMs.

  5. Using the test token To use the test token you need to import the keystore.json you use for your account to MetaMask. After importing, click on 'Add token' > 'Custom token' and enter the MiniMe Token address that can be found when deploying the contracts (should be 0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab by default but make sure to check) The token balance should show up automatically, and the token symbol is MMT. However, in the dApp the token symbol is referred to as ANT, b/c the dapp needs to be able to fetch a conversion rate.

NOTE: When resetting feathers or redeploying the contracts, you need to remove the keystore from metamask and follow this procedure again.

Build#

yarn run build

NOTE: due to some web3 libraries that are not transpiled from es6, we have to use our giveth-react-scripts fork of react-scripts .

Configuration#

The DApp has several node environment variables which can be used to alter the DApp behaviour without changing the code. You can set them through .env or .env.local files in the DApp folder.

Variable nameDefault ValueDescription
PORT3010Port on which the DApp runs
REACT_APP_ENVIRONMENT'localhost'To which feathers environment should the DApp connect. By default it connects to localhost feathers. Allowed values are: localhost, develop, release, alpha, mainnet. See Deployment Environments.
REACT_APP_DECIMALS8How many decimal should be shown for cryptocurrency values. Note that the calculations are still done with 18 decimals.
REACT_APP_FEATHERJS_CONNECTION_URLDiffers per REACT_APP_ENVIRONMENTOverwrites the environment injected feathers connection URL.
REACT_APP_NODE_CONNECTION_URLDiffers per REACT_APP_ENVIRONMENTOverwrites the EVM node connection URL for making EVM transactions.
REACT_APP_LIQUIDPLEDGING_ADDRESSDiffers per REACT_APP_ENVIRONMENTOverwrites the Liquid Pledging contract address.
REACT_APP_DAC_FACTORY_ADDRESSDiffers per REACT_APP_ENVIRONMENTOverwrites the Communities contract address.
REACT_APP_CAMPAIGN_FACTORY_ADDRESSDiffers per REACT_APP_ENVIRONMENTOverwrites the Campaign Factory contract address.
REACT_APP_MILESTONE_FACTORY_ADDRESSDiffers per REACT_APP_ENVIRONMENTOverwrites the MilestoneFactory contract address.
REACT_APP_TOKEN_ADDRESSESDiffers per REACT_APP_ENVIRONMENTOverwrites the bridged token addresses. This is a JSON object string w/ token name : token address.
REACT_APP_BLOCKEXPLORERDiffers per REACT_APP_ENVIRONMENTOverwrites the block explorer base URL. The DApp assumes such blockexplorer api is \<BLOCKEXPLORER\>/tx/\<TRANSACTION_HASH\>
REACT_APP_DEFAULT_GASPRICE10Overwrites the default gasPrice that is used if ethgasstation service is down. The value is in gwei.
REACT_APP_ANALYTICS_KEY""Overwrites Segment analytics key

Example of .env.local file that makes the DApp run on port 8080, connects to the develop environment and uses custom blockexplorer:

PORT=8080
REACT_APP_ENVIRONMENT='develop'
REACT_APP_BLOCKEXPLORER='www.awesomeopensourceexplorer.io'

The rest of the configuration can be found in configuration.js

Analytics#

Segment Analytics can be enabled by setting REACT_APP_ANALYTICS_KEY

Query Strings#

The milestone creation/proposal view now supports query string arguments! The following arguments are available:

ArgumentExpected ValuesType
titleThe title of the milestonestring
descriptionThe description of the milestonestring
recipientAddressThe address of the recipientstring
reviewerAddressThe address of the reviewerstring
selectedFiatTypeA valid fiat type (i.e. USD)string
dateA valid milestone date stringstring
tokenA valid token symbol (i.e. DAI)string
tokenAddressA valid token addressstring
maxAmountA valid max amount of ETH or tokennumber
fiatAmountA valid max amount of fiat (dependant on selectedFiatType)number
isCappedDetermines whether the milestone should be capped0 or 1 (boolean)
requireReviewerDetermines whether the milestone should require a reviewer0 or 1 (boolean)

Local Development#

At first you would like to run the DApp locally. When running testrpc locally in deterministic mode, you can use any of the keystores in the giveth-dapp/keystores as your wallet. This will provide you access to the testrpc accounts for local development. Each keystore uses the same password: password. DO NOT USE THESE ON ANY MAINNET EVMs

The keystores are seeded with 10.000 ANT tokens for testing donations. To get started with testing donations, make sure to add your account's keystore to MetaMask and swith MetaMask to Ganache. The donation modal should then show the appropriate balance when donating in ANT tokens.

NOTE: If you get a nonce error in MetaMask or if the dapp fails to load with your metamask unlocked, it could be b/c metamask is confused. You should go to "settings" -> "Reset Account" in MetaMask in order to reset the nonce & cached account data.

Development and PR Testing#

  1. The Giveth Dapp is auto deployed from the develop branch and is live on Rinkeby develop.giveth.io. All pull requests are autodeployed and the PR preview will be generated upon submission. To learn how to access PR previews see Development Process & Quality Assurance on our wiki.
  2. In order to use the dapp you will need to create account. If this is your first time, click "sign up" to create an account. If you already have a valid keychain file, use it to sign in.
  3. You will need test ether on the Rinkeby network. Go to the "wallet" page to see your new address (0x..). Copy that address and use the faucet to get some: https://faucet.rinkeby.io/

Deployment Environments#

At Giveth, we are using the gitflow branching model to deploy to 4 different environments.

NameBlockchainBranch DeployedAuto DeployUse
mainnetEthereum Main NetworkmasternoMain network deployment for now abandoned due to high transaction costs until sustainable solution is found.
alphaRinkeby Test NetworkmasternoEnvironment used as a production version until scalability is resolved.
releaseRinkeby Test NetworkreleaseyesEnvironment for release candidate quality control testing by non-devs.
developRinkeby Test NetworkdevelopyesDevelopment environment for integrating new features. Feature and pull request branches are also automatically deployed to this environment.

You can change the environment to which the DApp connects through the node environment variables. See the Configuration section for more details.

Last updated on by Mitch