Skip to content

Deploy Your App

Intermediate

Introduction

This page covers how to take a finished Polkadot Product live with the playground CLI. By the end, your app bundle will be uploaded to the Bulletin Chain, registered under a DotNS name, and, if you choose, discoverable in the Polkadot Playground.

TestNet names end in .paseo, not .dot

DotNS top-level domains are per network. On Paseo Next v2, the TestNet the playground CLI targets by default, names are minted under .paseo: you deploy myproject57 and get myproject57.paseo, served at https://myproject57.paseo.li. Passing a name that ends in .dot is rejected with an actionable error, so pass the bare label (myproject57) and let the CLI append the environment's TLD.

A deploy is really four stages, and playground deploy walks you through all of them in one flow:

  • Build: Compile your Product into a static bundle of files (HTML, JS, CSS, assets) with playground build.
  • Register: Reserve a DotNS name for your Product through the on-chain name service. This is the address people use to reach it. See Register a .dot Domain.
  • Publish: Optionally list your Product in the public Playground directory so others can discover it. Deploying without publishing keeps it reachable at its DotNS address but unlisted. See List Your App.
  • Deploy: Upload the bundle to the Bulletin Chain and bind it to your name, so any Host can fetch and verify it directly.

If your Product includes a smart contract, the deploy flow can redeploy that too, covered in the contract prompt below.

Prerequisites

Before deploying, ensure you have:

Build Your App Bundle

Run playground build to compile your project into a deployable bundle.

playground build

The CLI auto-detects your project type and runs the appropriate build. The output is a set of static files (HTML, JS, CSS, assets) that will be uploaded in the next step.

Tip

If you have already built the project, you can skip this step. playground deploy will prompt you to reuse the existing build.

Deploy Your App

Run playground deploy to start the interactive deploy flow. The CLI walks you through a series of prompts, then shows a confirmation summary before uploading.

playground deploy

The CLI presents the following prompts in order:

  1. Review app detail page: A reminder that your README.md becomes your app's detail page on the playground. Make sure it's up to date, then press Enter to continue (or Esc to exit and edit it first).

  2. Redeploy contracts if changed: Smart contracts hold your app's on-chain logic and data, and deploy separately from your website. Choose no if you only changed the website. Choose yes if you changed contract code in this project. The CLI then redeploys and reinstalls the contracts and rebuilds the site to match. See Add a Smart Contract to Your Product for the contract workflow in depth.

      did you change your smart contracts?
  › no  ·  I only changed the website
    yes  ·  I changed contract code too

  3. Choose to rebuild before deployment: Compiles your latest code into the files that get uploaded. Choose yes to rebuild now, or no to redeploy the build that's already in your build folder.

      build before deploy?
  › yes  ·  rebuild with my latest code
    no  ·  redeploy the existing build

  4. Choose who signs the upload: Publishing writes to the blockchain, which needs a signature. The dev signer uses a shared test account: instant, no phone needed. The phone signer signs with your own logged-in account, with a few taps on your phone.

      who signs the upload?
  › dev signer  ·  fast, no phone needed
    your phone signer  ·  signs with your own account

    Your phone will prompt — check it

    With the phone signer, each step waits for you to approve it in the Polkadot App, and there is no push notification announcing that a prompt is waiting. If the deploy appears to stall — including a deliberate pause while your name is registered — open the app and look for a pending approval. See the troubleshooting entries for an unanswered phone prompt and the registration pause, and Accounts and Signing for which account the phone signer uses.

  5. Choose a default build directory: The folder holding your built site (the files that get uploaded). The default dist fits most projects. This example uses .next for a Next.js app.

      build directory  default: dist
  › .next█

  6. Choose a domain name: Pick the address people will use to reach your app. Enter the bare label, such as myproject57; the CLI appends the environment's TLD, so on Paseo Next v2 that becomes myproject57.paseo. Which names you may register depends on the base length (the label minus any two-digit suffix) and on whether that suffix is present:

    Base length Two-digit suffix Requirement
    9 characters or longer Either Open to everyone — no personhood check
    6 to 8 characters Yes Requires Lite Proof of Personhood
    6 to 8 characters No Requires Full Proof of Personhood
    5 characters or fewer Either Reserved for governance 

      domain
  › myproject57█

    The label also has to be 3 to 63 lowercase characters (a-z, 0-9, -), with no leading or trailing dash, and any trailing digit run must be exactly two digits that do not follow a dash. If registration is rejected, the name may already be taken or reserved for accounts with Proof of Personhood. See Register a .dot Domain for the full name rules.

  7. Publish to the playground: Choose yes to list your app in the public Polkadot Playground so others can find and open it. Choose no to still deploy it to your DotNS address, but keep it unlisted.

      publish to the playground?
  › yes  ·  list it in the public playground
    no  ·  deploy to my .paseo address only

  8. Review confirmation summary: The CLI shows a summary of your choices before uploading. Review it, then press Enter to deploy (or Esc to cancel). With the dev signer, no phone taps are needed and phone approvals reads none.

      playground deploy  ·  myproject57.paseo  ·  paseo next v2        v0.47.0
  ────────────────────────────────────────────────────────────────────────
    
  deploying myproject57.paseo
    
  signer        Dev signer (no phone taps for upload)
  build         skip (use existing)
  build dir     .next
  contracts     skip
  publish       DotNS only
    
  phone approvals none
    
  enter to deploy  ·  esc to cancel

    Press Enter to confirm. The CLI then runs the upload and on-chain registration steps. If you chose the phone signer, each step triggers an approval prompt in the Polkadot mobile app — open the app and approve when prompted. With the dev signer selected here, the upload and DotNS registration run automatically with no phone prompts, and the deploy finalizes:

      playground deploy  ·  myproject57.paseo  ·  paseo next v2        v0.47.0
  ────────────────────────────────────────────────────────────────────────
    
  frontend
    
  · build         skipped
  ✓ upload + dotns
    
  ✓ deploy complete
    
  url           https://myproject57.paseo.li
  domain        myproject57.paseo
  app cid       bafybeihvru3e6ojhopxj7xxwtafrpyvsha6kylzklryon5k67u4clr26re
  ipfs cid      bafybeigr2liqwftbmily4sdxvo7mq4atgboqsrpdadypmsbpkn7c25cwja

Open Your App

Once the deploy completes, the CLI prints the URLs for your app. Regardless of whether you published it to the playground, your app is live at its DotNS address and reachable through the web gateway, which appends .li to the full name:

https://myproject57.paseo.li

You can also navigate directly by entering your name in the Polkadot Desktop browser address bar:

myproject57.paseo

Successfully deployed app reachable at its DotNS URL

Either way, the app loads directly from the Bulletin Chain — no central server involved.

If you chose yes at the publish to the playground? prompt, your app is also listed in the public playground directory. Open playground.dot in Polkadot Desktop browser and your app appears under your name, so others can find and open it. If you chose no (DotNS only, as in this example), the app is still fully deployed and reachable at the URLs above, only unlisted in the directory.

Tip

If your app does not appear immediately, wait a few seconds and refresh. On-chain state propagation can take a short time after the deploy transaction finalizes, and the web gateway resolves your name through an in-browser light client. A curl or script against the gateway URL returns a generic gateway shell rather than your app — open it in a real browser. If it still does not resolve, see Troubleshooting.

Keep Your App Available

Data published to the Bulletin Chain, including your app bundle, is retained for about two weeks by default and must be renewed to persist beyond that. The exact retention window is still being finalized, so treat "about two weeks" as provisional. Renewal is a separate transaction that pushes the expiration forward without moving the data or changing its CID.

Renewal needs a bookkeeping handle from the original write: the (block, index) pair from the Stored event. That pair is captured at write time and cannot be cheaply recovered afterward, so record it when you publish.

The CLI deploy does not surface the renewal handle yet

playground deploy prints only the app cid and ipfs cid, not the block number and index that renewal needs, so a bundle deployed through the CLI has no captured renewal handle today. If your app must outlive the retention window, publish its data through the programmatic CloudStorageClient.store(...).send() path, which returns the (block, index) pair, and track it. See Store Data on Chain for the store receipt and renewal flow, and the Bulletin Chain renewal reference for the mechanics.

If a Deploy Fails

Deploy-time issues have named fixes in Troubleshooting:

Where to Go Next

  • Guide Register a .dot Domain

    The naming step in depth: availability rules, the commit-reveal flow, and managing your name.

    Register a .dot Domain

  • Guide List Your App

    Make your Product discoverable in the Playground and Browse directories.

    List Your App

  • Guide Store Data on Chain

    The store receipt, chunking, authorization, and the renewal handle in full.

    Store Data on Chain

Last update: September 2, 2026
| Created: June 16, 2026