Skip to main content

First App Deployment

Introduction​

This tutorial will guide you through deploying a simple application on Acurast. By the end of this guide, you'll have your first project ready and deployment up and running.

tip

If you prefer to jump right in, you can take a look at one of the example projects:

You can either clone those repositories, or set up a blank Acurast starter project by running npx @acurast/cli new <project-name>.

Prerequisites​

  • Basic knowledge of Node.js and the Command Line
Other ways to deploy

This tutorial uses the CLI — the interactive path. You can also deploy programmatically with the SDK, or pay with USDC on Base via the Deploy Agent.

Setting up the Project​

The structure of a project looks exactly like a normal Node.js project, with one extra file: acurast.json — this configures the deployment and is covered below. See the Deployment Config reference for all fields.

Writing the code​

First, let's start by creating a simple node.js project. You can find the code of the example, including all the build steps and configurations, on GitHub

If you're interested only in the Acurast part of the tutorial, feel free to skip to the "Installing the Acurast CLI" step.

This app is a simple Express server that returns a "Hello, World!" message. This is the code of the app:

import express from "express";
import localtunnel from "localtunnel";

/**
 * WARNING: This subdomain is NOT secure and should not be used in production.
 * Anyone can simply overwrite it with their own project and hijack requests
 * This is simply for testing purposes. If you need a secure way to host your
 * project, please reach out to us.
 */
const LOCALTUNNEL_SUBDOMAIN = ""; // This is the subdomain where your webserver will be available. Eg. https://example.acu.run
const LOCALTUNNEL_HOST = "https://proxy.acu.run/";
const LOCAL_PORT = 3000;

if (!LOCALTUNNEL_SUBDOMAIN) {
  console.log("LOCALTUNNEL_SUBDOMAIN must be set");
  process.exit(1);
}

const app = express();
app.use(express.json());

app.get("/", (req, res) => {
  res.send(`<h1>Hello from Acurast!</h1>`);
});

app.listen(LOCAL_PORT, () =>
  console.log(`Server listening on port ${LOCAL_PORT}!`)
);

const startTunnel = async () => {
  const tunnel = await localtunnel({
    subdomain: LOCALTUNNEL_SUBDOMAIN,
    host: LOCALTUNNEL_HOST,
    port: LOCAL_PORT,
  });

  console.log("Tunnel started at", tunnel.url);
};

startTunnel();

This code starts a webserver using express on port 3000, then starts a localtunnel tunnel to make the server publicly available.

Set the LOCALTUNNEL_SUBDOMAIN variable to specify where the server will be available. If set to example, the URL will be https://example.acu.run.

note

This localtunnel server is not secure and should not be used in production. Work is underway to make this secure by default, but if a secure way to host your project is needed now, please reach out via the community channels.

Building the project​

To deploy a project to the Acurast Cloud, it needs to be bundled into a single js file. This example uses webpack. You can find the configuration in the example project on GitHub

Running npm run bundle will then output a single js file which includes all necessary dependencies.

The file is located in dist/bundle.js. It includes your code, as well as all the dependencies in a single file.

This is the file that will be deployed to the Acurast Cloud. You can run it locally with node dist/bundle.js to test it.

Setting up the Acurast CLI​

Now that the app is ready, the Acurast CLI needs to be set up. The CLI is a tool that allows you to deploy and manage your applications on the Acurast Cloud.

Installation​

Let's install the Acurast CLI globally using npm:

npm install -g @acurast/cli

To verify that the installation worked, you can run acurast in the terminal and it will show you the help page:

tutorial % acurast
     _                            _      ____ _     ___
    / \   ___ _   _ _ __ __ _ ___| |_   / ___| |   |_ _|
   / _ \ / __| | | | '__/ _` / __| __| | |   | |    | |
  / ___ \ (__| |_| | | | (_| \__ \ |_  | |___| |___ | |
 /_/   \_\___|\__,_|_|  \__,_|___/\__|  \____|_____|___|

Usage: acurast [options] [command]

A cli to interact with the Acurast Network.

Options:
  -v, --version               output the version number
  -h, --help                  display help for command

Commands:
  deploy [options] [project]  Deploy the current project to the Acurast platform.
  init                        Create an acurast.json and .env file
  live [options] [project]    Run the code in a live code environment on a remote processor
  open                        Open Acurast websites in your browser
  help [command]              display help for command

Adding Acurast Config to the Project​

The next step is to add the Acurast Config to the project. To do that, run the following command:

acurast init

This will start an interactive guide, which will create acurast.json and .env files.

tutorial % acurast init
Initializing Acurast CLI
There is no .env file, creating one now...
.env file created. Visit https://github.com/Acurast/acurast-cli to learn more.

The CLI will use the following address: 5GNimXAQhayQq8m8SxJt3xQmG2L3pGzeTkHopx9iPnrS6uHP

Visit the faucet to get some tokens: https://faucet.acurast.com?address=5GNimXAQhayQq8m8SxJt3xQmG2L3pGzeTkHopx9iPnrS6uHP

No package.json file found. This is unusual. Are you sure you are in the right directory?
? Enter the name of the project: tutorial
? Should the app be run one time or in an interval? One Time
? Enter the duration (eg. 1s, 5min or 2h): 1min
? What is the bundled javascript file to run? dist/bundle.js

🎉 Successfully created "acurast.json" and ".env" files

You can deploy your app using 'acurast deploy'

The defaults work well for this example. For all available fields and meanings, see the Deployment Config reference.

Getting ready for Deployment​

To deploy the application, one more step is needed: funding the account.

Mainnet vs Canary

The faucet only works on Canary (cACU). On Mainnet, ACU must be acquired via an exchange or bridge — see How to Get ACU.

[!TIP] You can import the mnemonic that was generated and stored in the .env file and import it in Talisman (Browser Extension) to access the same account in the Web Console.

Let's get some tokens on your new account. You can run the acurast deploy command, which will check your balance, and displays the link to the Faucet page.

tutorial % acurast deploy

Deploying project "tutorial"

Your balance is 0. Visit https://faucet.acurast.com?address=5GNimXAQhayQq8m8SxJt3xQmG2L3pGzeTkHopx9iPnrS6uHP to get some tokens.

Visit the link displayed in the CLI and follow the instructions to get some tokens. They should be available in a few seconds.

That's it! You're now ready to deploy your app.

Deploying the Application​

To deploy your application, run acurast deploy:

tutorial % acurast deploy

Deploying project "tutorial"

The CLI will use the following address: 5GNimXAQhayQq8m8SxJt3xQmG2L3pGzeTkHopx9iPnrS6uHP

The deployment will be scheduled to start in 5 minutes 0 seconds.

There will be 1 executions with a cost of 0.001 cACU each.

❯ Deploying project (first execution scheduled in 246s)
  ✔ Submitted to Acurast (ipfs://Qmdk1zGq2h9SiMLUQN845rB9ii6YbpQXdFTHz3j8zXQp8C)
  ✔ Deployment registered (DeploymentID: 3,461)
  ⠇ Waiting for deployment to be matched with processors
  ◼ Waiting for processor acknowledgements

Congratulations, your deployment is now being registered in the network and executed soon! Check the CLI for more information about the deployment process.

Deploy using Deploy Agent (x402)

You can use our Deploy Agent to deploy jobs using USDC on EVM base instead.

Verifying the Deployment​

If you followed this tutorial, then your app will be available at https://<your-subdomain>.acu.run. ("\<your-subdomain>" is the value you set for LOCALTUNNEL_SUBDOMAIN in the code).

Success! You've successfully deployed your first application on Acurast!

Next steps​

Join the Telegram or Discord to be part of the community!