Skip to content
This repository was archived by the owner on May 27, 2022. It is now read-only.

Updates readme with cakeshop's features #204

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Updates readme with cakeshop's features #204

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b7c1cff
Updates readme with cakeshop's features
bmcd Mar 17, 2021
e4daf50
Updates readme to match doc.goquorum changes
bmcd Mar 18, 2021
8faff1d
Updates configuration.md to match doc.goquorum update
bmcd Mar 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 23 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,19 @@

## What is it?

_Cakeshop_ is a set of tools and APIs for working with GoQuorum nodes, packaged as a Java web application archive (WAR) that gets you up and running in under 60 seconds.
_Cakeshop_ is a set of tools and APIs for working with [Ethereum](https://ethereum.org/),
packaged as a Java web application archive (WAR) that gets you up and running quickly.

It provides tools for attaching to GoQuorum nodes, exploring the state of the chain, and working with contracts.
Cakeshop can be connected to Ethereum-like nodes, such as Quorum, which you can then interact with using the Cakeshop front-end.

## Features

* **Blockchain Explorer** - view transactions, blocks and contracts, and see historical contract state at a point in time
* **Contract Registry** - keep track of deployed contracts, along with their code, interfaces, and state
* **Node Info** - view the overall status of your network
* **Peer Management** - easily discover, add, and remove peers
* **Enhanced Permissions UI** - manage smart contract-based [Enhanced Permissioning](https://docs.goquorum.consensys.net/en/stable/Concepts/Permissioning/Enhanced/ContractDesign/)
* **Solidity Sandbox** - develop, compile, deploy, and interact with Solidity smart contracts

## Download

Expand All @@ -27,13 +37,13 @@ The easiest way to use Cakeshop is to generate a GoQuorum network with [GoQuorum
### Requirements

* Java 11+
* NodeJS (if the nodejs binary on your machine isn't called 'node', see [here](docs/configuration.md#cakeshop-internals))
* NodeJS 10+ (if the nodejs binary on your machine isn't called 'node', see [here](docs/configuration.md#cakeshop-internals))

### Running

* Download WAR file
* Run `java -jar cakeshop.war`
* Navigate to [http://localhost:8080/](http://localhost:8080/)
* Navigate to [`http://localhost:8080/`](http://localhost:8080/)


## Running via Docker
Expand All @@ -44,7 +54,7 @@ Simple example of running via docker on port 8080:
docker run -p 8080:8080 quorumengineering/cakeshop
```

Then access the UI at [http://localhost:8080/](http://localhost:8080/)
Then access the UI at [`http://localhost:8080/`](http://localhost:8080/)

### Docker Customizations
You can add some extra flags to the run command to further customize cakeshop.
Expand All @@ -68,22 +78,17 @@ docker run -p 8080:8080 -v "$PWD/data":/opt/cakeshop/data \
## Migrating from Cakeshop v0.11.0

The following big changes were made in v0.12.0:

1. Simplification of config file to better follow Spring Boot standards.
* To ensure easy transition, Cakeshop will still look in the locations where v0.11.0 commonly stored the config file. But the new version allows you to now place your config in the folder where you run Cakeshop, or specify a different location using standard spring boot flags, for easier customization.
* Cakeshop had custom logging location logic in the config before this change, which was removed. You may now redirect logs yourself or use Spring's logging config settings.
1. Moved Contract Registry from being stored in a combination of a smart contract and the database to being in the database only.
1. Elimination of cakeshop's managed node in favor of only attaching to existing nodes.
* If you had contracts deployed and stored in the old Contract Registry, you may leave the `contract.registry.addr` line in your config file. Cakeshop will look for that contract address when it connects to the network and add those contracts to the database.
1. Elimination of Cakeshop's managed node in favor of only attaching to existing nodes.
* Most of the original config values were related to this feature, and can be safely removed. See the [default config file](../cakeshop-api/src/main/resources/config/application.properties) for all the values that are actually used.
1. Simplified DB configuration by using Spring Data.

To ensure easy transition, Cakeshop will still look in the locations where v0.11.0 commonly stored the config file. But (1) allows you to now place your config in the folder where you run cakeshop, or specify a different location using standard spring boot flags, for easier customization.

Cakeshop had custom logging location logic in the config before this change, which was removed. You may now redirect logs yourself or use Spring's logging config settings.

For (2), if you had contracts deployed and stored in the old Contract Registry, you may leave the `contract.registry.addr` line in your config file. Cakeshop will look for that contract address when it connects to the network and add those contracts to the database.

For (3), most of the original config values were related to this feature, and can be safely removed. See the [default config file](../cakeshop-api/src/main/resources/config/application.properties) for all the values that are actually used.

(4) means that you will need to update the db-related config values to use spring data. So the old `cakeshop.database`, `cakeshop.hibernate`, and `cakeshop.jdbc` settings should change to use `spring.data`, `spring.jpa`, etc. See the [configuration](docs/configuration.md#database) doc for more info.

Note: Due to an bug that happens when you update from Hibernate 4 to 5, when auto-updating the database it will try to recreate some column constraints that don't need to be recreated. These will fail and print a stack trace in the logs because they already exist. There are no negative effects from this error, so the best thing to do is to run with `spring.jpa.hibernate.ddl-auto=update` once and then change `update` to `none` on subsequent runs to avoid error logs. In production, it is not recommended to use auto-update to migrate your database at all, but instead run migrations on the database yourself.
* You will need to update the db-related config values to use spring data. The old `cakeshop.database`, `cakeshop.hibernate`, and `cakeshop.jdbc` settings should change to use `spring.data`, `spring.jpa`, etc. See the [database configuration section](docs/configuration.md#database) for more info.
* Due to an bug that happens when you update from Hibernate 4 to 5, when auto updating the database it will try to recreate some column constraints that don't need to be recreated. These will fail and print a stack trace in the logs because they already exist. No negative effects result from this error, so the best thing to do is to run with `spring.jpa.hibernate.ddl-auto=update` once and then change `update` to `none` on subsequent runs. In production, it is not recommended to use auto update to migrate your database at all, but instead run migrations on the database yourself.

## Further Reading

Expand Down
19 changes: 10 additions & 9 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Cakeshop

Cakeshop follows standard [Spring Boot configuration patterns](https://docs.spring.io/spring-boot/docs/2.0.9.RELEASE/reference/html/boot-features-external-config.html#:~:text=Spring%20Boot%20lets%20you%20externalize,line%20arguments%20to%20externalize%20configuration.), so you may provide an `application.properties` in the location where you are running cakeshop to customize some settings of cakeshop.
Cakeshop follows standard [Spring Boot configuration patterns](https://docs.spring.io/spring-boot/docs/2.3.7.RELEASE/reference/html/spring-boot-features.html#boot-features-external-config), so you may provide an `application.properties` in the location where you are running Cakeshop to customize some of its settings.

You may also override config options via Java system properties passed via `java -D<prop>=<val>`:

Expand All @@ -12,13 +12,13 @@ java -Dcakeshop.initialnodes=data/cakeshop/nodes.json -jar cakeshop.war

### Initial Nodes

When Cakeshop starts for the first time, it will not actually know which node(s) it is supposed to connect to. You will need to click on 'Manage Nodes' in the top right corner of the Cakeshop UI to add nodes by RPC url.
When Cakeshop starts for the first time, it will not actually know which node it is supposed to connect to. You will need to click on 'Manage Nodes' in the top right corner of the Cakeshop UI to add nodes by RPC URL.

Alternatively, you may provide an initial set of nodes in a JSON file that Cakeshop will use to prepopulate the nodes list. This file will only be used if no nodes have previously been added to Cakeshops database.

The format of the JSON file is as follows:

```
```json
[
{
"name": "node1",
Expand All @@ -38,10 +38,11 @@ The format of the JSON file is as follows:
]
```

The rpcUrl field should be the RPC endpoint on the GoQuorum (geth) node, and the transactionManagerUrl should be the Tessera 3rd Party API endpoint.
The `rpcUrl` field should be the RPC endpoint on the GoQuorum (`geth`) node, and the `transactionManagerUrl` should be the Tessera 3rd party API endpoint.

Provide the location of the initial nodes file through application.properties or by using the `-D` flag mentioned above.
```sh
Provide the location of the initial nodes file through `application.properties` or by setting the `cakeshop.initialnodes` property with Java `-D` command line option.

```properties
# inside application.properties
cakeshop.initialnodes=path/to/nodes.json
```
Expand All @@ -50,7 +51,7 @@ cakeshop.initialnodes=path/to/nodes.json

Cakeshop uses Spring Data for its database connection. By default, it uses an in-memory/file-based HSQLDB, but you may customize using standard Spring Data config values:

```sh
```properties
# spring data settings
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
spring.datasource.url=jdbc:postgresql://localhost:5432/cakeshop
Expand All @@ -62,9 +63,9 @@ spring.datasource.password=sdk

### Cakeshop Internals

Some other options that may be customized in application.properties:
Some other options that may be customized in `application.properties`:

```sh
```properties
# some systems don't call the nodejs binary 'node', in that change you can change this value
nodejs.binary=node

Expand Down