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)

1. 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

2. 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

2. 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 Faucet and ETH from the Faucet

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

2. 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.

3. Next, get some USDT tokens for testing deployment:

   • Select USDT from the token options.
   • Enter the same wallet address you used for ETH.
   • Click on the "Send Token" button.

4. Wait for both transactions to be confirmed.

5. Check if you got the test ETH and USDT tokens in your wallet:

sphnctl wallet balance --token USDT

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

Step 4: Get Some Arbitrum Sepolia ETH and Bridge to Spheron Chain (Optional)

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

Once you have obtained ETH on the Arbitrum Sepolia chain, you can use our bridge to transfer the ETH token to the Spheron chain. Here is the bridge URL for bridging the ETH token:

Spheron Bridge (opens in a new tab)

After bridging, check your balance on the Spheron chain to ensure the transfer was successful.

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:

1. Deposit USDT / any other token to the escrow wallet:

sphnctl payment deposit --amount 10 --token USDT

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.

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

sphnctl wallet balance --token USDT

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: 2min
  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: 2min
  mode: provider # or 'fizz' for Fizz Mode
  tier:
    - community
  compute:
    web:
      resources:
        cpu:
          units: 0.5
        memory:
          size: 1Gi
        storage:
          size: 1Gi
  placement:
    westcoast:
      attributes:
        region: us-east
      pricing:
        web:
          token: USDT
          amount: 50
deployment:
  web:
    westcoast:
      profile: web
      count: 1
EOF

2. 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.

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

• Fetching the deployment logs
• Fetching the deployment events
• Connecting to the deployment shell
• Updating your deployment
• Closing your deployment

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