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.
If you prefer to jump right in, you can take a look at one of our 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
Setting up the Project
Project Structure
The structure of a project looks exactly like a normal Node.js project:
├── dist
│ └── bundle.js
├── LICENSE
├── README.md
├── acurast.json
├── package-lock.json
├── package.json
├── src
│ └── index.ts
├── .env
├── tsconfig.json
└── webpack.config.js
There is only one file that is specific to Acurast, which is acurast.json. This file is used to configure the deployment, and we will come back to it later in the tutorial.
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.
The app we will build is a simple Express server that will return 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.processor-proxy.sook.ch
const LOCALTUNNEL_HOST = "https://processor-proxy.sook.ch/";
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();
In this code, we start a webserver using express on port 3000. We then start a localtunnel tunnel to make the server publicly available.
We need to set the LOCALTUNNEL_SUBDOMAIN variable to specifiy where our server will be available. If we set it to example, then the URL will be https://example.processor-proxy.sook.ch.
This localtunnel server is not secure and should not be used in production. We are working on making this secure by default, but if you need a secure way to host your project now, please reach out to us.
Building the project
To deploy a project to the Acurast Cloud, it needs to be bundled into a single js file. In our example, we use 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 our app is ready, we need to set up the Acurast CLI. 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 our 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'
During the setup process, we set default values for most of the parameters, and they should work well for our example. You can always open the acurast.json file and change the configuration there. In the CLI Docs you will find more information about the possible configurations.
These are the files that were generated:
acurast.json:
{
"projects": {
"tutorial": {
"projectName": "tutorial",
"fileUrl": "dist/bundle.js",
"network": "canary",
"onlyAttestedDevices": true,
"assignmentStrategy": {
"type": "Single"
},
"execution": {
"type": "onetime",
"maxExecutionTimeInMs": 3600000
},
"maxAllowedStartDelayInMs": 10000,
"usageLimit": {
"maxMemory": 0,
"maxNetworkRequests": 0,
"maxStorage": 0
},
"numberOfReplicas": 1,
"requiredModules": [],
"minProcessorReputation": 0,
"maxCostPerExecution": 1000000000,
"includeEnvironmentVariables": [],
"processorWhitelist": []
}
}
}
.env:
ACURAST_MNEMONIC=bounce crack ostrich put entry comic wage all tilt nature rebel position
# ACURAST_IPFS_URL=
# ACURAST_IPFS_API_KEY=
Getting ready for Deployment
To deploy our application, we still need to do one thing. Getting some tokens from the faucet.
[!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.
Verifying the Deployment
If you followed this tutorial, then your app will be available at https://<your-subdomain>.processor-proxy.sook.ch. ("\<your-subdomain>" is the value you set for LOCALTUNNEL_SUBDOMAIN in the code).
Success! You've successfully deployed your first application on Acurast!
Bonus: Working with Secret Environment Variables
You can use secret environment variables in Acurast depoyments. The environment variables that are encrypted during deployment and only decrypted when the code is run on the processor. This is useful for storing sensitive information like API keys.
To use environment variables in your project, you first need to add them to the .env file. For example, let's say you have an API key that you want to keep secret. You can add it to the .env file like this:
# .env
API_KEY=your-api-key
To configure which of your deployments make use of the environment variables, we need to edit the acurast.json file and add all the environment variables we want to include in the deployment to the includeEnvironmentVariables array.
{
"projects": {
"tutorial": {
"projectName": "tutorial",
"fileUrl": "dist/bundle.js",
"network": "canary",
"onlyAttestedDevices": true,
"assignmentStrategy": {
"type": "Single"
},
"execution": {
"type": "onetime",
"maxExecutionTimeInMs": 60000
},
"maxAllowedStartDelayInMs": 10000,
"usageLimit": {
"maxMemory": 0,
"maxNetworkRequests": 0,
"maxStorage": 0
},
"numberOfReplicas": 1,
"requiredModules": [],
"minProcessorReputation": 0,
"maxCostPerExecution": 1000000000,
"includeEnvironmentVariables": ["API_KEY"],
"processorWhitelist": []
}
}
}
Then, in your code, you can access the environment variables like this:
const API_KEY = _STD_.env[API_KEY];
When you run acurast deploy, the environment variables will now automatically be added to your deployment.
If you run an interval based deployment with multiple executions, then you can even update the environment variables between executions. This is useful if you want to rotate your API keys regularly. To do that, simply update the .env file and run acurast deployments <id> -e. This will update the environment variables for the deployment with the given ID.
Conclusion
Congratulations! You've successfully deployed your first application on Acurast! For more advanced features and detailed documentation, refer to Acurast CLI Documentation. Also make sure to join our Telegram or Discord to be part of our community!
More Examples
For more inspiration, check out the Acurast Examples with examples showing various features: