Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework documentation to make it more complete #128

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

Rework documentation to make it more complete #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
c4f8b6d
Improve documentation by creating a dedicated folder and adding Archi…
aboulay Sep 1, 2020
354156d
Add a new doc about how to handle new network
aboulay Sep 1, 2020
50fb597
Move README content inside docs/README.md (technical README) and prep…
aboulay Sep 1, 2020
016764f
Move API content from docs/README.md
aboulay Sep 1, 2020
76efc7a
Move Frontend content from docs/README.md
aboulay Sep 1, 2020
e80cfc3
Update beginning of README.md and add full logo
Sep 3, 2020
b03d3e8
Update README.md and try to add dynamic link to the Githu documentation
Sep 3, 2020
b5df64b
Update docs/README.md and add file path
Sep 3, 2020
b02e455
Refactor the docs/README Table of Contents and complete Proxy documen…
Sep 3, 2020
d43adb4
Add Project_organization.md
aboulay Sep 3, 2020
b86b776
Add How_to_run_locally.md
aboulay Sep 3, 2020
4165260
Remove duplicated part in README.md
aboulay Sep 3, 2020
e91ed25
Organize docs/README.md and add <TODO> inside not done part
aboulay Sep 3, 2020
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
333 changes: 21 additions & 312 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,330 +1,39 @@
# Tezos Link
# ![TezosLink](docs/img/tezoslink-logo-full.png "TezosLink")

[![Go Report Card](https://goreportcard.com/badge/github.com/octo-technology/tezos-link)](https://goreportcard.com/report/github.com/octo-technology/tezos-link) ![Build](https://github.com/octo-technology/tezos-link/workflows/Build/badge.svg?branch=master)

Tezos link is a gateway to access to the Tezos network aiming to improve developer experience when developing Tezos dApps.
[![Go Report Card](https://goreportcard.com/badge/github.com/octo-technology/tezos-link)](https://goreportcard.com/report/github.com/octo-technology/tezos-link)

# Table of Contents
![CI/CD Front](https://github.com/octo-technology/tezos-link/workflows/CI/CD%20Front/badge.svg?branch=master)
![CI/CD API](https://github.com/octo-technology/tezos-link/workflows/CI/CD%20API/badge.svg?branch=master)
![CI/CD Proxy](https://github.com/octo-technology/tezos-link/workflows/CI/CD%20Proxy/badge.svg?branch=master)

- [Project organization](#project-organization)
- [Run services locally on the machine](#run-services-locally-on-the-machine)
- [Build all services](#build-all-services)
- [Tests all services](#tests-all-services)
- [Frontend](#frontend)
- [Services](#services)
- [API](#api)
- [Proxy](#proxy)
- [Snapshot exporter](#snapshot-exporter)
- [Infrastructure](#infrastructure)
- [Architecture](#architecture)
- [Requirements](#requirements)
- [How To Deploy](#how-to-deploy)
- [Documentation](#documentation)
- [References](#references)
---

# Project Organization
Tezos Link is a gateway to access to the Tezos network aiming to improve developer experience when you are developping Tezos applications.

The repository is currently following this organization:
The project is hosted in Amazon Web Service by [OCTO Technology](https://www.octo.com/) and is under the supervision of the [Tezos Foundation](https://tezos.foundation/).

```
.
├── api # api documentation
├── build # packaging
├── cmd # mains
├── config # config parsers
├── data # config and migrations
├── infra # infrastructure
├── internal # services
├── test # test-specific files
└── web # frontend
└── public
└── docs # usage documentation
```
## How to start using Tezos-Link

## Run services locally on the machine with mockup blockchain node
The [Tezos Link website](https://tezoslink.io/) contains all the informations needed to use it.

> Blockchain nodes are mocked up for development environment the be as lightweight as possible.
We invite you to have a look to our [documentation](https://tezoslink.io/documentation) to learn how to use the API.

### Requirements
You don't know how to code a Tezos Smart Contract ? Feel free to check [Tezos Academy](https://tezosacademy.io). It contains all the assets you need to learn Smart Contract development... and for free.

- `Docker`
- `docker-compose`
- `Yarn` (setup with 1.22.0)
- `Golang` (setup with 1.13)
- `GNU Make` (setup with 3.81)
- `Node.js` (setup with 11.14.0)
## How it works

### How to
The TezosLink project was builded to be run on an AWS architecture.
It is mainly composed by a group of Tezos nodes from differents Tezos networks which are running next to a proxy. This proxy redirect smartly requests based on the request type and few other factors.

To run services locally on the machine, you will need to run those commands :
If you want to get more informations, have a look to our [technical documentation](./docs).

```bash
$> make deps
$> make build-docker
$> make run-dev
```
## Contributing

It will run:
TODO : will be writed soon

- `tezos-link_proxy`
- `tezos-link_proxy-carthagenet`
- `tezos-link_api`
- `mockserver/mockserver:mockserver-5.9.0` (mocking a blockchain node)
- `postgres:9.6`
## License

The only endpoint served by the blockchain mock is:
Apache Licence v2.0

```bash
curl -X PUT localhost:8001/v1/<YOUR_PROJECT_ID>/mockserver/status
```

## Test all services

### Requirements

- `Golang` (setup with 1.13)
- `GNU Make` (setup with 3.81)

For integrations tests only:

- `Docker`
- `docker-compose`
- `yarn`

### How to

To run the `unit tests`, you can use the command

```bash
$> make unit-test
```

To run `integration tests` locally, you will need to run following commands :

```bash
# We build docker images and run them
$> make build-docker & make run

# We run integration tests...
$> make integration-test

# And we clean the environment when we are done
$> docker-compose down
```

## Build all services and frontend

### Requirements

- `GNU Make` (setup with 3.81)
- `Golang` (setup with 1.13)
- `Yarn` (setup with 1.22.0)
- `Node.js` (setup with 11.14.0)

### How to

To build your project, you need first to `install dependencies`:

```bash
$> make deps
```

After, you can run the `build` with

```bash
$> make build
```

## Frontend

### Requirements

- `Yarn` (setup with 1.22.0)
- `Node.js` (setup with 11.14.0)

To build the frontend, you need first to `install dependencies`:

```bash
$> make deps
```

### Run

To run the frontend, execute:

```bash
$> cd web && yarn start-local
```

### Build

To run the frontend, execute:

```bash
$> make build-frontend
```

### Deploy

> You will need AWS credentials setup on your machine, see [AWS Credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)

To run the frontend, execute:

```bash
$> make deploy-frontend
```

## Services

### API

REST API to manage projects and get project's metrics.

#### Dependencies

- `PostgreSQL` (setup with 9.6)

#### Environment variables

- `DATABASE_URL` (default: `postgres:5432`)
- `DATABASE_USERNAME` (default: `user`)
- `DATABASE_PASSWORD` (default: `pass`)
- `DATABASE_TABLE` (default: `tezoslink`)
- `DATABASE_ADDITIONAL_PARAMETER` (default: `sslmode=disable`)
- `SERVER_HOST` (default: `localhost`)
- `SERVER_PORT` (default: `8000`)

### Proxy

- HTTP proxy in front of the nodes
- In-memory (LRU) cache

#### Dependencies

- `PostgreSQL` (setup with 9.6)

#### Environment variables

- `DATABASE_URL` (default: `postgres:5432`)
- `DATABASE_USERNAME` (default: `user`)
- `DATABASE_PASSWORD` (default: `pass`)
- `DATABASE_TABLE` (default: `tezoslink`)
- `DATABASE_ADDITIONAL_PARAMETER` (default: `sslmode=disable`)
- `ARCHIVE_NODES_URL` (default: `node`)
- `TEZOS_ARCHIVE_PORT` (default: `1090`)
- `ROLLING_NODES_URL` (default: `node`)
- `TEZOS_ROLLING_PORT` (default: `1090`)
- `SERVER_PORT` (default: `8001`)

### Snapshot exporter lambda

Lambda function scheduled with a `Cloudwatch Rule` cronjob, connect to a node with SSH and trigger a snapshot export.

#### Deploy for testing and for development purpose

Individual deployment of the lambda is possible for testing and development purpose.

> You will need AWS credentials setup on your machine, see [AWS Credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)

It will build, send to the S3 bucket and update snapshot lambda code:

```bash
$> make build-unix
$> make deploy-snapshot-lambda
```

To execute the lambda, run:

```bash
aws lambda invoke --region=eu-west-1 --function-name=snapshot --log Tail output.txt | grep "LogResult"| awk -F'"' '{print $4}' | base64 --decode
```

### Metrics cleaner lambda

Lambda function scheduled with a `Cloudwatch Rule` cronjob, connect to a node with SSH and trigger a metrics clean.

#### Deploy for testing and development purpose

Individual deployment of the lambda is possible for testing and development purpose.

> You will need AWS credentials setup on your machine, see [AWS Credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)

It will build, send to the S3 bucket and update metrics-cleaner lambda code:

```bash
$> make build-unix
$> make deploy-metrics-cleaner-lambda
```

To execute the lambda, run:

```bash
aws lambda invoke --region=eu-west-1 --function-name=metrics --log Tail output.txt | grep "LogResult"| awk -F'"' '{print $4}' | base64 --decode
```

#### Environment variables

These environment variables are set in `infra/dev.tfvars`.

- `NODE_USER` (default: `ec2-user`)
- `S3_REGION` (default: `eu-west-1`)
- `S3_BUCKET` (default: `tzlink-snapshot-lambda-dev`)
- `S3_LAMBDA_KEY` (default: `snapshot_lambda_key`)

## Infrastructure

### Architecture

![Architecture](infra/img/architecture.png "Architecture")

### Requirements

- `Terraform` (version == 0.12.20)
- `Terragrunt` (version == 0.21.4)

> We recommend to install `tf-env` to manage easily your terraform environments.

### How to deploy

All the files related to the infrastructure are based on the `infra` folder.

First, you will need to update the configuration (if needed). To do this, you will find `common.tfvars` and `<env>.tfvars` in the folder `infra/terragrunt`.

> Currently, database password is encrypted inside the file `vaulted.tfvars`. To see it content, you will need ansible-vault and a passphrase to decrypt it with the command `ansible-vault decrypt vaulted.tfvars`.
>
> This will be changed soon with AWS Secret Manager.

When they are updated, we will use Terragrunt to deploy our infrastructure by running:

```bash
# To check if all is OK
$> terragrunt plan-all

# To apply the change
$> terragrunt apply-all
```

If you want to apply a specific part of the infrastructure (ex: `00_network`), you can run

```bash
$> cd infra/terragrunt/00_network

# To check if all is OK
$> terragrunt plan

# To apply the change
$> terragrunt apply
```

## Documentation

The documentation usage is located at `web/public/docs`.

It contains the various Markdown files served by the application at `/documentation`.

## References

This repo took some ideas & code from:

- https://github.com/tezexInfo/TezProxy
- https://github.com/AymericBethencourt/serverless-mern-stack/
See [License](./LICENSE) to see full text
Loading