User Guide
Deploy Your App

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
  1. 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
  1. Verify Spheron Installation
# Verify the installation by using a simple command to check the Spheron version
sphnctl -h

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 token from the Faucet

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

Spheron Faucet

  1. Choose USDT or any other token option and enter the wallet address of the wallet you generated in the previous section.

  2. Click on the Send Token button.

  3. Wait for the transaction to be confirmed.

  4. Check if you got the test USDT token on your wallet:

sphnctl wallet balance --token USDT

Note: If you have choosen a different token from the faucet, to check it's balance you need to pass the name of that token in all caps.

Step 2: Get Some Arbitrum Sepolia ETH

Below, you can find faucets for obtaining test ETH token for Arbitrum Sepolia chain.

Faucet OperatorFaucet URLChain
QuickNodehttps://faucet.quicknode.com/arbitrum/sepolia (opens in a new tab)Arbitrum Sepolia
Alchemyhttps://www.alchemy.com/faucets/arbitrum-sepolia (opens in a new tab)Arbitrum Sepolia
Chainlinkhttps://faucets.chain.link/arbitrum-sepolia (opens in a new tab)Arbitrum Sepolia
LearnWeb3https://learnweb3.io/faucets/arbitrum_sepolia/ (opens in a new tab)Arbitrum Sepolia

Step 3: 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 10000000 --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.

  1. Now check if you have balance in unlocked state in your wallet:
sphnctl wallet balance --token USDT

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 4: 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
  1. 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 5: 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:  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 6: 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 7: 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 GuideInfrastructure Composition Language