Deploy Your App on Spheron Protocol

This guide will walk you through the steps to deploy and access your app on Spheron. Follow these steps carefully to ensure a successful deployment.

Step 1: Install Spheron Protocol `sphnctl` CLI (Linux, MacOS)

To install Spheron Protocol CLI using script, make sure you have curl (opens in a new tab) installed on your system. To check, quickly:

curl --version

To install the Spheron Protocol CLI on the system, just run this one command in your terminal and pass the password during the prompt:

curl -sL1 https://sphnctl.sh | bash

Verify Spheron Installation

# Verify the installation by using a simple command to check the Spheron version
sphnctl version

Step 2: Create a new wallet using the CLI

To create a new wallet, start by configuring the name of your key. Run the command below, replacing [wallet name] with a name of your choice:

sphnctl wallet create --name [wallet name]

Here is an example of how the result will look:

Created account xxx:
 path: /Users/mitrasish-personal/.spheron/xxxxxyx.json
 address: 0x5C2432F3cB41927212e46e7224036d78eF3F2A93
 secret: xxxxxxxxxx
 mnemonic: xxxxxx xxxxx xxxx xxxxx xxxxx xxxx xxxxx xxxxx

Make sure to read the output carefully and save your mnemonic phrase and key secret in a secure location.

Once created, the wallet will be saved locally at ~/.spheron. You can access the key-secret of the current wallet in ~/.spheron/config.json. The newly created wallet will automatically be set as the current wallet. If needed, you can change the wallet by following the instructions in the Changing Your Wallet section. You can also export the private key of your newly generated wallet. Please follow the instructions given in Export the Private Key of Wallet.

Step 3: Get Some test tokens from the Team and ETH from the Faucet

Visit the Spheron Faucet (opens in a new tab).

Spheron Faucet

First, get some ETH gas tokens on the Spheron chain:
- Select ETH from the list in the faucet.
- Enter the wallet address of the wallet you generated in the previous section.
- Click the "Send Token" button to start the transaction.
Wait for the transaction to be confirmed.
Reach out to the Spheron team on Discord's #build-chat channel to get some USDT, USDC, WETH, or CST tokens.
Check if you got the test ETH and USDT tokens in your wallet:

sphnctl wallet balance --token CST

This will show both USDT and ETH balances in your wallet.

Note:

You won't get USDT, USDC, WETH, or CST tokens from the Spheron Faucet. You will need to reach out to the Spheron team to get these tokens on the Discord's #build-chat channel.
Make sure to mention what you are building and how you are using Spheron Protocol, which compute or GPU you want to use and the duration you want to use it for. And finally, mention the wallet address you want to get the tokens in.

Step 4: Get Some Base Sepolia ETH from other faucets (Optional)

Note: This step is only necessary if you could not get ETH from the Spheron faucet in Step 3. You can skip this step if you successfully obtained ETH from the Spheron faucet.

In case you need an alternative source of ETH, you can obtain some on the Arbitrum Sepolia chain from the following faucets:

Faucet Operator	Faucet URL	Chain
QuickNode	https://faucet.quicknode.com/base/sepolia (opens in a new tab)	Base Sepolia
Alchemy	https://www.alchemy.com/faucets/base-sepolia (opens in a new tab)	Base Sepolia
Chainlink	https://faucets.chain.link/base-sepolia (opens in a new tab)	Base Sepolia
Ethereum Foundation	https://www.ethereum-ecosystem.com/faucets/base-sepolia (opens in a new tab)	Base Sepolia

Step 5: Deposit some token to Your Escrow Balance

Depositing your tokens into the escrow is the first step to deploying your app on the Spheron Protocol. Ensure you have sufficient tokens in your escrow balance to lock the necessary funds for the deployment. Please follow the instructions below to proceed:

Deposit USDT / any other token to the escrow wallet:

sphnctl payment deposit --amount 10 --token CST

Here, the amount must be in the full precision of the token. To determine the precision of the token you are depositing, please refer to the Supported Payment Tokens section.

Now check if you have a balance in an unlocked state in your wallet:

sphnctl wallet balance --token CST

Note: You can withdraw tokens from your unlocked balance at any time. However, if the tokens are in a locked state, you will not be able to withdraw them until you close your deployment. Upon closing, the locked tokens will be returned to the unlocked state after deducting provider charges and protocol fees.

Step 6: Deploy an app

Now let's deploy an app to Spheron Protocol. Please follow the instructions below to proceed:

Important: Choosing Your Deployment Mode

Spheron offers two deployment modes:

Provider Mode: For stable, production-grade deployments with larger compute resources.
Fizz Mode: For cost-effective, distributed deployments suitable for testing or less resource-intensive applications.

You can specify the mode in your ICL configuration under the profiles section. For example:

profiles:
  name: hello-world
  duration: 1h
  mode: provider  # or 'fizz' for Fizz Mode
  tier:
    - community
  // ... other profile configurations ...

For this guide, we'll use Provider Mode. You may use the sample deployment file as-is or modify it for your own needs as described in our ICL documentation. A typical modification would be to reference your own image instead of our image.

cat > gpu.yml <<EOF
---
version: "1.0"
 
services:
  web:
    image: jupyter/minimal-notebook:latest
    expose:
      - port: 8888
        as: 8888
        to:
          - global: true
    env:
      - TEST=test
profiles:
  name: hello-world
  duration: 1h
  mode: provider # or 'fizz' for Fizz Mode
  compute:
    web:
      resources:
        cpu:
          units: 0.5
        memory:
          size: 1Gi
        storage:
          size: 1Gi
  placement:
    westcoast:
      pricing:
        web:
          token: CST
          amount: 1
deployment:
  web:
    westcoast:
      profile: web
      count: 1
EOF

Deploy the configuration on Spheron Protocol, run:

sphnctl deployment create gpu.yml

Here is an example of how the result will look:

Checking ballance for wallet: 0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8
Validating SDL configuration.
SDL validated.
Sending configuration for provider matching.
Deployment order created: [Tx Hash]
Waiting for providers to bid on the deployment order...
Bid found.
Order matched successfully.
Deployment created using wallet 0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8
 lid: 44
 provider: 0x6634d41cccBD1E1576Ed4c6226832521A66bF874
 agreed price: 158747943694
Sending the manifest for deployment…
Deployment manifest sent, waiting for acknowledgment.
Deployment is finished.

The lid that we get from the deployment is called Lease ID & 44 is the Lease ID in this example. This is the identifier that you need to use to access your deployment's logs and status.

Step 7: Access Your Deployment

To access your deployment / lease details, you need to run this command to fetch it:

This will contain URL to access the deployment server, all the assigned ports and the URI to access it. With this you can check your deployment status.

sphnctl deployment get --lid 44

Here is an example of how the result will look:

Status of the deployment ID: 44
Deployment details:
 Status:  Matched
 Provider:  avaaaa
 Price per hour:  1.21222
 Start time:  2024-07-25T10:10:12Z
 
Services running:
  web
    URL: []
    Ports:
      - provider.provider.devnetasphn.com:42100 -> 8888 (TCP)
    Replicas: 1/1 available, 1 ready
    Host URI: provider.devnetasphn.com
    Region: us-east
    IPs: []

Step 8: Fetching Deployment Logs

To fetch your deployment logs, you need to use the Lease ID.

sphnctl deployment logs --lid 44

Here is an example of how the result will look:

Here is the logs for the Lease ID: 44
 
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Entered start.sh with args: jupyter lab
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Running hooks in: /usr/local/bin/start-notebook.d as uid: 1000 gid: 100
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Done running hooks in: /usr/local/bin/start-notebook.d
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Running hooks in: /usr/local/bin/before-notebook.d as uid: 1000 gid: 100
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Done running hooks in: /usr/local/bin/before-notebook.d
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Executing the command: jupyter lab
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] [I 2024-07-02 15:19:39.753 ServerApp] Package jupyterlab took 0.0000s to import
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] [I 2024-07-02 15:19:39.776 ServerApp] Package jupyter_lsp took 0.0222s to import
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] [W 2024-07-02 15:19:39.776 ServerApp] A _jupyter_server_extension_points function was not found in jupyter_lsp. Instead, a _jupyter_server_extension_paths function was found and will be used for now. This function name will be deprecated in future releases of Jupyter Server.
...

Step 9: Connect to the deployment shell

To connect to the deployment shell, you need to run this command:

sphnctl deployment shell web /bin/sh --lid 44 --stdin --tty

Once you run this command, you will be connected to the shell of the deployment.

NOTE: If the service name or command you need to pass contains spaces, enclose the entire string in quotes. This ensures it is treated as a single argument.

You can retrieve various information from the deployment or interact with your deployment you just made, such as:

Congratulations! Your app is now deployed and accessible. If you encounter any issues, reach out to Spheron Discord Support (opens in a new tab).

User Guide Infrastructure Composition Language

Deploy Your App on Spheron Protocol

Step 1: Install Spheron Protocol sphnctl CLI (Linux, MacOS)

Step 2: Create a new wallet using the CLI

Step 3: Get Some test tokens from the Team and ETH from the Faucet

Step 4: Get Some Base Sepolia ETH from other faucets (Optional)

Step 5: Deposit some token to Your Escrow Balance

Step 6: Deploy an app

Step 7: Access Your Deployment

Step 8: Fetching Deployment Logs

Step 9: Connect to the deployment shell

Step 1: Install Spheron Protocol `sphnctl` CLI (Linux, MacOS)