Deploying with ARIO Deploy

ARIO Deploy is the recommended CLI tool for hosting decentralised applications on ar.io.

It streamlines the entire deployment process by uploading your build folder to Arweave, creating Arweave manifests, and automatically updating your ArNS records in a single command.

Built on the Turbo SDK, ario-deploy offers flexible payment options including pre-funded Turbo Credits or on-demand topups using ARIO or Base-ETH tokens. It works seamlessly with both Arweave and EVM wallets, making it easy to integrate permanent hosting into your existing development workflow.

Prerequisites

Before starting, ensure you have:

• Node.js 18+ - Download from nodejs.org
• Upload Wallet - An Arweave JWK or EVM private key to pay for the upload
• Solana Wallet - A base58 Solana secret key that controls your ArNS name (for ArNS record updates)
• ArNS Name - Register one at arns.ar.io
• Command Line Familiarity - Basic terminal/shell knowledge

Project Setup

Let's create a new web application and configure it for deployment. ARIO Deploy works with any framework that generates a static build folder.

npx create-next-app@latest my-permaweb-app
cd my-permaweb-app

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  trailingSlash: true,
}

module.exports = nextConfig

npm install --save-dev @ar.io/deploy

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out"
  }
}

npm create vite@latest my-permaweb-app -- --template react
cd my-permaweb-app
npm install

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: './', // Use relative paths for Arweave
})

npm install --save-dev @ar.io/deploy

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && ario-deploy deploy --arns-name your-arns-name"
  }
}

Deploying from the Command Line

For this walkthrough, we'll deploy directly from the command line using inline credentials. For production apps, we recommend using GitHub Actions with secrets (covered later in this guide).

DEPLOY_KEY=$(base64 -i wallet.json) ARNS_KEY="your-base58-solana-key" npm run deploy

DEPLOY_KEY="0x1234567890abcdef..." ARNS_KEY="your-base58-solana-key" npm run deploy

Starting deployment...

✔ ARIO initialized
✔ ArNS record fetched for your-arns-name
✔ Signer created (arweave)
✔ Turbo initialized
✔ Turbo credits check passed
✔ Folder uploaded: abc123def456ghi789jkl012mno345pqr678stu901v
✔ ANT record updated

Deployment Successful!
┌─────────────┬───────────────────────────────────────────────┐
│ Tx ID       │ abc123def456ghi789jkl012mno345pqr678stu901v  │
│ ArNS Name   │ your-arns-name                               │
│ Undername   │ @                                             │
│ ArNS URL    │ https://your-arns-name.ar.io                  │
└─────────────┴───────────────────────────────────────────────┘

On-Demand Payment

Instead of pre-funding Turbo Credits, you can pay for deployments on-demand. ARIO Deploy will automatically convert tokens to credits as needed.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out",
    "deploy:on-demand": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --on-demand ario --max-token-amount 2.0"
  }
}

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --sig-type ethereum",
    "deploy:on-demand": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --sig-type ethereum --on-demand base-eth --max-token-amount 0.01"
  }
}

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && ario-deploy deploy --arns-name your-arns-name",
    "deploy:on-demand": "vite build && ario-deploy deploy --arns-name your-arns-name --on-demand ario --max-token-amount 2.0"
  }
}

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && ario-deploy deploy --arns-name your-arns-name --sig-type ethereum",
    "deploy:on-demand": "vite build && ario-deploy deploy --arns-name your-arns-name --sig-type ethereum --on-demand base-eth --max-token-amount 0.01"
  }
}

DEPLOY_KEY=$(base64 -i wallet.json) ARNS_KEY="your-base58-solana-key" npm run deploy:on-demand

DEPLOY_KEY="0x1234567890abcdef..." ARNS_KEY="your-base58-solana-key" npm run deploy:on-demand

The on-demand approach is ideal for:

• Frequent deployments where pre-funding isn't convenient
• CI/CD pipelines that need reliable automated deployments
• Multi-team projects where different wallets handle different apps

Automating with GitHub Actions

The simplest way to automate deployments is with the official ar-io/ar-io-deploy GitHub Action. It handles node setup, dedup caching, and PR preview comments automatically.

name: Deploy to Arweave

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Deploy to Arweave
        uses: ar-io/ar-io-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          arns-key: ${{ secrets.ARNS_KEY }}
          arns-name: ${{ secrets.ARNS_NAME }}

name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

jobs:
  preview:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Deploy preview
        uses: ar-io/ar-io-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          arns-key: ${{ secrets.ARNS_KEY }}
          arns-name: ${{ secrets.ARNS_NAME }}
          preview: 'true'
          github-token: ${{ secrets.GITHUB_TOKEN }}

git add .
git commit -m "Set up automated deployments"
git push origin main

Summary

You now know how to deploy permanent web applications using ario-deploy:

• Static site setup for Next.js and React + Vite with proper configuration
• Two-key model with separate upload (DEPLOY_KEY) and ArNS authority (ARNS_KEY) keys
• Flexible wallet options supporting Arweave, EVM, and Solana wallets
• Payment methods including pre-funded Turbo Credits and on-demand topups with ARIO or Base-ETH
• Command-line deployment with inline wallet credentials for quick deployments
• GitHub Actions automation with the official ar-io/ar-io-deploy action for production deploys and PR previews

For more details, see the ARIO Deploy GitHub repository.

In the next guide, you'll learn how to use undernames to manage multiple environments and versions of your application.