EOS Local provides a really quick way to setup and maintain a local development environment for EOS dApps. It is a docker based dev environment that is guaranteed to work out-of-the-box across the different host operating systems: Mac OS, Windows, and Linux.
This project was inspired on MonsterEOS' EOSIO Dream Stack architecture that will allow you to develop EOS applications faster and easily scale as necessary.
EOS Local is a community-driven project led by EOS Costa Rica. We welcome contributions of all sorts. There are many ways to help, from reporting issues, proposing features, improving documentation, contributing code, design/ux proposals, etc.
Watch the EOS Local Introductory Video on YouTube
Table of Contents generated with DocToc
- Architecture
- Advantages
- Technical Specs
- Getting started
- Commands
- Chain Initialization and Database Migrations
- Directory Structure
- Designing and Developing EOS Smart Contracts
- Services
- Continuous Integration Process
- Using Cleos on EOS Local
- EOS Documentation & Resources
- Frequently Asked Questions
- Contributing
- Awesome Lists
- Support
- About EOS Costa Rica
- License
- Contributors
- Get started with EOS DApp development in less than 5 minutes with a single command.
- Focus on your features, not on configurations or integrating commonly used third party-services.
- Scalable microservices architecture.
- Deploy your dApp dedicated services easily to any infrastructure provider with containers.
- Ability to run multiple versions of EOS with different configuration with no conflicts.
- This project follows EOS DApp development best practices.
- Fully virtualized EOS blockchain development environment.
- Microservices architecture.
- Out-of-box services:
- EOS node with everything contract development and compilation.
- EOS fullnode with history.
- Demux service.
- GraphQL endpoint with GraphiQL.
- Postgres database.
- MongoDB database.
- Admin Mongo instance.
- PGWeb instance.
- Flyway service for Postgres DB migrations.
- Reactjs client with:
- Scatter integration.
- Lynx integration.
- EOS Account profile page.
- Material UI.
- GraphQL Apollo client.
- Services accessible through virtual host names both from host machine and within the docker network.
- Handy scripts for interacting with the local EOS services.
- Gulp as global task manager.
- Automated code linting and testing.
- Automated "seeding" of testing accounts and contract compilation.
- Continuous Integration and Deployment. ( Travis and Netlify )
- Kubernetes support ( coming soon eoscostarica#8 )
Note: at the moment we are not using a docker container for running the React client due to issues related to hot reloading the app efficiently
Important Disclaimer: This is a Work in Progress
Basic knowledge about Docker, Docker Compose, EOS and NodeJS is required.
Global Dependencies
- Docker https://docs.docker.com/install/.
At least 10GB RAM (Docker -> Preferences -> Advanced -> Memory -> 10GB or above) - Install node.js v10 on your machine. We recommend using nvm and avn to manage multiple node.js versions on your computer.
- Yarn https://yarnpkg.com/lang/en/docs/install/.
- Gulp CLI
yarn global add gulp-cli.
NPM packages
- run
yarnon the root directory to install node packages required bygulp-cli
gulp setuprun chain initialization and database migrations.gulp startstarts the docker containers.gulp stopstops and removes all containers.gulp restartrestarts all services.gulp flushstops all services and remove all blockchain and database data.gulp logsdisplays and follows all services logs.gulp migrateexecutes flywaydb migrations against the postgres database.gulp psqlconnects you to the postgres db instance thru command line.
When you run gulp setup several things will happen:
- Chain initialization.
- Testing Users Creation.
- Contracts Compilation and deployment.
- Postgres Schema Creation.
- Postgres Database Migrations.
See services/eos-dev/scripts/0000_init_chain.sh
.
├── docs/ .............................................. documentation files and media
├── services/ .......................................... microservices
| ├── demux/ ......................................... demux-js service
| | ├── utils/ ..................................... general utilities
| | ├── src/ ....................................... application biz logic
| | ├── Dockerfile ................................. service image spec
| | ├── pm2.config.js .............................. process specs for pm2
| | ├── tsconfig.json .............................. tslint config
| | ├── tslint.json ................................ code style rules
| | └── package.json ............................... service dependencies manifest
| |
| ├── eosiodev/ ...................................... eos-dev node for contact development
| | ├── utils/ ..................................... general utilities
| | ├── config/ .................................... eos node config
| | ├── contracts/ ................................. smart contracts
| | ├── scripts/ ................................... chain and wallet init scripts
| | ├── Dockerfile ................................. service image spec
| | └── start.sh ................................... service startup script
| |
| ├── eos-fullnode/ .................................. eos fullnode
| | ├── utils/ ..................................... general utilities
| | ├── config.ini ................................. eos node configuration file
| | ├── Dockerfile ................................. service image spec
| | └── start.sh ................................... service startup script
| |
| ├── postgres/ ...................................... postgres db related files
| | └── migrations/ ................................ flyway migrations
| |
| └── frontend/ ...................................... reactjs frontend
| ├── public/ .................................... static and public files
| ├── src/ ....................................... reactjs views and components
| ├── config-overrides.js ........................ configuration overrides for `cra`
| ├── .env ....................................... environment variables
| ├── .eslintrc .................................. code style rules
| └── package.json ............................... service dependencies manifest
|
├── docker-compose.yaml ................................ docker compose for local dev
├── contributing.md .................................... contributing guidelines
├── license ............................................ project license
├── readme.md .......................................... project documentation
├── netlify.toml ....................................... netlify config file
├── .travis.yml ........................................ travis ci config file
├── .editorconfig ...................................... common text editor configs
└── package.json ....................................... dependencies manifest for gulp-cli
Recommended process for designing EOS Smart Contracts.
Simple use case of equipment rentals that list their equipment for rent and renters who pay rent for those items. digital-scarcity/equiprental
Demux is a backend infrastructure pattern for sourcing blockchain events to deterministically update queryable datastores and trigger side effects.
Taking inspiration from the Flux Architecture pattern and Redux, Demux was born out of the following qualifications:
- A separation of concerns between how state exists on the blockchain and how it is queried by the client front-end
- Client front-end not solely responsible for determining derived, reduced, and/or accumulated state
- The ability for blockchain events to trigger new transactions, as well as other side effects outside of the blockchain
- The blockchain as the single source of truth for all application state
- Client sends transaction to blockchain.
- Action Watcher invokes Action Reader to check for new blocks.
- Action Reader sees transaction in new block, parses actions.
- Action Watcher sends actions to Action Handler.
- Action Handler processes actions through Updaters and Effects.
- Actions run their corresponding Updaters, updating the state of the Datastore.
- Actions run their corresponding Effects, triggering external events.
- Client queries API for updated data.
Learn more at https://github.com/EOSIO/demux-js.
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
There are many reason for choosing GraphQL over other solutions, read Top 5 Reasons to Use GraphQL.
Move faster with powerful developer tools
Know exactly what data you can request from your API without leaving your editor, highlight potential issues before sending a query, and take advantage of improved code intelligence. GraphQL makes it easy to build powerful tools like GraphiQL by leveraging your API’s type system.
The GraphiQL instance on EOS Local is available at http://localhost:3030/graphiql
Learn more at https://graphql.org & https://www.howtographql.com
PostGraphile is an open-source tool to help you rapidly design and serve a high-performance, secure, client-facing GraphQL API backed primarily by your PostgreSQL database. Delight your customers with incredible performance whilst maintaining full control over your data and your database. Use our powerful plugin system to customise every facet of your GraphQL API to your liking.
This is what EOS Local uses to provide the GraphQL endpoint.
Learn more at https://www.graphile.org/postgraphile
This ubuntu server contains everything that's required for contract compilation.
The eosio/eos image does not contain the required dependencies for contract development (this is by design, to keep the image size small), we use eosio.cdt for this and the eosiodev docker image already has it installed for automated and manual compilation.
Note:
The eosio/eos-dev image contains both the required binaries and dependencies to build contracts using eosiocpp. https://hub.docker.com/r/eosio/eos-dev/ the base image can be found at https://github.com/EOSIO/eos/blob/master/Docker/dev/Dockerfile. However eosiocpp is now deprecated in favor eosio-cpp and the lastest eosio/oes-dev docker image does not contain eosio-cpp, at least not yet
Follow up on eoscostarica#27
EOSIO.CDT is a toolchain for WebAssembly (WASM) and set of tools to facilitate contract writing for the EOSIO platform. In addition to being a general purpose WebAssembly toolchain, EOSIO specific optimizations are available to support building EOSIO smart contracts. This new toolchain is built around Clang 7, which means that EOSIO.CDT has the most currently available optimizations and analyses from LLVM, but as the WASM target is still considered experimental, some optimizations are not available or incomplete.
Learn more at https://github.com/EOSIO/eosio.cdt
This is node the provides the RPC API.
See fullnode cofiguration at https://github.com/eoscostarica/eos-local/blob/master/services/eos-fullnode/config.ini
https://hub.docker.com/r/eosio/eos/ the base image source code can be found at https://github.com/EOSIO/eos/blob/master/Docker/Dockerfile.
Postgres database instance for the demux and graphql service.
PostgreSQL is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.
-
Postgres has a strongly typed schema that leaves very little room for errors. You first create the schema for a table and then add rows to the table. You can also define relationships between different tables with rules so that you can store related data across several tables and avoid data duplication.
-
You can change tables in PostgreSQL without requiring to lock it for every operation. For example, you can add a column and set a default value quickly without locking the entire table. This ensures that every row in a table has the column and your codebase remains clean without needing to check if the column exists at every stage. It is also much quicker to update every row since Postgres doesn't need to retrieve each row, update, and put it back.
-
Postgres also supports JSONB, which lets you create unstructured data, but with data constraint and validation functions to help ensure that JSON documents are more meaningful. The folks at Sisense have written a great blog with a detailed comparison of Postgres vs MongoDB for JSON documents.
-
The newest round of performance comparisons of PostgreSQL and MongoDB produced a near repeat of the results from the first tests that proved PostgreSQL can outperform MongoDB.
Learn more at https://www.postgresql.org
Flyway is an open-source database migration tool. It strongly favors simplicity and convention over configuration. It is based around just 7 basic commands: Migrate, Clean, Info, Validate, Undo, Baseline and Repair. EOS Local leverages Flyway to manage the Postgres database migrations.
Learn more at https://flywaydb.org/documentation/migrations & https://flywaydb.org/documentation/videos
Pgweb is a web-based database browser for PostgreSQL, written in Go and works on OSX, Linux and Windows machines. Main idea behind using Go for backend development is to utilize ability of the compiler to produce zero-dependency binaries for multiple platforms. Pgweb was created as an attempt to build very simple and portable application to work with local or remote PostgreSQL databases.
Docker compose exposes a pgweb instance on https://localhost:8081 and also through http://pgweb.eoslocal.io with the nginx reverse-proxy.
MongoDB instance for the fullnode.
The eosio::mongo_db_plugin provides archiving of blockchain data into a MongoDB. It is recommended that the plugin be added to a non-producing node as it is designed to shut down on any failed insert into the MongoDB and is resource intensive.
https://developers.eos.io/eosio-nodeos/docs/mongo_db_plugin
AdminMongo is a Web based user interface (GUI) to handle all your MongoDB connections/databases needs. adminMongo is fully responsive and should work on a range of devices.
Out-of-the-box it is connected to the fullnode mongodb instance and allows you to explore transactions and other data in that database. Docker compose exposes it on https://localhost:8082 and also through http://admin-mongo.eoslocal.io with the nginx reverse-proxy.
adminMongo connection information (including username/password) is stored unencrypted in a config file, it is not recommended to run this application on a production or public facing server without proper security considerations.
Learn more https://mrvautin.com/adminmongo/
Nginx reverse proxy that allows accesing the services directly on the host machine the wildcard *.esolocal.io that points to 127.0.0.1, therefore as long as you can hit the dns server it will redirect all requests to your machine and nginx-proxy does the internal docker network routing to the right service.
Run ping {whatever}.eoslocal.io to verify.
Optionally you can avoid the round trip and work offline maintaining virtual hosts by manually adding your dns to your hosts file. https://en.wikipedia.org/wiki/Hosts_(file)
See the docker-compose.yml for available virtual hosts for easier access without port shenanigans.
In the services/frontend folder you will find a production ready frontend with Scatter and Lynx libraries ready for you to use.
- react-app-rewired for tweaking
create-react-appconfiguration without ejecting. - reach-router for a more accessible router.
- state management with rematch to use
reduxbest practices without all the boilerplate. - react-apollo react apollo client.
- material-ui.
- scatter-js.
- eoslynx integration.
- TravisCI to run test and code style checks. We are planning on moving to Circle CI https://github.com/eoscostarica/eos-local/projects/3.
- Netlify for continuous delivery and creation of ephemeral test environments.
Cleos is a command line tool that interfaces with the REST API exposed by nodeos. In order to use cleos you will need to have the end point (IP address and port number) to a nodeos instance and also configure nodeos to load the 'eosio::chain_api_plugin'. cleos contains documentation for all of its commands.
More at https://developers.eos.io/eosio-nodeos/docs/cleos-overview
EOS Local comes with 2 EOS nodes running in separate docker containers, you can interact with these nodes using cleos in several ways:
You can execute commands on any container from you host machine using the docker-compose exec command.
Eg:
docker-compose exec eosiodev cleos --url http://localhost:8888/
We recomend using declaring alias on your shell configuration Eg (.bashrc or .zshrc)
alias cleos_eosiodev='docker-compose exec eosiodev cleos --url http://localhost:8888/'
alias cleos_fullnode='docker-compose exec fullnode cleos --url http://localhost:8888/'
After you have added those lines to your config you can open a new terminal window and run cleos_eosiodev --help and cleos_fullnode --help to test.
EOS Local provides to handy yarn scripts to accomplish the same functionality mentioned above.
yarn cleos............. connects to eosiodev nodeyarn cleos:eosiodev.... connects to eosiodev nodeyarn cleos:fullnode.... connects to the eos fullnode
Important note:
We currently use yarn instead gulp for this because it allows to pass parameters more easily.
In the future gulp and yarn script at the root level will be replaced with an eoslocal cli.
Follow up here eoscostarica#17
You can also login into the containers using the following docker-compose command
docker-compose exec [service_name] bash where service_name is either eosiodev or fullnode
That will log you in and you will be able to execute cleos directly within the ubuntu server. Eg.
➜ eos-local git:(master) ✗ docker-compose exec eosiodev bash
root@b39ffe3c43c0:/opt/eosio/bin# cleos get info
{
"server_version": "f9a3d023",
"chain_id": "cf057bbfb72640471fd910bcb67639c22df9f92470936cddc1ade0e2f2e7dc4f",
"head_block_num": 4900,
"last_irreversible_block_num": 4899,
"last_irreversible_block_id": "000013232f7193f86a4edc59b6aa2b2a8ccd6c2060d24eb0e5c497beb97b76e5",
"head_block_id": "000013249772e5af12592d7d3eeb401276c09f781e3ed76faa75a49f53b481bd",
"head_block_time": "2018-11-05T20:27:45.000",
"head_block_producer": "eosio",
"virtual_block_cpu_limit": 26829884,
"virtual_block_net_limit": 140951435,
"block_cpu_limit": 199900,
"block_net_limit": 1048576,
"server_version_string": "v1.4.1"
}
- https://github.com/EOSIO/eos/tree/master/Docker
- https://developers.eos.io
- https://github.com/EOSIO/eosio.contracts
- https://learn.eoscostarica.io
- https://github.com/slowmist/eos-smart-contract-security-best-practices
- https://nadejde.github.io/eos-token-sale
- https://docs.docker.com/kitematic/userguide/
EOSFactory is Python-based framework for building and testing EOS smart contracts. EOS Local has a larger scope. It is Docker-based and serves as boilerplate to start a scalable EOSIO project with microservices architecture following best practices at all levels. It includes many required services for large-scale EOSIO based applications and ReactJS client with Scatter and Lynx already integrated.
The primary benefits of containers are efficiency and agility. Containers are orders of magnitude faster to provision, and much lighter-weight to build and define versus methods like omnibus software builds and full Virtual Machine images. Containers in a single OS are also more efficient at resource utilization than running a Hypervisor and guest OSs.
Efficiency and agility are good for everyone, but they become game-changers at scale.
It also gives the ability to run distint versions of the different services like EOSIO on your laptop without conflicts.
Containers offer a logical packaging mechanism in which applications can be abstracted from the environment in which they actually run. This decoupling allows container-based applications to be deployed easily and consistently, regardless of whether the target environment is a private data center, the public cloud, or even a developer’s personal laptop. Containerization provides a clean separation of concerns, as developers focus on their application logic and dependencies, while IT operations teams can focus on deployment and management without bothering with application details such as specific software versions and configurations specific to the app.
For those coming from virtualized environments, containers are often compared with virtual machines (VMs). You might already be familiar with VMs: a guest operating system such as Linux or Windows runs on top of a host operating system with virtualized access to the underlying hardware. Like virtual machines, containers allow you to package your application together with libraries and other dependencies, providing isolated environments for running your software services. As you’ll see below however, the similarities end here as containers offer a far more lightweight unit for developers and IT Ops teams to work with, carrying a myriad of benefits.
Learn more at https://cloud.google.com/containers/
- It enables a rock-solid deployment process because you are doing exactly the same when updating your local database, your development database, your QA database, your acceptance database and your production database. It’s always the same process and it can be automated.
- You can easily bring a (CI-)database to the point you want by loading a baseline backup and running all migration scripts until a certain point.
- If you do it right you have database versioning and change documentation included
- The approach encourages small changes at a time, leading to less risky deployments
- It enables and empowers continuous integration because you can easily transport your functional stat to different data sets (e.g. test data)
- You know exactly what’s happening. That’s in my opinion the greatest benefit of all, because it gives you confidence that what you’re delivering will work. It also gives you enormous flexibility and lets you solve any kind of challenge – even and especially ones which need specific business logic.
Learn more at https://dev.to/pesse/one-does-not-simply-update-a-database--migration-based-database-development-527d
We use a Kanban-style board. That's were we prioritize the work. Go to Project Board.
The main communication channels are github issues and EOS Costa Rica's Discord server. Feel to join and ask as many questions you may have.
Our weekly sync call is every Monday 1:00 AM UTC. meet.eoscostarica.io.
Contributing Guidelines https://learn.eoscostarica.io/open-source/.
Please report bugs big and small by opening an issue
- https://github.com/EOS-Nation/Awesome-EOS
- https://github.com/DanailMinchev/awesome-eosio
- https://github.com/kesar/eos-awesome-contracts/
- https://github.com/veggiemonk/awesome-docker
- https://github.com/dhamaniasad/awesome-postgres
- https://github.com/ramnes/awesome-mongodb
- https://github.com/enaqx/awesome-react
- https://github.com/jaredpalmer/awesome-react-render-props
- https://github.com/chentsulin/awesome-graphql
Contact the team directly on the #eos-local channel on EOS Costa Rica's Discord server, we will assist you as soon as possible.
EOS Blockchain is aiming to become a decentralized operating system which can support large-scale decentralized applications.
EOS Costa Rica supports the EOSIO community by maintaining and contributing to open source initiatives, meetups and workshops.
We challenge ourselves to provide the EOS platform with a strong geographical and political diversity by running the most robust EOS Block Producer possible from Costa Rica; We pledge to leverage our talent, experience, and sustainable internet resources to meet such an important challenge.
MIT © EOS Costa Rica
 Gabo Esquivel 🤔 📖 💻 👀 |
 Daniel Prado 💻 📖 🤔 👀 |
 Jorge Murillo 🤔 📖 🎨 💻 👀 |
 Xavier Fernandez 🤔 📝 📢 🚇 |
 Rubén Abarca Navarro 🤔 👀 💻 |
 jsegura17 💻 👀 🤔 |
 Leo Ribeiro 🤔 👀 |
|---|---|---|---|---|---|---|
 Mariano Alvarez 🤔 👀 |
 Julien Lucca 👀 🤔 |
 Edgar Fernandez 🤔 📝 📢 |
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!