Introduction

Welcome to the Planetr decentralized cloud platform. Planetr is an encrypted, secure, and cost-effective compute platform that enables you to decentralize compute jobs everywhere, using a simple logical instance.

The decentralized alternative to cloud services

Buying your own hardware is costly, and renting it from a cloud service provider is even more costly in terms of total cost of ownership. Planetr is about to change that. You can now obtain computing power in a more cost-effective manner. Decentralized computing is much more cost-effective than conventional cloud computing and is a geo-distributed solution.

How it Works

Planetr is a decentralized network of computers owned by individuals and companies across the internet. As a cloud consumer you install and run the Planetr gateway node to be part of the network. The gateway exposes various services like compute units to run docker containers, edge proxies and zero footprint functions as a service. The gateway monitors and manages the computing capacity of the network and delegates the computing task to an available node on the network.

There is no single point of failure or centralized location meaning outages, downtime and data breaches are virtually impossible. If a node goes offline for any reason, the gateway automatically redeploy the service to other available nodes.

Architecture

Planetr Network Diagram

Why Choose Planetr?

Developers have a wide range of choices for cloud servicese, but Planetr provides a number of key advantages to help developers build more secure and private applications. Planetr leverages the existing commodity computing hardware to build a large computing network. The network computing hardware is not owned or managed by a centralized body instead it is provided by the community.

What services are offered by Planetr?

Planetr is a bleeding edge technology platform which is continusouly focusing on more ways to help the developers and businesses by providing secure, decentralized solutions at reasonable cost. Since the cloud is built on commodity hardware spread across the globe connected with a thin peer-to-peer network fabrix, it is extremely complex to build features compared to a centralized cloud.

Planetr can help you with the following:

  • Run your applications on docker containers deployed on a decentralized cloud and save cost.
  • Leverage decentralized SOCKS proxies to exit your traffic from edge nodes across the globe.
  • Deploy functions to solve your complex computing or web data processing tasks on a zero-server-footprint mode.

You may read more bout these services on the products page or Get Started with Planetr.

Get Started with Planetr Gateway

We have a complete decentralized compute solution for you - no matter who you are and where you are on your decentralization journey.

  1. Review requirements
  2. Install & run Planetr gateway node
  3. Understand the use cases
  4. Read reference docs
  5. Fast learn with easy tutorials

Do you have extra computing capacity?

If you want to be part of the Planetr community, become a provider by renting your idling computing resources. It could be your laptop, desktop or unused share of your servers.

Requirements

Hardware Requirements

  • A Laptop, desktop or any cloud machine
  • Internet connection with reasonable bandwidth
  • 1GB Free RAM
  • 500MB Free disk space

Operating System Support

Currently Planetr gateway node can be run on any of the following operating systems:

  • MacOS 10.14 or newer (Intel Chip)
  • Windows 10 - 64 bit
  • Linux - 64 bit

This software only supports 64 bit operating systems.

Network

You dont need a public IP to run Planetr. It can be run on any broadband network behind NAT or router firewall.

The computer which runs the gateway needs to be up and connected to internet while you access Planetr services.

Installation

Planetr is a decentralized network of computers owned by individuals and companies across the internet. As a cloud consumer you install and run the Planetr gateway node to be part of the network. The gateway exposes various services like compute units to run docker containers, edge proxies and zero footprint functions as a service. The gateway monitors and manages the computing capacity of the network and delegates the computing task to an available node on the network.

Install Planetr Gateway

If you are going to access the Planetr cloud to deploy docker containers or run functions, you need to install the Planetr gateway node. Remember, Planetr is a decentralized cloud and hence there is ano central server to access!

Voila... you run your own node to the cloud. Choose the right installer beased on the machine you want to run the gateway node. Read more about requirements here.

Repository Folder

All configuration data is stored in a directory structure at ~/.planetr/. You can find databases, and config files there.

Planetr Gateway MacOS Installation

What’s included in the installer

The Planetr Gateway Desktop installation includes Planetr Gateway and Planetr CLI client.

Install Planetr Gateway Desktop on Mac

Planetr gateway is tested with Mac running Intel chip.

  1. Download Planetr Gateway Desktop Installer.

  2. Double-click Planetr-Gateway.dmg to open the installer, then drag the Planetr Gateway icon to the Applications folder.

  1. Open Finder and go to Applications folder

  1. Ctrl + click Planetr-Gateway in the Applications folder to see the context menu. Click Open.

The Planetr Gateway menu in the top status bar indicates that Planetr Gateway Desktop is running, and accessible from a terminal.

Click on the icon, and select Status to verify that you have the latest version.

Visit http://localhost:8080 to ensure that Gatway API is up and running.

Congratulations! You are now successfully running Planetr Gateway Desktop.

What next?

  1. If you would like to run the tutorial, go to the Planetr Gatway Desktop menu and select Get Started.

  2. Open the terminal and use Planetr CLI (planetr) command to interact with the gayeway.

Planetr Gateway also has REST API if you want to integrate with your application.

Planetr Gateway Windows Installation

What’s included in the installer

The Planetr Gateway Desktop installation includes Planetr Gateway and Planetr CLI client.

Install Planetr Gateway Desktop on Windows

Planetr gateway is tested with Windows 10 (64 bit).

  1. Download Planetr Gateway Desktop Installer.

  2. Double-click Planetr-Gateway-Setup.exe to open the installer and follow the instructions.

  3. Right click Planetr-Gateway icon on the Desktop and choose Run as Administrator.

Planetr Gateway need Administrator priviledges to work efficiently.

The Planetr Gateway menu in the system tray indicates that Planetr Gateway Desktop is running, and accessible from a command shell.

Congratulations! You are now successfully running Planetr Gateway Desktop.

What next?

  1. If you would like to run the tutorial, go to the Planetr Gatway Desktop menu and select Get Started.

  2. Open the terminal and use Planetr CLI (planetr) command to interact with the gayeway.

Planetr Gateway also has REST API if you want to integrate with your application.

Planetr Gateway Linux Installation

What’s included in the installer

The Planetr Gateway installation includes Planetr Gateway and Planetr CLI client.

Install Planetr Gateway on Linux

Planetr gateway is tested with any flavour of Linux 64 bit OS.

// Download & Install
$ wget https://planetr.io/latest/planetr-gateway-linux-amd64.tar.gz
$ tar -xf planetr-gateway-linux-amd64.tar.gz

// CLI commands help
$ planetr --help

// run gateway node 
// you may run in background using nohup
$ planetr gateway

Congratulations! You are now successfully running Planetr Gateway.

What next?

Use Planetr CLI (planetr) command to interact with the gayeway.

Planetr Gateway also has REST API if you want to integrate with your application.

Planetr Gateway Reference Documentation

This section includes the reference documentation for the Planetr gateway's various APIs, CLIs, and others.

Decentralized Compute Unit (DCU)

DCU stands for Decentralized Compute Unit. A DCU consists of a docker image which need to be run on the decentralized cloud with an instance specification which provisions the necessary computing resources.

You can run any docker image hosted on Docker Hub. All you need is the docker image name and access to pull the docker (currently only public images are supported without docker hub authentication).

Along with the docker image, you need to specify the instance size (sound familiar with AWS?). Various supported instance types and their cost is available on the pricing page.

To install Planetr gateway on your computer, please read the installation section.

DCU CLI Command Reference

// run planetr with --help to see all possible commands
$  planetr --help 

DCU CLI Commands

CommandDescription
dcu-runRun a new container on a DCU
dcu-startStart one or more stopped containers
dcu-stopStop one or more running containers
dcu-rmStop and remove one or more containers
dcu-execRun a command in a running container deployed on a DCU
dcu-psList all containers
dcu-infoDisplay information about a container
dcu-logsFetch the logs of a container
dcu-cp-toCopy a file to the container from the local filesystem
dcu-cp-fromCopy a file from the container to the local filesystem

Docker Container Networking

In order to access the service running on the Docker container, port mapping is supported. You can map one port of the container to your gateway machine. This works similar to docker container networking.

Note: Planetr port mapping is limited to one port. It could be HTTP, SSHD or custom port.

Decentralized Functions

The lowering of accidental complexity has been one of the most powerful indicators of computing advancement. The most recent effect of this progress is serverless technology. However, while it has removed most of the operational burden that was previously on developers' plates, it still leaves something to be desired in terms of end-user benefit. That will soon be a thing of the past thanks to a new breed of serverless applications.

Industry has progressed from Infrastructure as a Service (IaaS) to Platform as a Service (PaaS) to Functions as a Service (FaaS). It's quite liberating to go from managing physical servers, operating systems, hypervisors, container engines, load balancers, and so on to merely provisioning functions.

Power of WebAssembly

We built Planetr Functions, our new serverless compute environment, to give developers more power, scalability, and speed at the decentralized network. Planetr Functions is powered by WebAssembly. We chose WebAssembly because it's an emerging technology that we believe lays the foundation for what function computing will become: a more performant and flexible place to deliver websites and applications.

Planetr team is actively following the open-source projects from WebAssembly Community Group and the Bytecode Alliance. Planetr uses an adapted version of Wasmtime to power the functions on the network.

Functions CLI Command Reference

// run planetr with --help to see all possible commands
$  planetr --help 

Functions CLI Commands

CommandDescription
func-createCreate a decentralized function
func-editEdit a decentralized function
func-runRun a decentralized function
func-rmDelete a decentralized function
func-psList all decentralized functions
func-testTest a decentralized function locally

Writing Planetr Functions

To make it easier for developers, Planetr functions have signatures that are quite similar to AWS Lambda functions. The code is compiled into a Web Assembly binary and then deployed to the Planetr network.

To write functions, Planetr currently only supports the Rust programming environment.

As a next step please learn to create a web assembly.

Edge Proxy

The Edge proxy is the endpoint to which the User-Agent (eg web browser) connects and it has a few responsibilities:

  • Performing the TLS handshake for HTTPS connections
  • Routing requests to the corresponding application proxy stack
  • Implementing the HTTP/2 protocol
  • Request correlation
  • Serving custom error pages

To install Planetr gateway on your computer, please read the installation section.

Proxy CLI Command Reference

// run planetr with --help to see all possible commands
$ planetr --help

Proxy CLI Commands

CommandDescription
proxy-runRun a SOCKS5 proxy at the specified port
proxy-startStart one or more stopped proxies
proxy-stopStop one or more running proxies
proxy-rmStop and remove one or more proxies
proxy-psList all proxies

Planetr Gateway REST API Reference

API Documentation

Planetr Use Cases

Planetr may be used as a public cloud platform or to expand the capabilities and computing capacity of an existing cloud. It can also be used as a stand-alone platform to build your own private cloud.

You can use Planetr as a:

  • Public Cloud - A cloud that is not centralised (like AWS, GCP or Azure).
  • Hybrid Cloud - It can be integrated into an existing cloud to optimize functionality and computing capacity.
  • Private Cloud - Utilize the computing capacity of all idle machines in your office, regardless of geographical location.
  • Personal Cloud - Utilize the computing power of your/your friends' personal machines.

Public Cloud

Anyone with internet access can use Planetr as a public decentralised cloud by installing the Planetr gateway on a local computer, such as a personal laptop or a workstation. You can benefit from massive cost savings and scalability for the type of workload that Planetr cloud can support.

Planetr Public Cloud

Hybrid Cloud

If you already have a cloud infrastructure, you can expand its computing capabilities by combining it with Planetr cloud. Existing cloud with public IPs can be used for internet-facing services, with Planetr acting as a reverse proxy behind such services to perform compute-intensive tasks.

Planetr Hybrid Cloud

Private Cloud

Most businesses have a large number of idle machines in their office network that can be pooled to form a private cloud. This may be in the case of idle server capacity or simply employee desktops. To build a private cloud, install the Planetr Satellite on each of these nodes.

Without any additional configurations, you can expand it to different networks spanning multiple geographic locations. 

Planetr Private Cloud

Create a private network

Personal Cloud

If you are a freelancer who want to run computational jobs like graphic rendering for your customers or data analytics by crawling the internet, you can build a personal cloud on top of your own computing devises and even use idling resources of your friends and families.

Remember that it doesn't matter what kind of network they're on. Planetr is transparent to network devices such as NAT routers. It's as easy as that.

Planetr Personal Cloud

Create a private network

Planetr Use Cases

Planetr may be used as a public cloud platform or to expand the capabilities and computing capacity of an existing cloud. It can also be used as a stand-alone platform to build your own private cloud.

You can use Planetr as a:

  • Public Cloud - A cloud that is not centralised (like AWS, GCP or Azure).
  • Hybrid Cloud - It can be integrated into an existing cloud to optimize functionality and computing capacity.
  • Private Cloud - Utilize the computing capacity of all idle machines in your office, regardless of geographical location.
  • Personal Cloud - Utilize the computing power of your/your friends' personal machines.

Public Cloud

Anyone with internet access can use Planetr as a public decentralised cloud by installing the Planetr gateway on a local computer, such as a personal laptop or a workstation. You can benefit from massive cost savings and scalability for the type of workload that Planetr cloud can support.

Planetr Public Cloud

Hybrid Cloud

If you already have a cloud infrastructure, you can expand its computing capabilities by combining it with Planetr cloud. Existing cloud with public IPs can be used for internet-facing services, with Planetr acting as a reverse proxy behind such services to perform compute-intensive tasks.

Planetr Hybrid Cloud

Private Cloud

Most businesses have a large number of idle machines in their office network that can be pooled to form a private cloud. This may be in the case of idle server capacity or simply employee desktops. To build a private cloud, install the Planetr Satellite on each of these nodes.

Without any additional configurations, you can expand it to different networks spanning multiple geographic locations. 

Planetr Private Cloud

Create a private network

Personal Cloud

If you are a freelancer who want to run computational jobs like graphic rendering for your customers or data analytics by crawling the internet, you can build a personal cloud on top of your own computing devises and even use idling resources of your friends and families.

Remember that it doesn't matter what kind of network they're on. Planetr is transparent to network devices such as NAT routers. It's as easy as that.

Planetr Personal Cloud

Create a private network

Web Assembly & Rust

Planetr FaaS Vs other providers

Serverless computing is a method of developing and deploying cloud services without the need for servers to be managed. Serverless computing, as opposed to IaaS (Infrastructure-as-a-Service), provides a greater level of abstraction, promising improved developer productivity and lower operational expenses. Resource flexibility, zero operations, and pay-as-you-go are all important features of serverless computing.

What is FaaS

A new wave of cloud services, led by AWS Lambda, has made it possible for developers to create web services straight from code functions in recent years. Developers don't have to worry about setting up or managing servers. When requests come in, the cloud provider instantly builds an execution environment and scales it based on demand. Function-as-a-Service is the name for this method (FaaS). According to industry reports, FaaS is already popular among cloud users and could become the dominant form of cloud computing in the future.

How is it done

The rise of FaaS is fueled by improvements in virtualization and containerization, which make it easy to start and stop the execution environment frequently and with low overhead. As infrastructure for FaaS, leading public cloud providers use a mix of system VMs and application containers. System virtual machines, such as hypervisor-based VMs, enable isolation at the system or hardware level. They differ from high-level software-based language virtual machines like the Java virtual machine, JavaScript runtime, and WebAssembly virtual machine. Application containers, such as Docker, are quicker and lighter than system VMs, but they are less secure.

  • AWS Lambda is built on Firecracker, a lightweight virtualization technique. Firecracker, also known as microVM, is smaller and faster than typical system VMs, making it ideal for FaaS workloads.

  • Docker containers are used by IBM Cloud Functions to provide separation.

  • When deployed in the public cloud, Microsoft Azure Functions is compatible with Docker, but with extra VM protection.

  • Google Cloud Functions chose a middle ground. Its gVisor engine is built to run Docker on the cloud reliably. gVisor, on the other hand, is 2x slower than ordinary Docker.

Challenges

FaaS still has performance and scalability difficulties, even with the performance-optimized system VMs and application containers. To begin with, a cold start is slow. It could take seconds to setup and run a microVM or container. This is a critical issue for FaaS, as each function execution may need the creation of a new microVM or container. Because the function could run faster when the execution environment was "warmed up," this flaw resulted in inconsistent and unpredictable performance.

For each function call, the VM or container must put up a runtime software stack, which includes operating system-specific standard libraries. As a result, the footprint is somewhat enormous.

Customers are charged for coarse-grained resource usage, such as allocated memory and execution time, in the current generation of VM or container-based FaaS systems. Fine-grained use billing, such as CPU cycles for each function run, is not supported.

Web Assembly for FaaS

A light-weight strategy With user-submitted and untrusted code, serverless FaaS must provide a secure and segregated execution environment. WebAssembly has been recommended as a lighter and faster solution to FaaS. WebAssembly is a high-level language VM runtime, unlike system VMs and containers. WebAssembly began as a group effort to improve the performance of JavaScript in web browsers. The WebAssembly runtime provides a Software-based Fault Isolation sandbox for untrusted applications because it is meant to execute code obtained from the web.

WebAssembly is compatible with a variety of programming languages, including C/C++ and Rust. The WASI standard allows WebAssembly runtimes to interface with operating system resources, making it ideal for server-side applications.

Functions written in WebAssembly can be run safely and independently. Without requiring any code changes, those functions can be initiated and cancelled on demand across various underlying systems. WebAssembly can accurately assess finely-grained resource consumptions at runtime because it provides abstractions at the opcode level.

Performance and size are the most significant advantages WebAssembly offers over system VMs, microVMs, and containers. WebAssembly-based FaaS is currently available on the edge networks of smaller cloud providers like Fastly and Cloudflare.

Planetr Functions & WebAssembly

We at Planetr decided to use WebAssembly to enable FaaS in Planetr network because of its obvioud advantages stated above. Planetr supports Rust programming language to write functions and also provides a bootstrap project to make it easy. Other programming languages will supported in the future and is under active development. The following links will help you started with Planetr functions in just few minutes.

Other resources:

Become a Provider - Put Your Idling Computing Resurces to Work!

A Planetr user who owns computing resources and rents them to Planetr is known as a Node Operator. Node Operators can make money by selling their computing resources to customers on a peer-to-peer basis.

Use Existing Hardware

Becoming a node operator doesn’t require extra hardware or power-hungry CPUs. All you need is a solid internet connection and ability to run Docker engine and bandwidth.

Be the Cloud

By becoming a node operator you’re running the computing power for actual customers, all while getting paid. Become the decentralized cloud and disrupt the cloud industry.

Better Than Mining

Mining bitcoin is expensive, requires a lot of extra power, is not that profitable, and is much more difficult than becoming a Planetr node operator.

Get paid to build the future of cloud computing.

Turn your computer into a Planetr host node and earn money! All your resources will be utilized — not only GPU, but also CPU and RAM, as well as your disks and network. Let your equipment benefit you and others on real-world tasks.

Requirements

  • One or more Desktop, Laptop or Servers
  • Internet connection with reasonable bandwidth
  • Optional: Container runtime installed. Docker or Podman installed and running in each computer
  • Super user privileges to install and run
  • Have some technical experience

Operating System Support

Currently Planetr satellite node can be run on any of the following operating systems:

  • MacOS 10.14 or newer (Intel Chip)
  • Windows 10 - 64 bit
  • Linux - 64 bit (Ubuntu 20.04 LTS or newer is preferred)

This software only supports 64 bit operating systems.

Container Runtime Support

If you are installing Satellite on a machine with more than 8GB of spare RAM and 4 Cores of CPU, it is advised to install a container runtime to fully utilize the computing resources.

Planetr supports Docker on Windows and MacOS, and Podman is recommended for Linux.

Docker (for Windows, MacOS)

Please ensure Docker CE is installed and running. You may get started with Docker.

Podman (for Linux)

Please ensure Podman is installed and running. You may get started with Podman.

Repository Folder

All configuration data is stored in a directory structure at ~/.planetr-satellite/. You can find databases, and config files there.

Installation

MacOS - Install Planetr Satellite

Planetr satellite is tested with Mac running Intel chip.

  1. Download Planetr Satellite Desktop Installer.

  2. Double-click Planetr-Satellite.dmg to open the installer, then drag the Planetr Satellite icon to the Applications folder.

  3. Open Finder and go to Applications folder

  4. Ctrl + click Planetr-Satellite in the Applications folder to see the context menu. Click Open.

The Planetr Satellite icon and menu in the top status bar indicates that Planetr Satellite Desktop is running.

Click on the icon, and select Config to verify that you have the latest version.

Congratulations! You are now successfully running Planetr Satellite Desktop.

Windows - Install Planetr Satellite

Planetr satellite is tested with Windows 10 (64 bit).

  1. Download Planetr Satellite Desktop Installer.

  2. Double-click Planetr-Satellite-Setup.exe to open the installer and follow the instructions.

  3. Right click Planetr-Satellite icon on the Desktop and choose Run as Administrator.

Planetr Satellite need Administrator priviledges to work efficiently.

The Planetr Satellite menu in the system tray indicates that Planetr Satellite Desktop is running.

Click on the icon, and select Config to verify that you have the latest version.

Congratulations! You are now successfully running Planetr Satellite Desktop.

Linux - Install Planetr Satellite

Recommended Linux distro is Ubuntu Server v16, 18 or 20.

Ubuntu / Debian

$ curl https://planetr.io/latest/planetr-satellite-linux-amd64.deb -o planetr-satellite-linux-amd64.deb && sudo dpkg -i planetr-satellite-linux-amd64.deb

This will download and install Planetr satellite as a systemd service called planetr-satellite

To start the service:

$ sudo systemctl start planetr-satellite

To see the logs:

$ sudo journalctl -f -u planetr-satellite

To stop the Satellite:

$ sudo systemctl stop planetr-satellite

To uninstall and cleanup the files:

$ sudo dpkg -r planetr-satellite

Other Linux

$ cd ~
$ mkdir planetr-satellite
$ cd planetr-satellite
$ wget https://planetr.io/latest/planetr-satellite-linux-amd64.tar.gz
$ tar -xf planetr-satellite-linux-amd64.tar.gz
$ ./planetr-satellite

Keep the Satellite running. Press Ctr+C to stop the node.

Customizing the Computing Resources

Once the satellite is installed, you can specify how much CPU core and memory you want to allocate for the Planetr network. The default is 2 Core and 1GB RAM.

Edit /root/.planetr-satellite/config.env by:

$ sudo vi /root/.planetr-satellite/config.env

HOST_NAME=localhost
HTTP_PORT=7002
P2P_PORT=0
NETWORK_NAME=MERCURY
MAX_CPU_CORES=2
MAX_MEMORY_BYTES=1G
CONTAINER_RUNTIME=podman
WEB_PROXY_ENABLE=1

MAX_CPU_CORES=<cpu-cores> - Specify the number of CPU core allocated to the Planetr network.

MAX_MEMORY_BYTES=<memory> - Specify the amount of RAM allocated to Planetr network. You can use human readable values like M, G etc. For example: 8G will allocate 8 giga bytes of RAM.

Save the file and restart the service

$ sudo systemctl restart planetr-satellite

Finding Help

If you get stuck, help is always available. We provide you with 24/7 technical support.

Email: contact@planetr.io

Please be ready to provide all the required information to help us solve your issue. Also, please write up a step-by-step description of the actions that led to the error and provide us with the command outputs.

Run a Planetr Private Network

Most businesses have a large number of idle machines in their office network that can be pooled to form a private network. This may be in the case of idle server capacity or simply employee desktops. To build a private cloud, install the Planetr Satellite on each of these machines and specify a network name unique to your organisation.

Without any additional configurations, you can expand it to different networks spanning multiple geographic locations. 

Identify Computers With Capacity

As a first step, identify the computers which have extra capacity and ensure that they are connected to your network (LAN). It is advisable to have internet access on these machines. Make sure these computers meet the requirements to run Planetr Satellite node.

If you are running Windows or Ubuntud desktop, please adjust the power settings to ensure that the computer is running always. Also ensure that the computer is connected to the power mains.

Install Planetr Satellite

Please refer this link to install the Satellite node on every provider computer.

You may need to install Docker on these computers to run containers.

Configure the Private Network

Run Planetr Satellite node once, which will create the repo folder under your home directory called .planetr-satellite.

Stop the Satellite node.

Edit ~/.planetr-satellite/config.env file and change the network name to a unique name like your companyname. Also set the correct values for memory, CPU etc.

NETWORK_NAME=BIG-DATA-COMPANY

HOST_NAME=localhost
HTTP_PORT=7002
P2P_PORT=0
NETWORK_NAME=BIG-DATA-COMPANY
MAX_CPU_CORES=4
MAX_MEMORY_BYTES=4G
CONFIG_CONTAINER_ENABLE=1
CONFIG_WEB_PROXY_ENABLE=1
DOCKER_BINARY_FILE=docker

Save the file and restart the satellite node.

Repeat this for other provider machines as well. This is a one time setup and you are ready to go.

Gateway Node

Now that the Satellites are setup and running, you can access the network by installing and running the Planetr Gateway node on your laptop or any computer you wish to. Gateway is the entry to the network to assign and run the computing tasks.

Please refer this link to install the Gateway node.

Connect to the Private Network

Run Planetr Gateway node once which will create the repo folder under your home directory called .planetr.

Stop the Gateway node.

Edit ~/.planetr/config.env file and change the network name to the SAME unique name you specified for satellites.

NETWORK_NAME=BIG-DATA-COMPANY

HOST_NAME=localhost
HTTP_PORT=7001
P2P_PORT=0
NETWORK_NAME=BIG-DATA-COMPANY

Save the file and restart the Gateway node.

Congratulatons! You are running a private Planetr network now. You can run Planetr CLI commands on your Gateway now. The computing tasks will be deplaoyed only on your nodes.

Tutorial

Create your first decnetralized container

In this tutorial, you will learn how to launch the Busybox public docker image on Planetr decentralized cloud and interact with it using the Planetr gateway CLI interface.

This tutorial is aimed at someone who has basic knowledge of Docker and wants to get a basic and quick understanding of what Planetr is all about. We will not be going into depth about the intricacies of developing on Planetr, but will hopefully satisfy your curiosity so that you will continue your journey!

This tutorial should take you about 10 minutes to complete.

We only expect that:

  • You are generally familiar with software development and command line interfaces.
  • You are generally familiar with Docker and containers.
  • You are open to learning about the bleeding edge of decentralized development.

Let's Begin

On Planetr's decentralised cloud, run a Busybox docker image.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Make sure Planetr gateway is installed and running on your computer.

$ planetr -v

Run busybox on Planetr network using dcu-run command. This is similar to docker run command.

$ planetr dcu-run busybox g.micro
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT                        
c234uqv2hral761lkpbg Pending g.micro busybox 2021-04-26T10:58:11.938791+05:30  

Please note that the status is Pending. The gateway will attempt to laucnh your instance on the Planetr network now and once done, the status will become Running

You can run dcu-ps command to list all containers and check teh status. This is similar to docker ps command.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c234uqv2hral761lkpbg Pending g.micro busybox 2021-04-26T10:58:11.938791+05:30  

Congratulations! You ran your first docker image on the decentralized cloud. Your computer is now running the gateway to the cloud.

Please note that you may not even have docker installed on your computer and the busybox container is now running on a edge node somewhere on the internet. Mostly in some other country!

Now let us execute some busybox linux shell commands. Let us do the classic ls command to list the files in your container. This is similar to docker exec command.

$ planetr dcu-exec c234uqv2hral761lkpbg "ls"
bin
dev
etc
home
proc
root
sys
tmp
usr
var

Thats it! You can execute any other command in the remote container. Try "date" to see system date. Try "ps -eaf" to list all running processes.

Now stop and delete the container. Keeping the dcu running will consume cost.

$ planetr dcu-rm c234uqv2hral761lkpbg
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c234uqv2hral761lkpbg Deleting g.micro busybox 2021-04-26T10:58:11.938791+05:30 

Thank you for trying the first tutorial. You may continue with more tutorials.


Project source at: GitHub

Tutorial

Create your first decnetralized container

In this tutorial, you will learn how to launch the Busybox public docker image on Planetr decentralized cloud and interact with it using the Planetr gateway CLI interface.

This tutorial is aimed at someone who has basic knowledge of Docker and wants to get a basic and quick understanding of what Planetr is all about. We will not be going into depth about the intricacies of developing on Planetr, but will hopefully satisfy your curiosity so that you will continue your journey!

This tutorial should take you about 10 minutes to complete.

We only expect that:

  • You are generally familiar with software development and command line interfaces.
  • You are generally familiar with Docker and containers.
  • You are open to learning about the bleeding edge of decentralized development.

Let's Begin

On Planetr's decentralised cloud, run a Busybox docker image.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Make sure Planetr gateway is installed and running on your computer.

$ planetr -v

Run busybox on Planetr network using dcu-run command. This is similar to docker run command.

$ planetr dcu-run busybox g.micro
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT                        
c234uqv2hral761lkpbg Pending g.micro busybox 2021-04-26T10:58:11.938791+05:30  

Please note that the status is Pending. The gateway will attempt to laucnh your instance on the Planetr network now and once done, the status will become Running

You can run dcu-ps command to list all containers and check teh status. This is similar to docker ps command.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c234uqv2hral761lkpbg Pending g.micro busybox 2021-04-26T10:58:11.938791+05:30  

Congratulations! You ran your first docker image on the decentralized cloud. Your computer is now running the gateway to the cloud.

Please note that you may not even have docker installed on your computer and the busybox container is now running on a edge node somewhere on the internet. Mostly in some other country!

Now let us execute some busybox linux shell commands. Let us do the classic ls command to list the files in your container. This is similar to docker exec command.

$ planetr dcu-exec c234uqv2hral761lkpbg "ls"
bin
dev
etc
home
proc
root
sys
tmp
usr
var

Thats it! You can execute any other command in the remote container. Try "date" to see system date. Try "ps -eaf" to list all running processes.

Now stop and delete the container. Keeping the dcu running will consume cost.

$ planetr dcu-rm c234uqv2hral761lkpbg
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c234uqv2hral761lkpbg Deleting g.micro busybox 2021-04-26T10:58:11.938791+05:30 

Thank you for trying the first tutorial. You may continue with more tutorials.


Project source at: GitHub

Tutorial

Run a Web Server

On Planetr's decentralised cloud, run a Webserver with a sample website.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the demo docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network

$ planetr dcu-run -m 9001:3000 planetrio/demo-website g.micro
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Pending g.micro planetrio/demo-website 9001:3000 2021-04-17T14:48:06.568676+05:30

Please wait for the status to become 'Running'

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Running g.micro planetrio/demo-website 9001:3000 2021-04-17T14:48:06.568676+05:30

Now visit https://localhost:9001/ in a browser to access the demo website which is served by the docker image running in a remote node

Delete the DCU.

$ planetr dcu-rm c1tafjn2hraq06kud0bg
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Deleting g.micro planetrio/demo-website 9001:3000 2021-04-17T14:48:06.568676+05:30

Check status again.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT

Project source at: GitHub

Tutorial

Run Docker Exec Commands on Decentralized Container

Run a 'docker exec' command to execute command line applications

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the demo docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network

$ planetr dcu-run planetrio/demo-exec g.micro
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Pending g.micro planetrio/demo-exec 2021-04-17T14:48:06.568676+05:30

Please wait for the status to become 'Running'

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Running g.micro planetrio/demo-exec 2021-04-17T14:48:06.568676+05:30

planetrio/demo-exec docker image has two commands reverse and capitalize in /home folder

$ planetr dcu-exec c1tatan2hraq6c4g3rlg '/home/reverse "TOM AND JERRY"'
YRREJ DNA MOT

Delete the DCU.

$ planetr dcu-rm c1tatan2hraq6c4g3rlg
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tatan2hraq6c4g3rlg Deleting g.micro planetrio/demo-exec 2021-04-17T14:48:06.568676+05:30

Check status again.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT

Project source at: GitHub

Tutorail

Run a REST API Server (Microservice)

Run a REST API server on Planetr decentralised cloud.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the demo docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network

$ planetr dcu-run -p 9002:8080 planetrio/demo-restapi g.micro
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tb1mf2hraqacl2oung Pending g.micro planetrio/demo-restapi 9002:8080 2021-04-17T15:26:41.891416+05:30

Please wait for the status to become 'Running'

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tb1mf2hraqacl2oung Running g.micro planetrio/demo-restapi 9002:8080 2021-04-17T15:26:41.891416+05:30

planetrio/demo-restapi image has a REST API which echo the name passed with a Hello

Now visit https://localhost:9002/iron-man in a browser to see Hello iron-man! Now visit https://localhost:9002/John in a browser to see Hello John!

Delete the DCU.

$ planetr dcu-rm c1tb1mf2hraqacl2oung
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Deleting g.micro planetrio/demo-restapi 9002:3000 2021-04-17T14:48:06.568676+05:30

Check status again.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT

Project source at: GitHub

Tutorial

TensorFlow

Run TensorFlow through HTTP API.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the demo docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network

$ planetr dcu-run -p 9001:8080 planetrio/demo-tensorflow g.medium
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tb6tn2hraqacl2oup0 Pending g.medium planetrio/demo-tensorflow 9003:8080 2021-04-17T15:37:50.801558+05:30

Please wait for the status to become 'Running'. This docker image is 2GB in size, so allow time to load.

planetrio/demo-tensorflow image has an API recognize to pass an image (file or URL) and it recognize the image with score.

We will recognize any random image on the internet. For this demo, let us take this image

In a browser visit https://localhost:9001/recognize?img=https://akm-img-a-in.tosshub.com/sites/btmt/images/stories/lamborghini_660_140220101539.jpg

You will see an output:

{"filename": "https://akm-img-a-in.tosshub.com/...140220101539.jpg", "labels": [
{"label": "sports car","probability": 0.8717548},
{"label": "racer","probability": 0.09467805},
{"label": "cab","probability": 0.009529107},
{"label": "car wheel","probability": 0.0069874455},
{"label": "beach wagon","probability": 0.006662446}
]}

Delete the DCU.

$ planetr dcu-rm c1tb6tn2hraqacl2oup0
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Deleting g.micro planetrio/demo-tensorflow 9003:3000 2021-04-17T14:48:06.568676+05:30

Check status again.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT

Project source at: GitHub

Tutorial

How to securely connect to a decentralized container using SSH

Access the decentralized container through SSH client.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the demo docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network

$ planetr dcu-run -m 2222:22 planetrio/demo-sshd g.micro
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tbgjf2hraqacl2ouq0 Pending g.micro planetrio/demo-sshd 2222:22 2021-04-17T15:58:29.791084+05:30

Please wait for the status to become 'Running'. This docker image has SSHD daemon running with a user planetr

$ ssh planetr@localhost -p 2222

Enter password planetr789 and you are logged in with SSH! Play around with linux commands and 'exit' to come out of the ssh shell

Delete the DCU.

$ planetr dcu-rm c1tbgjf2hraqacl2ouq0
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT
c1tafjn2hraq06kud0bg Deleting g.micro planetrio/demo-sshd 2222:22 2021-04-17T14:48:06.568676+05:30

Check status again.

$ planetr dcu-ps
INSTANCE ID STATUS TYPE IMAGE NAME PORTS CREATED AT

Project source at: GitHub

Example: Run Chrome headless browser

Run Chrome headless browser on decentralized docker container.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the Chrome headless browser docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network. For this tutorial we will be using an alpine docker image planetrio/chrome-headless with chromium-headless installed. You can see the source files to build the docker image here.

$ planetr dcu-run planetrio/chrome-headless g.medium 
INSTANCE ID            STATUS    TYPE       IMAGE                       NAME   PORTS 
c2plvuv2hrandp11u5d0   Pending   g.medium   planetrio/chrome-headless     

Please wait for the status to become 'Running'

$ planetr dcu-ps
INSTANCE ID            STATUS    TYPE       IMAGE                       NAME   PORTS 
c2plvuv2hrandp11u5d0   Running   g.medium   planetrio/chrome-headless     

planetrio/chrome-headless docker image has an alias chrm to run the chromium-headless browser.

$ planetr dcu-exec c2plvuv2hrandp11u5d0 "chrm --no-sandbox --screenshot --hide-scrollbars https://planetr.io"

The above command should create a screen grab of the web site https://planetr.io (you can change this to any website URL). Check if the screenshot file screenshot.png is created within the container.

$ planetr dcu-exec c2plvuv2hrandp11u5d0  "ls -al"
total 40
drwxr-xr-x    1 chrome   chrome        4096 May 30 11:47 .
drwxr-xr-x    1 root     root          4096 May 30 06:20 ..
-rw-------    1 chrome   chrome       24920 May 30 11:47 screenshot.png

Copy the file to your local drive.

$ planetr dcu-cp-from c2plvuv2hrandp11u5d0 /usr/src/screenshot.png screenshot.png 
File copied.

Docker project at: GitHub

Example: Run Chrome puppeteer browser with puppeteer

Run Chrome puppeteer browser and with puppeteer on decentralized docker container.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Install and run the Chromium with puppeteer docker image on Planetr decentralized cloud

Make sure Planetr gateway is installed and running on your computer.

$ planetr dcu-ps

Create and run a decentralized compute unit (DCU) on Planetr network. For this tutorial we will be using an alpine docker image planetrio/chrome-puppeteer with chromium and puppeteer installed. You can see the source files to build the docker image here.

$ planetr dcu-run planetrio/chrome-puppeteer g.medium 
INSTANCE ID            STATUS    TYPE       IMAGE                       NAME   PORTS  
c2pnkbf2hraosbb0rmq0   Pending   g.medium   planetrio/chrome-puppeteer     

Please wait for the status to become 'Running'

$ planetr dcu-ps
INSTANCE ID            STATUS    TYPE       IMAGE                       NAME   PORTS 
c2pnkbf2hraosbb0rmq0   Running   g.medium   planetrio/chrome-puppeteer     

Run puppeteer code. There are two javascript files pdf.js and screenshot.js in /usr/src/ folder to start with.

$ planetr dcu-exec c2pnkbf2hraosbb0rmq0 "node screenshot.js https://planetr.io"

The above command should create a screen grab of the web site https://planetr.io (you can change this to any website URL). Check if the screenshot file screenshot.jpg is created within the container.

$ planetr dcu-exec c2pnkbf2hraosbb0rmq0  "ls -al"
total 84
drwxr-xr-x    1 chrome   chrome        4096 May 30 11:43 .
drwxr-xr-x    1 root     root          4096 May 30 06:48 ..
drwxr-xr-x    7 chrome   chrome        4096 May 30 07:33 .git
-rw-r--r--    1 chrome   chrome         438 May 30 06:48 Dockerfile
-rw-r--r--    1 chrome   chrome         934 May 30 07:32 README.md
drwxr-xr-x   56 chrome   chrome        4096 May 30 06:48 node_modules
-rw-r--r--    1 chrome   chrome       16518 May 30 06:41 package-lock.json
-rw-r--r--    1 chrome   chrome         204 May 30 06:40 package.json
-rw-r--r--    1 chrome   chrome         634 May 30 07:04 pdf.js
-rw-r--r--    1 chrome   chrome       22261 May 30 11:43 screenshot.jpg
-rw-r--r--    1 chrome   chrome         605 May 30 07:07 screenshot.js

Copy the file to your local drive.

$ planetr dcu-cp-from c2pnkbf2hraosbb0rmq0 /usr/src/screenshot.jpg screenshot.jpg
File copied.

Docker project at: GitHub

Tutorial

Run a SOCKS5 proxy on decentralized cloud

Run a decentralized SOCKS5 edge proxy at port number 8888.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Run SOCKS5 edge proxy

Make sure Planetr gateway is installed and running on your computer by visiting http://localhost:8080/

Create and run a decentralized edge proxy on Planetr network.

$ planetr proxy-run 8888
INSTANCE ID            STATUS    PORT   NAME   ERROR  
c218ao72hrar656dqsc0   Running   8888

Check the status of the proxy.

$ planetr proxy-ps
INSTANCE ID            STATUS    PORT   NAME   ERROR  
c218ao72hrar656dqsc0   Running   8888

Test the proxy by configuring a SOCKS5 proxy on your browser. Specify:

  • SOCKS Host: localhost
  • Port: 8888
  • Select SOCKS5 option.

See Configure Firefox if you need help with configuring firefox. You may visit WhatIsMyIP to see which edge node is routing your traffic to internet.

Stop the proxy.

$ planetr proxy-stop c218ao72hrar656dqsc0

Restart the proxy.

$ planetr proxy-start c218ao72hrar656dqsc0

Stop and delete the proxy.

$ planetr proxy-rm c218ao72hrar656dqsc0

Tutorial

Run a SOCKS5 proxy on decentralized cloud

Run a decentralized SOCKS5 edge proxy at port number 8888.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the Get Started section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Run SOCKS5 edge proxy

Make sure Planetr gateway is installed and running on your computer by visiting http://localhost:8080/

Create and run a decentralized edge proxy on Planetr network.

$ planetr proxy-run 8888
INSTANCE ID            STATUS    PORT   NAME   ERROR  
c218ao72hrar656dqsc0   Running   8888

Check the status of the proxy.

$ planetr proxy-ps
INSTANCE ID            STATUS    PORT   NAME   ERROR  
c218ao72hrar656dqsc0   Running   8888

Test the proxy by configuring a SOCKS5 proxy on your browser. Specify:

  • SOCKS Host: localhost
  • Port: 8888
  • Select SOCKS5 option.

See Configure Firefox if you need help with configuring firefox. You may visit WhatIsMyIP to see which edge node is routing your traffic to internet.

Stop the proxy.

$ planetr proxy-stop c218ao72hrar656dqsc0

Restart the proxy.

$ planetr proxy-start c218ao72hrar656dqsc0

Stop and delete the proxy.

$ planetr proxy-rm c218ao72hrar656dqsc0

Creating Web Assembly

Planetr Functions is powered by WebAssembly. We chose WebAssembly because it's an emerging technology that we believe lays the foundation for what function computing will become: a more performant and flexible place to deliver websites and applications.

Prerequisites

  • Basic understanding of Rust programming language
  • Rust and Cargo installed (steps below)
  • Planetr Gateway installed and running

Install Rust and Cargo

Follow this link to install Rust and Cargo.

Install cargo-generate

We will use a scaffolding tool to automate the project creation. It will build an entire directory structure based on current environment.

Install the cargo-generate by running the below command in a terminal:

$ cargo install cargo-generate

Install Web Assembly compile & build tool

Install wasm-pack to compile and build the web assembly.

$ cargo install wasm-pack

Or refer this link to install.

Create Planetr Functions Project

Using cargo generate we can create a new project. Please change the <project-name> to whatever you like (example: wasm-sum).

$ cargo generate --git https://github.com/planetrio/planetr-faas-waasm-template.git --name <project-name>
$ cd <project-name>

This will create a new folder with project name and will have toml file and src folder containing the rust code.

Folder Structure

Open and edit handler.rs file to implement the function logic in rust. The sample code below will take two parameter x, y and return the sum.


#![allow(unused)]
fn main() {
#[derive(Deserialize, Serialize)]
pub struct InputPayload {
    x: i32,
    y: i32,
}

#[derive(Deserialize, Serialize)]
pub struct OuputPayload {
    sum: i32,
}

pub fn handle_req(args: InputPayload, _ctx: Context) -> Result<OuputPayload, PlanetrError> {
    Ok(OuputPayload{
        sum: args.x + args.y,
    })
}
}

Build Web Assembly (WASM) file

Build the project using wasm-pack.

$ cd <project-name>
$ wasm-pack build

You should see something similar as build output.

[INFO]: 🎯  Checking for the Wasm target...
[INFO]: 🌀  Compiling to Wasm...
    Finished release [optimized] target(s) in 43.81s
[INFO]: ⬇️  Installing wasm-bindgen...
[INFO]: Optimizing wasm binaries with `wasm-opt`...
[INFO]: ✨   Done in 45.04s
[INFO]: 📦   Your wasm pkg is ready to publish at /.../wasm-sum/pkg.

Your compiled wasm library file is at: <project-name>/target/wasm32-unknown-unknown/release/<project-name>.wasm

Congratulations on your achievement! You've successfully developed the project, compiled it, and generated the wasm binary, which can now be deployed as a function to the Planetr gateway.

Creating Web Assembly

Planetr Functions is powered by WebAssembly. We chose WebAssembly because it's an emerging technology that we believe lays the foundation for what function computing will become: a more performant and flexible place to deliver websites and applications.

Prerequisites

  • Basic understanding of Rust programming language
  • Rust and Cargo installed (steps below)
  • Planetr Gateway installed and running

Install Rust and Cargo

Follow this link to install Rust and Cargo.

Install cargo-generate

We will use a scaffolding tool to automate the project creation. It will build an entire directory structure based on current environment.

Install the cargo-generate by running the below command in a terminal:

$ cargo install cargo-generate

Install Web Assembly compile & build tool

Install wasm-pack to compile and build the web assembly.

$ cargo install wasm-pack

Or refer this link to install.

Create Planetr Functions Project

Using cargo generate we can create a new project. Please change the <project-name> to whatever you like (example: wasm-sum).

$ cargo generate --git https://github.com/planetrio/planetr-faas-waasm-template.git --name <project-name>
$ cd <project-name>

This will create a new folder with project name and will have toml file and src folder containing the rust code.

Folder Structure

Open and edit handler.rs file to implement the function logic in rust. The sample code below will take two parameter x, y and return the sum.


#![allow(unused)]
fn main() {
#[derive(Deserialize, Serialize)]
pub struct InputPayload {
    x: i32,
    y: i32,
}

#[derive(Deserialize, Serialize)]
pub struct OuputPayload {
    sum: i32,
}

pub fn handle_req(args: InputPayload, _ctx: Context) -> Result<OuputPayload, PlanetrError> {
    Ok(OuputPayload{
        sum: args.x + args.y,
    })
}
}

Build Web Assembly (WASM) file

Build the project using wasm-pack.

$ cd <project-name>
$ wasm-pack build

You should see something similar as build output.

[INFO]: 🎯  Checking for the Wasm target...
[INFO]: 🌀  Compiling to Wasm...
    Finished release [optimized] target(s) in 43.81s
[INFO]: ⬇️  Installing wasm-bindgen...
[INFO]: Optimizing wasm binaries with `wasm-opt`...
[INFO]: ✨   Done in 45.04s
[INFO]: 📦   Your wasm pkg is ready to publish at /.../wasm-sum/pkg.

Your compiled wasm library file is at: <project-name>/target/wasm32-unknown-unknown/release/<project-name>.wasm

Congratulations on your achievement! You've successfully developed the project, compiled it, and generated the wasm binary, which can now be deployed as a function to the Planetr gateway.

Tutorial

Create your first decnetralized function

In this tutorial, you will learn how to write a simple function to calculate sum of two numbers in Rust language and run on Planetr decentralized cloud using Planetr gateway CLI interface.

This tutorial is aimed at someone who has basic knowledge of Function-as-a-service (AWS Lambda, Google Functions etc..) and wants to get a basic and quick understanding of Planetr decentralized functions. We will not be going into depth about the intricacies of developing on Planetr, but will hopefully satisfy your curiosity so that you will continue your journey!

This tutorial should take you about 10 minutes to complete.

We only expect that:

  • You are generally familiar with software development and command line interfaces.
  • You are generally familiar with Rust programming language.
  • You are open to learning about the bleeding edge of decentralized development.

Let's Begin

On Planetr's decentralised cloud, run a function to compute sum of two numbers.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the installation section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Make sure Planetr gateway is installed and running on your computer.

$ planetr -v

Create a web assembly

Follow this link to create a web assembly binary (.wasm file) with the rust code to add two numbers. After completing the steps, you should be having a wasm file named wasm-sum.wasm.

Deploy the 'sum' function

Deploy the sum function on Planetr network using func-create command. You can provide any name for the function using -n parameter.

$ planetr func-create wasm-sum.wasm -n sumfunc
INSTANCE ID            NAME      ENDPOINT                                       ERROR  
c2nmdr72hrahq4eraj8g   sumfunc   http://localhost:7001/f/c2nmdr72hrahq4eraj8g          

Please note the endpoint URL.

Run the 'sum' function using CLI

You can run the sum function using planetr func-run command.

$ planetr func-run c2nmdr72hrahq4eraj8g -a "{\"x\":10, \"y\":20}" -p
{
    "code": 200,
    "log": "begin\nend\n",
    "payload": {
        "sum": 30
    }
}

Where c2nmdr72hrahq4eraj8g is the Instance Id of the sum function created earler. It will be different for you.

{x:10, y:20} is the input payload JSON which defines x and y integers as input.

{"sum":30} is the result payload JSON which gives sum=30.

-p flag is to pretty print the JSON result and is optional.

Congratulations! You ran your first function on the decentralized cloud.

Provide the input through JSON file

You can also provide the input payload JSON in a file with -f parameter.

Create a file input.json with the input as below:

input.json

{x:10, y:20}

Now run the function with input json file.

$ planetr func-run c2nmdr72hrahq4eraj8g -f input.json -p
{
    "code": 200,
    "log": "begin\nend\n",
    "payload": {
        "sum": 30
    }
}

Run the 'sum' function using API

Planetr exposes the function as a REST API for you to integrate it with your application which may be written in any language of your choice (example: Java, PHP, Rust, Go, .Net, Python etc...)

The endpoint for the function is seen when you create the function which for this tutorial is http://localhost:7001/f/c2nmdr72hrahq4eraj8g

When you are invoking the function via API, use:

URL: http://localhost:7001/f/c2nmdr72hrahq4eraj8g
Content-type: application/json
Method: POST
Body: Input as JSON string

For example, the CURL request will be:

curl \
  --header "Content-type: application/json" \
  --request POST \
  --data '{"x":10, "y":20}' \
  http://localhost:7001/f/c2nmdr72hrahq4eraj8g

Thank you for trying the first function tutorial.

Tutorial

Create a function to crawl a web page and extract links

In this tutorial, you will learn how to write a simple function to crawl a web page and extract links in Rust language and run on Planetr decentralized cloud using Planetr gateway CLI interface.

This tutorial is aimed at someone who has basic knowledge of Function-as-a-service (AWS Lambda, Google Functions etc..) and wants to get a basic and quick understanding of Planetr decentralized functions. We will not be going into depth about the intricacies of developing on Planetr, but will hopefully satisfy your curiosity so that you will continue your journey!

This tutorial should take you about 10 minutes to complete.

We only expect that:

  • You are generally familiar with software development and command line interfaces.
  • You are generally familiar with Rust programming language.
  • You are open to learning about the bleeding edge of decentralized development.

Install and run Planetr Gateway on your computer

To install Planetr gateway on your computer, please read the installation section. This can be achieved on a laptop, a desktop computer, or a cloud instance.

Make sure Planetr gateway is installed and running on your computer.

$ planetr -v

Create a web assembly

Follow this link to create a web assembly binary (.wasm file). Provide the project name as web-crawler.

The Rust code to crawl the web page

Edit web-crawler/src/handler.rs and put the below rust code.


#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use planetr::wasm::Context;
use planetr::wasm::PlanetrError;
use std::collections::HashSet;
use select::document::Document;
use select::predicate::Name;

#[derive(Deserialize, Serialize)]
pub struct InputPayload {
    url: String,
}

#[derive(Deserialize, Serialize)]
pub struct OuputPayload {
   links: HashSet<String>,
}

pub fn handle_req(args: InputPayload, ctx: Context) -> Result<OuputPayload, PlanetrError> {
    //error condition
    if args.url == "" {
        return Err(PlanetrError::new("url cannot be empty"));
    }

    ctx.log(args.url.to_string());
    
    let html = match ctx.http_get(args.url){
        Ok(html) => html,
        Err(err) => return Err(err)
    };

    if html.len() == 0 {
        return Err(PlanetrError::new("HTML empty"));
    }

    let found_urls = Document::from(html.as_str())
        .find(Name("a"))
        .filter_map(|n| n.attr("href"))
        .map(str::to_string)
        .collect::<HashSet<String>>();
    
    Ok(OuputPayload{
        links: found_urls,
    })
}
}

Add the select Crate to Cargo.toml file as dependancy to parse the HTML file for links etc...

Cargo.toml:

[dependencies]
...
select = "0.4.3"
...

Now build the wasm binary.

$ cd web-crawler
$ wasm-pack build

After completing the steps, you should be having a wasm file named web-crawler.wasm under target/release/wasm32-unknown-unknown/release/ folder.

Deploy the 'web-crawler' function

Deploy the web-crawler function on Planetr network using func-create command. You can provide any name for the function using -n parameter.

$ planetr func-create web-crawler.wasm -n web-crawler
INSTANCE ID            NAME         ENDPOINT                                       ERROR  
c2mfref2hraufcj56qeg   web-crawler  http://localhost:7001/f/c2mfref2hraufcj56qeg          

Please note the endpoint URL.

Run the 'web-crawler' function using CLI

You can run the web-crawler function using planetr func-run command.

$ planetr func-run c2mfref2hraufcj56qeg -a "{\"url\":\"https://planetr.io\"}" -p
{
    "code": 200,
    "log": "begin\nhttps://planetr.io\nend\n",
    "payload": {
        "links": [
            "index.php",
            "why-planetr.php",
            "getstarted.php",
            "docs/usecases.html",
            "https://planetr.io",
            "docs/providers.html",
            "https://github.com/planetrio",
            "pricing.php",
            "products.php",
            "docs/index.html"
        ]
    }
}

Where c2mfref2hraufcj56qeg is the Instance Id of the sum function created earler. It will be different for you.

Run the 'sum' function using API

curl \
  --header "Content-type: application/json" \
  --request POST \
  --data '{"url" : "https://planetr.io"}' \
  http://localhost:7001/f/c2mfref2hraufcj56qeg

Thank you for trying the tutorial.