Deploy a Website or Application

Overview

With the growing popularity of permanently deployed apps, hosted on Arweave, along with the growing list of tools offered by AR.IO, several methods have been developed to automate the process of deploying a website and updating the ArNS name pointed at it. A particularly useful tool for this is permaweb-deploy from Forward Research.

permaweb-deploy is a cli tool that handles uploading a build folder to Arweave using Turbo, creating a manifest, and then updating an ArNS name to point at the new manifest. It being a cli tool makes it very easy to incorporate into a github actions flow. Setting up an automated deployment with permaweb-deploy is simple, but does require a few steps.

Getting Started

Installing package

permaweb-deploy is an npm package, and must be installed in any project before it can be used. If you are using npm, you can install the package with the below command:

npm install permaweb-deploy --save-dev

If you prefer yarn for your package installations, the process is slightly more involved. permaweb-deploy is not designed for installation with yarn, so you must provide the additional argument ignore-engines in order to skip over the yarn version error you would normally get with installation. There are two methods for doing so:

• Directly in the install command

  yarn add permaweb-deploy -D --ignore-engines
  

  CopyCopied!

• In a .yarnc file

  You can provide a file, named .yarnc in the same directory as your package.json in order to assign specific instructions to all of your yarn commands. Creating a .yarnc file with the line

  ignore-engines true
  

  CopyCopied!

  will have the same effect as providing the flag directly in your yarn command

Adding a Deploy Script

The simplest way to utilize the permaweb-deploy tool is to build it into a script in your package.json. Here you will provide all of the variables that permaweb-deploy needs in order to function properly, as well as ensure that your app is statically built before being uploaded.

"scripts": {
    "build": "vuepress build src",
    "deploy": "npm run build && permaweb-deploy --deploy-folder ./src/.vuepress/dist --arns-name <YOUR_ARNS_NAME>"
  },

Be sure to replace <YOUR_ARNS_NAME> with the name of the ArNS name you want to deploy to.

The above example shows a build script for a vuepress app, which will build the app into a static folder for deployment, and a deploy script which runs build and then permaweb-deploy. Your build script will look different depending on the framework you are using, but most will provide that for you when you create your app.

The permaweb-deploy command has two required arguments:

• --deploy-folder This is the relative path (from your package.json) to the build folder you want to upload. In a vuepress app, that will be ./src/.vuepress/dist unless you manually specify otherwise in your vuepress configuration. It will be different depending on your chosen framework and if you have modified the default location.

• --arns-name This is the ArNS name you want to deploy to. It must be an ArNS name that the wallet used to authenticate has ownership or controller privileges over, otherwise the deployment will fail at authentication in the ao process that controls the ArNS name.

Testnet

Permaweb-deploy supports both Mainnet and Testnet deployments. By default, it will deploy to Mainnet. To deploy to Testnet, you can provide the --ario-process flag as "testnet". If not provided, deployments will default to Mainnet.

Providing Arweave Wallet Keys

While using permaweb-deploy, you will be uploading data to Arweave using Turbo, as well as performing protected actions on an Arweave Name Token. Because of this, you will need to provide the keys to an Arweave wallet in order for the actions to be successful. The wallet must contain Turbo Credits to pay for the upload, and it must either be a controller or the owner of the ArNS name you are trying to update.

permaweb-deploy requires your wallet keyfile be encoded in base64 format. You can convert a local keyfile to base64, and copy the new value to your clipboard by using one of the below commands, depending on your operating system:

• Linux

base64 wallet.json | xclip -selection clipboard

• Mac

base64 -i wallet.json | pbcopy

• Windows (CMD)

base64 wallet.json | clip

Be sure to replace wallet.json with the path to your chosen wallet keyfile. Once you have this value saved to your clipboard, you can move on to the next step.

Create Github Secrets

Anyone who has your wallet keyfile (including the base64 formatted keyfile) has full control over your wallet and any of its assets. Because of this, you do not want to include it directly in your package.json script. Instead, keep the value safe by storing it in a github secret. You will create the secrets in the settings tab on your github repo, and the secrets will act as environmental variables in the github actions workflow.

You will need to create 1 secret

• DEPLOY_KEY: This is the base64 encoded version of your Arweave wallet keyfile.

Create Action Workflow

Github Actions allow you to perform specific actions whenever you push code to github. They are handled by using .yaml files provided in <root-of-project>/.github/workflows.

To get started, create a new file named deploy.yaml in the workflows directory, then paste the below inside of it:

name: Arweave Deploy

on:
  push:
    branches:
      - main

jobs:
  Arweave-build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js environment
        uses: actions/setup-node@v2
        with:
          node-version: "20"

      - name: Run deployment script
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
        run: |
          npm install
          npm run deploy

The above tells github to perform these actions when you push new code to the branch main

It then sets up a vps with nodejs v 20. When that is complete, it installs dependencies for your project using npm (You will need to add a step to install yarn if that is your preferred package manager), and runs your deploy script, which builds your static folder and then runs permaweb-deploy. It also loads your github secrets into environmental variables that can be used by your deploy script.

Deploying App

With the above setup complete, the only thing you need to do to deploy a new version of a permasite app to Arweave is push the updated code to branch main on github. Everything else is fully automated.