tfgrid/info_tfgrid
33
3
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Activity

restructured manual

Browse Source
This commit is contained in:
mik-tf
2024-04-29 18:23:19 +00:00
parent 7bd1e7a0d8
commit 60b6c802ed
2351 changed files with 247 additions and 67649 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
collections/developers/developers.md
View File

@@ -87,5 +87,4 @@ For complementary information on the technology developed by ThreeFold, refer to
- [Grid Deployment](./grid_deployment/grid_deployment.md)
- [TFGrid Stacks](./grid_deployment/tfgrid_stacks.md)
- [Full VM Grid Deployment](./grid_deployment/grid_deployment_full_vm.md)
- [Grid Snapshots](./grid_deployment/snapshots.md)
- [Deploy the Dashboard](./grid_deployment/deploy_dashboard.md)
- [Grid Snapshots](./grid_deployment/snapshots.md)

4
collections/developers/flist/flist.md
View File

@@ -2,8 +2,8 @@
<h2> Table of Contents </h2>
- [Zero-OS Hub](./flist_hub/zos_hub.md)
- [Generate an API Token](./flist_hub/api_token.md)
- [Zero-OS Hub](manual:zos_hub.md)
- [Generate an API Token](api_token.md)
- [Convert Docker Image Into Flist](./flist_hub/convert_docker_image.md)
- [Supported Flists](./grid3_supported_flists.md)
- [Flist Case Studies](./flist_case_studies/flist_case_studies.md)

8
collections/developers/flist/flist_hub/zos_hub.md
View File

@@ -11,8 +11,8 @@
- [Upload your Existing Flist to Reduce Bandwidth](#upload-your-existing-flist-to-reduce-bandwidth)
- [Authenticate via 3Bot](#authenticate-via-3bot)
- [Get and Update Information Through the API](#get-and-update-information-through-the-api)
- [Public API Endpoints (No Authentication Required)](#public-api-endpoints-no-authentication-required)
- [Restricted API Endpoints (Authentication Required)](#restricted-api-endpoints-authentication-required)
- [Public API Endpoints - No Authentication Required](#public-api-endpoints---no-authentication-required)
- [Restricted API Endpoints - Authentication Required](#restricted-api-endpoints---authentication-required)
- [API Request Templates and Examples](#api-request-templates-and-examples)
***
@@ -71,7 +71,7 @@ If your `jwt` contains memberof, you can choose which user you want to use by sp
See example below.
### Public API Endpoints (No Authentication Required)
### Public API Endpoints - No Authentication Required
- `/api/flist` (**GET**)
- Returns a json array with all repository/flists found
- `/api/repositories` (**GET**)
@@ -84,7 +84,7 @@ See example below.
- `/api/flist/<repository>/<flist>` (**GET**)
- Returns json object with flist dumps (full file list)
### Restricted API Endpoints (Authentication Required)
### Restricted API Endpoints - Authentication Required
- `/api/flist/me` (**GET**)
- Returns json object with some basic information about yourself (authenticated user)
- `/api/flist/me/<flist>` (**GET**, **DELETE**)

127
collections/developers/grid_deployment/deploy_dashboard.md
View File

@@ -1,127 +0,0 @@
<h1>Deploy the Dashboard</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Create an SSH Tunnel](#create-an-ssh-tunnel)
- [Editor SSH Remote Connection](#editor-ssh-remote-connection)
- [Set the VM](#set-the-vm)
- [Build the Dashboard](#build-the-dashboard)
- [Dashboard Public Access](#dashboard-public-access)
- [Questions and Feedback](#questions-and-feedback)
***
## Introduction
We show how to deploy the Dashboard (devnet) on a full VM. To do so, we set an SSH tunnel and use the VSCodium Remote Explorer function. We will then be able to use a source-code editor to explore the code and see changes on a local browser.
We also show how to provide a public access to the Dashboard by setting a gateway domain to your full VM deployment. Note that this method is not production-ready and should only be used to test the Dashboard.
## Prerequisites
- TFChain account with TFT
- [Deploy full VM with WireGuard connection](../../system_administrators/getstarted/ssh_guide/ssh_wireguard.md)
- [Make sure you can connect via SSH on the terminal](../../system_administrators/getstarted/ssh_guide/ssh_openssh.md)
In this guide, we use WireGuard, but you can use other connection methods, such as [Mycelium](../../system_administrators/mycelium/mycelium_toc.md).
## Create an SSH Tunnel
- Open a terminal and create an SSH tunnel
```
ssh -4 -L 5173:127.0.0.1:5173 root@10.20.4.2
```
Simply leave this window open and follow the next steps.
If you use an IPv6 address, e.g. with Mycelium, set `-6` in the line above instead of `-4`.
## Editor SSH Remote Connection
You can connect via SSH through the source-code editor to a VM on the grid. In this example, WireGuard is set.
- Add the SSH Remote extension to [VSCodium](https://vscodium.com/)
- Add a new SSH remote connection
- Set the following (adjust with your own username and host)
```
Host 10.20.4.2
HostName 10.20.4.2
User root
```
- Click on `Connect to host`
## Set the VM
We set the VM to be able to build the Dashboard.
```
apt update && apt install build-essential python3 -y
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
nvm install 18
npm install -g yarn
```
## Build the Dashboard
We now build the Dashboard.
Clone the repository, then install, build and run the Dashboard. Note that here it is called `playground`:
```
git clone https://github.com/threefoldtech/tfgrid-sdk-ts
cd tfgrid-sdk-ts/
yarn install
make build
make run project=playground
```
You can then access the dev net Dashboard on your local browser.
To stop running the Dashboard, simply enter ̀`Ctrl-C` on the terminal window.
## Dashboard Public Access
> Note: This method is not production-ready. Use only for testing purposes.
Once you've tested the Dashboard with the SSH tunnel, you can explore how to access it from the public Internet. For this, we will create a gateway domain and bind the host to `0.0.0.0`.
On the Full VM page, [add a domain](../../dashboard/solutions/add_domain.md) to access your deployment from the public Internet.
- Under `Actions`, click on `Manage Domains`
- Go to `Add New Domain`
- Choose a gateway domain under `Select domain`
- Set the port 5173
- Click on `Add`
To run the Dashboard from the added domain, use this instead of the previous `make run` line:
```
cd packages/playground
yarn dev --host 0.0.0.0
```
You can then access the Dashboard from the domain you just created.
## Questions and Feedback
If you have any questions or feedback, please let us know by either writing a post on the [ThreeFold Forum](https://forum.threefold.io/), or by chatting with us on the [TF Grid Tester Community](https://t.me/threefoldtesting) Telegram channel.

5
collections/developers/grid_deployment/grid_deployment.md
View File

@@ -2,11 +2,8 @@
The TFGrid whole source code is open-source and instances of the grid can be deployed by anyone thanks to the distribution of daily grid snapshots of the complete ThreeFold Grid stacks.
This section also covers the steps to deploy the Dashboard locally. This can be useful when testing the grid or contributing to the open-source project.
## Table of Contents
- [TFGrid Stacks](./tfgrid_stacks.md)
- [Full VM Grid Deployment](./grid_deployment_full_vm.md)
- [Grid Snapshots](./snapshots.md)
- [Deploy the Dashboard](./deploy_dashboard.md)
- [Grid Snapshots](./snapshots.md)

51
collections/developers/grid_deployment/grid_deployment_full_vm.md
View File

@@ -4,7 +4,6 @@
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Deploy All 3 Network Instances](#deploy-all-3-network-instances)
- [DNS Settings](#dns-settings)
- [DNS Verification](#dns-verification)
- [Prepare the VM](#prepare-the-vm)
@@ -18,11 +17,9 @@
## Introduction
We present the steps to deploy an instance of the TFGrid on a full VM.
We present the steps to deploy a network instance of the TFGrid on a full VM.
For this guide, we will be deploying a mainnet instance. While the steps are similar for testnet and devnet, you will have to adjust your deployment depending on which network you use. Details are provided when needed.
We also provide information to deploy the 3 different network instances.
For this guide, we will be deploying a mainnet instance. While the steps are similar for testnet and devnet, you will have to adjust your deployment depending on which network you use.
## Prerequisites
@@ -36,30 +33,17 @@ For this guide, you will need to deploy a full VM on the ThreeFold Grid with at
After deploying the full VM, take note of the IPv4 and IPv6 addresses to properly set the DNS records and then SSH into the VM.
It is recommended to deploy on a machine with modern hardware and NVME storage disk.
## Deploy All 3 Network Instances
To deploy the 3 network instances, mainnet, testnet and mainnet, you need to follow the same process for each network on a separate machine or at least on a different VM.
This means that you can either deploy each network instance on 3 different machines, or you can also deploy 3 different VMs on the same machine, e.g. a dedicated node. Then, each VM will run a different network instance. In this case, you will certainly need a machine with NVME storage disk and modern hardware.
## DNS Settings
You need to set an A record for the IPv4 address and an AAAA record for the IPv6 address with a wildcard subdomain.
The following table explicitly shows how to set the A and AAAA records for your domain for all 3 networks. Note that both `testnet` and `devnet` have a subdomain. The last two lines are for mainnet since no subdomain is needed in this case.
The following table explicitly shows how to set the A and AAAA records for your domain.
| Type | Host | Value |
| ---- | ---- | -------------- |
| A | \*.dev | <devnet_ipv4_address> |
| AAAA | \*.dev | <devnet_ipv6_address> |
| A | \*.test | <testnet_ipv4_address> |
| AAAA | \*.test | <testnet_ipv6_address> |
| A | \* | <mainnet_ipv4_address> |
| AAAA | \* | <mainnet_ipv6_address> |
| A | \* | <ipv4_address> |
| AAAA | \* | <ipv6_address> |
As stated above, each network instance must be on its own VM or machine to work properly. Make sure to adjust the DNS records accordingly.
### DNS Verification
@@ -67,17 +51,12 @@ You can use tools such as [DNSChecker](https://dnschecker.org/) or [dig](https:/
## Prepare the VM
We show the steps to prepare the VM to run the network instance.
If you are deploying on testnet or devnet, simply replace `mainnet` by the proper network in the following lines.
- Download the ThreeFold Tech `grid_deployment` repository
```
git clone https://github.com/threefoldtech/grid_deployment
cd grid_deployment/docker-compose/mainnet
```
- Generate a TFChain node key with `subkey`
- Note: If you deploy the 3 network instances, you can use the same node key for all 3 networks. But it is recommended to use 3 different keys to facilitate management.
```
echo .subkey_mainnet >> .gitignore
../subkey generate-node-key > .nodekey_mainnet
@@ -101,7 +80,7 @@ If you are deploying on testnet or devnet, simply replace `mainnet` by the prope
- **GRID_PROXY_MNEMONIC**="word1 word2 ... word24"
- Write the seed phrase of an account on mainnet with at least 10 TFT in the wallet and a registered twin ID\*
> \*Note: If you've created an account using the ThreeFold Dashboard on a given network, the twin ID is automatically registered for this network.
> \*Note: If you've created an account using the ThreeFold Dashboard on mainnet, the twin ID is automatically registered.
## Set the Firewall
@@ -131,18 +110,16 @@ This will take some time since you are downloading the whole mainnet grid snapsh
Once you've deployed the grid stack online, you can access the different grid services by usual the usual subdomains:
```
dashboard.example.com
metrics.example.com
tfchain.example.com
graphql.example.com
relay.example.com
gridproxy.example.com
activation.example.com
stats.example.com
dashboard.your.domain
metrics.your.domain
tfchain.your.domain
graphql.your.domain
relay.your.domain
gridproxy.your.domain
activation.your.domain
stats.your.domain
```
In the case of testnet and devnet, links will also have the given subdomain, such as `dashboard.test.example.com` for a `testnet` instance.
## Manual Commands
Once you've run the install script, you can deploy manually the grid stack with the following command:

65
collections/developers/grid_deployment/snapshots.md
View File

@@ -4,10 +4,6 @@
- [Introduction](#introduction)
- [Services](#services)
- [ThreeFold Public Snapshots](#threefold-public-snapshots)
- [Requirements](#requirements)
- [Files for Each Net](#files-for-each-net)
- [Deploy All 3 Network Instances](#deploy-all-3-network-instances)
- [Deploy a Snapshot Backend](#deploy-a-snapshot-backend)
- [Deploy the Services with Scripts](#deploy-the-services-with-scripts)
- [Create the Snapshots](#create-the-snapshots)
- [Start All the Services](#start-all-the-services)
@@ -55,65 +51,6 @@ ThreeFold hosts all available snapshots at: [https://bknd.snapshot.grid.tf/](htt
rsync -Lv --progress --partial rsync://bknd.snapshot.grid.tf:34873/gridsnapshotsdev/processor-devnet-latest.tar.gz .
```
## Requirements
To run your own snapshot backend, you need the following:
- Configuration
- A working docker environment
- 'node key' for the TFchain public RPC node, generated with `subkey generate-node-key`
Hardware
- min of 8 modern CPU cores
- min of 32GB RAM
- min of 1TB SSD storage (high preference for NVMe based storage), preferably more (as the chain keeps growing in size)
- min of 2TB HDD storage (to store and share the snapshots)
Dev, QA and Testnet can do with a Sata SSD setup. Mainnet requires NVMe based SSDs due to the data size.
**Note**: If a deployment does not have enough disk input/output operations per second (iops) available, you might see the processor container restarting regulary and grid_proxy errors regarding processor database timeouts.
### Files for Each Net
Each folder contains the required deployment files for its net. Make sure to work in the folder that has the name of the network you want to create snapshots for.
What does each file do:
- `.env` - contains environment files maintaned by Threefold Tech
- `.gitignore` - has a list of files to ignore once the repo has been cloned. This has the purpose to not have uncommited changes to files when working in this repo
- `.secrets.env-examples` - is where you have to add all your unique environment variables
- `create_snapshot.sh` - script to create a snapshot (used by cron)
- `docker-compose.yml` - has all the required docker-compose configuration to deploy a working Grid stack
- `open_logs_tmux.sh` - opens all the docker logs in tmux sessions
- `typesBundle.json` - contains data for the Graphql indexer and is not to be touched
- `startall.sh` - starts all the (already deployed) containers
- `stopall.sh` - stops all the (already deployed) containers
### Deploy All 3 Network Instances
To deploy the 3 network instances, mainnet, testnet and mainnet, you need to follow the same process for each network on a separate machine or at least on a different VM.
This means that you can either deploy each network instance on 3 different machines, or you can also deploy 3 different VMs on the same machine, e.g. a dedicated node. Then, each VM will run a different network instance. In this case, you will certainly need a machine with NVME storage disk and modern hardware.
## Deploy a Snapshot Backend
Here's how to deploy a snapshot backend of a given network.
- Go to the corresponding network folder (e.g. `mainnet`).
```sh
cd mainnet
cp .secrets.env-example .secrets.env
```
- Open `.secrets.env` and add your generated subkey node-key.
- Check that all environment variables are correct.
```
docker compose --env-file .secrets.env --env-file .env config
```
- Deploy the snapshot backend. Depending on the disk iops available, it can take up until a week to sync from block 0.
```sh
docker compose --env-file .secrets.env --env-file .env up -d
```
## Deploy the Services with Scripts
You can deploy the 3 individual services using known methods such as [Docker](../../system_administrators/computer_it_basics/docker_basics.md). To facilitate the process, scripts are provided that run the necessary docker commands.
@@ -150,7 +87,7 @@ You can set a cron job to execute a script running rsync to create the snapshots
```
- Here is an example of a cron job where we execute the script every day at 1 AM and send the logs to `/var/log/snapshots/snapshots-cron.log`.
```sh
0 1 * * * sh /root/code/grid_deployment/grid-snapshots/mainnet/create_snapshot.sh > /var/log/snapshots/snapshots-cron.log 2>&1
0 1 * * * sh /opt/snapshots/create-snapshot.sh > /var/log/snapshots/snapshots-cron.log 2>&1
```
### Start All the Services

0
collections/developers/internals/zos/readme.md → collections/developers/internals/zos/zos_readme.md
View File

104
collections/developers/proxy/commands.md
View File

@@ -19,45 +19,45 @@ we are using [swaggo/swag](https://github.com/swaggo/swag) to generate swagger d
- install swag executable binary
```bash
go install github.com/swaggo/swag/cmd/swag@latest
```
```bash
go install github.com/swaggo/swag/cmd/swag@latest
```
- now if you check the binary directory inside go directory you will find the executable file.
```bash
ls $(go env GOPATH)/bin
```
```bash
ls $(go env GOPATH)/bin
```
- to run swag you can either use the full path `$(go env GOPATH)/bin/swag` or export go binary to `$PATH`
```bash
export PATH=$PATH:$(go env GOPATH)/bin
```
```bash
export PATH=$PATH:$(go env GOPATH)/bin
```
- use swag to format code comments.
```bash
swag fmt
```
```bash
swag fmt
```
- update the docs
```bash
swag init
```
```bash
swag init
```
- to parse external types from vendor
```bash
swag init --parseVendor
```
```bash
swag init --parseVendor
```
- for a full generate docs command
```bash
make docs
```
```bash
make docs
```
## To start the GridProxy server
@@ -65,24 +65,24 @@ After preparing the postgres database you can `go run` the main file in `cmds/pr
The server options
| Option | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| -address | Server ip address (default `":443"`) |
| -ca | certificate authority used to generate certificate (default `"https://acme-staging-v02.api.letsencrypt.org/directory"`) |
| -cert-cache-dir | path to store generated certs in (default `"/tmp/certs"`) |
| -domain | domain on which the server will be served |
| -email | email address to generate certificate with |
| -log-level | log level |
| -no-cert | start the server without certificate |
| -postgres-db | postgres database |
| -postgres-host | postgres host |
| -postgres-password | postgres password |
| -postgres-port | postgres port (default 5432) |
| -postgres-user | postgres username |
| -tfchain-url | tF chain url (default `"wss://tfchain.dev.grid.tf/ws"`) |
| -relay-url | RMB relay url (default`"wss://relay.dev.grid.tf"`) |
| -mnemonics | Dummy user mnemonics for relay calls |
| -v | shows the package version |
| Option | Description |
|---|---|
| -address | Server ip address (default `":443"`) |
| -ca | certificate authority used to generate certificate (default `"https://acme-staging-v02.api.letsencrypt.org/directory"`) |
| -cert-cache-dir | path to store generated certs in (default `"/tmp/certs"`) |
| -domain | domain on which the server will be served |
| -email | email address to generate certificate with |
| -log-level | log level |
| -no-cert | start the server without certificate |
| -postgres-db | postgres database |
| -postgres-host | postgres host |
| -postgres-password | postgres password |
| -postgres-port | postgres port (default 5432) |
| -postgres-user | postgres username |
| -tfchain-url | tF chain url (default `"wss://tfchain.dev.grid.tf/ws"`) |
| -relay-url | RMB relay url (default`"wss://relay.dev.grid.tf"`) |
| -mnemonics | Dummy user mnemonics for relay calls |
| -v | shows the package version |
For a full server setup:
@@ -101,22 +101,22 @@ There is two types of tests in the project
- Found in `tests/queries/`
- Run with:
```bash
go test -v \
--seed 13 \
--postgres-host <postgres-ip> \
--postgres-db tfgrid-graphql \
--postgres-password postgres \
--postgres-user postgres \
--endpoint <server-ip> \
--mnemonics <insert user mnemonics>
```
```bash
go test -v \
--seed 13 \
--postgres-host <postgres-ip> \
--postgres-db tfgrid-graphql \
--postgres-password postgres \
--postgres-user postgres \
--endpoint <server-ip> \
--mnemonics <insert user mnemonics>
```
- Or to run a specific test you can append the previous command with
```bash
-run <TestName>
```
```bash
-run <TestName>
```
You can found the TestName in the `tests/queries/*_test.go` files.

36
collections/developers/proxy/db_testing.md
View File

@@ -16,30 +16,30 @@ We show how to use a database for testing.
## Run postgresql container
```bash
docker run --rm --name postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=tfgrid-graphql \
-p 5432:5432 -d postgres
```
```bash
docker run --rm --name postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=tfgrid-graphql \
-p 5432:5432 -d postgres
```
## Create the DB
you can either Generate a db with relevant schema to test things locally quickly, or load a previously taken DB dump file:
### Method 1: Generate a db with relevant schema using the db helper tool:
```bash
cd tools/db/ && go run . \
--postgres-host 127.0.0.1 \
--postgres-db tfgrid-graphql \
--postgres-password postgres \
--postgres-user postgres \
--reset \
```
```bash
cd tools/db/ && go run . \
--postgres-host 127.0.0.1 \
--postgres-db tfgrid-graphql \
--postgres-password postgres \
--postgres-user postgres \
--reset \
```
### Method 2: Fill the DB from a Production db dump file, for example if you have `dump.sql` file, you can run:
```bash
psql -h 127.0.0.1 -U postgres -d tfgrid-graphql < dump.sql
```
```bash
psql -h 127.0.0.1 -U postgres -d tfgrid-graphql < dump.sql
```

0
collections/developers/tfchain/tfchain.md → collections/developers/tfchain/dev_tfchain.md
View File