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
permaweb-deploy is a cli tool that handles uploading a build folder to Arweave using Turbo
Before automating your deployments, be sure to build your app and check for exposed environmental secrets. Some app frameworks or build flows will build your app with the secrets exposed, and if you are using a tool like permaweb-deploy, those secrets will be uploaded to Arweave. Since the permaweb is permanent, this could pose a security risk, especially with a copy of your wallet keyfile required for the deployment automation.
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
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 --ignore-engines
-
In a
.yarnc
fileYou can provide a file, named
.yarnc
in the same directory as yourpackage.json
in order to assign specific instructions to all of your yarn commands. Creating a.yarnc
file with the lineignore-engines true
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 yourpackage.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.
The --arns-name
flag MUST be the top level name, not and undername. That is, if you want to deploy to undername_arnsname
you must set --arns-name arnsname
and not --arns-name undername_arnsname
.
There is the additional, optional flag --undername
. If you want to deploy your app to an undername on an ArNS name, provide that name with this flag.
--arns-name arnsname --undername undername
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
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 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.