Functions

Appwrite Functions allow you to extend and customize your Appwrite server functionality by executing your custom code. Appwrite can execute your custom code in response to any Appwrite system event like account creation, user login, or document update. You can also schedule your functions to run according to a CRON schedule or start them manually by triggering your function from an HTTP endpoint using the Appwrite client or server APIs.

Appwrite Functions run in a secure, isolated Docker container. By default, Appwrite supports multiple runtimes for different languages that you can use to run your code.

Getting Started

The quickest way to get started with Appwrite Functions is using the Appwrite CLI. The CLI comes with starter code and some simple commands to quickly create and deploy your functions. Once you have the CLI installed and setup with an Appwrite project, create your first function using:

appwrite init function

Give your function a name and choose your runtime. This will create a new starter function in the current directory and also add it to your appwrite.json file. Go ahead and deploy your function using :

appwrite deploy function

You can now head over to your Appwrite Dashboard, navigate to the Function settings and execute your function. You can find the status of your execution under the Logs tab.

Feel free to modify and play around with the starter code and use the appwrite deploy command to instantly deploy your changes to the Appwrite server.

The following sections will dive deeper into some more terminology and advanced concepts which can be useful when writing your function from scratch.

Writing your own Function

When writing your own Appwrite Function, you must export the code in certain ways depending on the language. This varies between languages so refer to the examples below.

• Node.js

  module.exports = async (req, res) => {
    const payload =
      req.payload ||
      'No payload provided. Add custom data when executing function.';
  
    const secretKey =
      req.env.SECRET_KEY ||
      'SECRET_KEY environment variable not found. You can set it in Function settings.';
  
    const randomNumber = Math.random();
  
    const trigger = req.env.APPWRITE_FUNCTION_TRIGGER;
  
    res.json({
      message: 'Hello from Appwrite!',
      payload,
      secretKey,
      randomNumber,
      trigger,
    });
  };

  Installing Dependencies

  Include a package.json along with your function, and Appwrite handles the rest! The best practice is to make sure node_modules folder is not part of your tarball.

• PHP

  <?php
  
  return function ($req, $res) {
    $payload =
      $req['payload'] ?:
      'No payload provided. Add custom data when executing function.';
  
    $secretKey =
      $req['env']['SECRET_KEY'] ?:
      'SECRET_KEY environment variable not found. You can set it in Function settings.';
  
    $randomNumber = \mt_rand() / \mt_getrandmax();
  
    $trigger = $req['env']['APPWRITE_FUNCTION_TRIGGER'];
  
    $res->json([
      'message' => 'Hello from Appwrite!',
      'payload' => $payload,
      'secretKey' => $secretKey,
      'randomNumber' => $randomNumber,
      'trigger' => $trigger,
    ]);
  };

  Installing Dependencies

  Include a composer.json file in your function, make sure to require autoload.php from vendor folder, and Appwrite will handle the rest!. The best practice is to make sure vendor directory is not part of your tarball.

• Python

  import random
  
  def main(req, res):
    payload = req.payload or 'No payload provided. Add custom data when executing function.'
  
    secretKey = req.env.get(
      'SECRET_KEY',
      'SECRET_KEY environment variable not found. You can set it in Function settings.'
    )
  
    randomNumber = random.random()
  
    trigger = req.env['APPWRITE_FUNCTION_TRIGGER']
  
    return res.json({
      'message': 'Hello from Appwrite!',
      'payload': payload,
      'secretKey': secretKey,
      'randomNumber': randomNumber,
      'trigger': trigger,
    })

  Installing Dependencies

  Include a requirements.txt file in your function, Appwrite will handle the rest!

• Ruby

  def main(req, res)
    payload =
      !req.payload.empty? ? req.payload :
      'No payload provided. Add custom data when executing function.'
  
    secretKey =
      req.env['SECRET_KEY'] ||
      'SECRET_KEY environment variable not found. You can set it in Function settings.'
  
    randomNumber = rand()
  
    trigger = req.env['APPWRITE_FUNCTION_TRIGGER']
  
    return res.json({
      :message => 'Hello from Appwrite!',
      :payload => payload,
      :secretKey => secretKey,
      :randomNumber => randomNumber,
      :trigger => trigger,
    })
  end

  Installing Dependencies

  Include a Gemfile in your function, Appwrite handles the rest!

• Deno

  export default async function (req: any, res: any) {
    const payload =
      req.payload ||
      'No payload provided. Add custom data when executing function.';
  
    const secretKey =
      req.env.SECRET_KEY ||
      'SECRET_KEY environment variable not found. You can set it in Function settings.';
  
    const randomNumber = Math.random();
  
    const trigger = req.env.APPWRITE_FUNCTION_TRIGGER;
  
    res.json({
      message: 'Hello from Appwrite!',
      payload,
      secretKey,
      randomNumber,
      trigger,
    });
  };

  Installing Dependencies

  No special steps are required for Deno, Appwrite handles everything!

• Dart

  import 'dart:math';
  import 'dart:async';
  
  Future <void> start(final req, final res) async {
    final payload =
      !req.payload?.isEmpty ? req.payload :
      'No payload provided. Add custom data when executing function.';
  
    final secretKey =
      req.env['SECRET_KEY'] ??
      'SECRET_KEY environment variable not found. You can set it in Function settings.';
  
    final randomNumber = new Random().nextDouble();
  
    final trigger = req.env['APPWRITE_FUNCTION_TRIGGER'];
  
    res.json({
      'message': 'Hello from Appwrite!',
      'payload': payload,
      'secretKey': secretKey,
      'randomNumber': randomNumber,
      'trigger': trigger,
    });
  }

  Installing Dependencies

  Include a pubspec.yaml file with your function, Appwrite handles the rest!

• Swift

  func main(req: RequestValue, res: RequestResponse) throws -> RequestResponse {
      let payload = req.payload.isEmpty 
          ? "No payload provided. Add custom data when executing function" 
          : req.payload
      
      let secretKey = req.env["SECRET_KEY"] 
          ?? "SECRET_KEY environment variable not found. You can set it in Function settings."
  
      let randomNumber = Double.random(in: 0...1)
  
      let trigger = req.env["APPWRITE_FUNCTION_TRIGGER"]
  
      return res.json(data: [
          "message": "Hello from Appwrite!",
          "payload": payload,
          "secretKey": secretKey,
          "randomNumber": randomNumber,
          "trigger": trigger,
      ])
  }

  With Swift, your entrypoint can be empty since Appwrite automatically infers it from the location of your main() function. Just ensure that your cloud function has a single declaration of main() across your source files.

  Installing Dependencies

  Include a Package.swift file with your function, Appwrite handles the rest!

When your function is called, you receive two parameters, a request and a response object. The request object contains all data that was sent to the function including environment variables. A schema of the request object can be found below and is the same for all runtimes.

The response object has two functions, send() and json() that can be used to send data back to the client. The types and implementation of these functions vary depending on runtime due to all languages being slightly different. You can check out implementation in the specific languages to learn more about them. The schema of the response object can be found below:

Create your Function

Before you can deploy your function, you will need to create a new function from your Appwrite project's dashboard. Access the Function settings from your project's left navigation panel. Click the 'Add Function' button and choose a function name and runtime. In your Functions settings page, you can also set your function event triggers, CRON schedule, and set secure environment variables for your function.

Deploy Your Function

Once you've written your function, you can now deploy it using the Appwrite CLI, the Appwrite Server API or manually from the Appwrite console.

• Unix

  appwrite functions createDeployment \
      --functionId=6012cc93d5a7b \
      --activate=true \
      --entrypoint="index.js" \
      --code="/myrepo/myfunction"

• CMD

  appwrite functions createDeployment ^
      --functionId=6012cc93d5a7b ^
      --activate=true ^
      --entrypoint="index.js" ^
      --code="/myrepo/myfunction"

• PowerShell

  appwrite functions createDeployment ,
      --functionId=6012cc93d5a7b ,
      --activate=true ,
      --entrypoint="index.js" ,
      --code="/myrepo/myfunction"

The command above accepts three parameters:

You can also create new code deployments using the Appwrite server API

Builds

Deployments needs to be built before they can be activated. This is automatically done after creating a deployment and the time taken can vary depending on the runtime.

If a build fails for any reason, the deployment's status is set to failed and you won't be able to activate it. You can however retry a build if you think it was caused by an external factor using the Retry Button on the Appwrite Dashboard or Retry Build endpoint with the buildId from the deployment.

To find more details about a deployment and reasons for its failure, you can use the Get Deployment endpoint using the deploymentId.

Deployments that have been built successfully are marked as ready and can be activated and executed.

Execute

Besides setting a schedule or allowing your function to listen to Appwrite’s system events, you can also manually execute your cloud functions from your Appwrite console or API.

To execute a function from the Appwrite console, click the 'Execute Now' button on your function's overview page. To execute a function from the API, send a POST request to the function execution endpoint.

The function execution endpoint is available from both Appwrite client and server APIs. To execute your function from the server API, you need an API key with 'execution.write' scope.

Executing the function from the client API requires the current user to have execution permission for the function. You can change the execution permission from the function's settings page in the Appwrite console, by default no user, team, or role has this permission.

• Web

  const sdk = new Appwrite();
  
  sdk
      .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
      .setProject('5df5acd0d48c2') // Your project ID
  ;
  
  let promise = sdk.functions.createExecution('[FUNCTION_ID]');
  
  promise.then(function (response) {
      console.log(response); // Success
  }, function (error) {
      console.log(error); // Failure
  });

• Flutter

  import 'package:appwrite/appwrite.dart';
  
  void main() { // Init SDK
    Client client = Client();
    Functions functions = Functions(client);
  
    client
      .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
      .setProject('5df5acd0d48c2') // Your project ID
    ;
  
    Future result = functions.createExecution(
      functionId: '[FUNCTION_ID]',
    );
  
    result
      .then((response) {
        print(response);
      }).catchError((error) {
        print(error.response);
    });
  }

• iOS

  import Appwrite
  
  func main() {
      let client = Client()
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
  
      let functions = Functions(client)
      let execution = functions.createExecution(
          functionId: "[FUNCTION_ID]"
      )
      print(execution.toMap())
  }

• Android

  import androidx.appcompat.app.AppCompatActivity
  import android.os.Bundle
  import kotlinx.coroutines.GlobalScope
  import kotlinx.coroutines.launch
  import io.appwrite.Client
  import io.appwrite.services.Functions
  
  class MainActivity : AppCompatActivity() {
      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          setContentView(R.layout.activity_main)
  
          val client = Client(applicationContext)
              .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
              .setProject("5df5acd0d48c2") // Your project ID
  
          val functions = Functions(client)
  
          GlobalScope.launch {
              val response = functions.createExecution(
                  functionId = "[FUNCTION_ID]",
              )
              val json = response.body?.string()        
          }
      }
  }

Abuse and Limits

Appwrite allows your project's end-users to execute Cloud Functions using client API or your client SDK. Execution is permitted to any user who has been granted the "execute" permission in your Cloud Functions settings page. The execution permission can accept any of the typical Appwrite permission types.

When triggering a Cloud Function execution from the client, your users will be limited to a specific amount of execution per minute to make sure your Appwrite server is not being abused. The default limit is 60 calls per 1 minute. You can edit this limit using the server environment variables.

Ignore Files

Library folders such as node_modules or vendor should not be included in your tarball since these dependencies will be installed during your function's build process. Similarly, you should not include files containing secrets in your deployment. You can use the Appwite CLI's file ignoring feature to exclude specific files from a deployment.

You can use the ignore property in your appwrite.json file to specify which files and folders should be ignored. This value must be an array of paths, as seen in the example below:

{
    ...
    "functions": [
        {
            "$id": "6213b58cb21dda6c3263",
            "name": "My Awesome Function",
            "runtime": "node-17.0",
            "path": "My Awesome Function",
            "entrypoint": "src/index.js",
            "ignore": [ "node_modules", ".env" ]
        },
        ...
    ],
}

The example configuration above would not deploy the folder node_modules and the file .env.

Alternatively, you can add a .gitignore file into your function folder and Appwrite CLI will ignore files specified in there. Keep in mind that if present, the ignore configuration in appwrite.json will nullify the .gitignore file configuration.

If you need to use a .gitignore file for your version control but don't want the Appwrite CLI to use it, you can specify the ignore key in appwrite.json to be an empty array.

Supported Runtimes

Appwrite provides multiple code runtimes to execute your custom functions. Each runtime uses a Docker image tied to a specific language version to provide a safe, isolated playground to run your team's code.

Below is a list of supported Cloud Functions runtimes. The Appwrite team continually adds support for new runtimes. You can easily change which runtimes your Appwrite setup supports by editing your server environment variables.

	Name	Image	Architectures
	node-14.5	openruntimes/node:v1-14.5	x86 / arm
	node-15.5	openruntimes/node:v1-15.5	x86 / arm
	node-16.0	openruntimes/node:v1-16.0	x86 / arm
	node-17.0	openruntimes/node:v1-17.0	x86 / arm
	php-8.0	openruntimes/php:v1-8.0	x86 / arm
	php-8.1	openruntimes/php:v1-8.1	x86 / arm
	ruby-3.0	openruntimes/ruby:v1-3.0	x86 / arm
	ruby-3.1	openruntimes/ruby:v1-3.1	x86 / arm
	python-3.8	openruntimes/python:v1-3.8	x86 / arm
	python-3.9	openruntimes/python:v1-3.9	x86 / arm
	python-3.10	openruntimes/python:v1-3.10	x86 / arm
	deno-1.12	openruntimes/deno:v1-1.12	x86
	deno-1.13	openruntimes/deno:v1-1.13	x86
	deno-1.14	openruntimes/deno:v1-1.14	x86
	dart-2.12	openruntimes/dart:v1-2.12	x86
	dart-2.13	openruntimes/dart:v1-2.13	x86
	dart-2.14	openruntimes/dart:v1-2.14	x86 / arm
	dart-2.15	openruntimes/dart:v1-2.15	x86 / arm
	dart-2.16	openruntimes/dart:v1-2.16	x86 / arm
	dotnet-3.1	openruntimes/dotnet:v1-3.1	x86 / arm
	dotnet-6.0	openruntimes/dotnet:v1-6.0	x86 / arm
	java-8.0	openruntimes/java:v1-8.0	x86 / arm
	java-11.0	openruntimes/java:v1-11.0	x86 / arm
	java-17.0	openruntimes/java:v1-17.0	x86 / arm
	swift-5.5	openruntimes/swift:v1-5.5	x86 / arm
	kotlin-1.6	openruntimes/kotlin:v1-1.6	x86 / arm
	cpp-17.0	openruntimes/cpp:v1-17	x86 / arm

Environment Variables

Environment variables supplied by Appwrite in addition to your own defined environment variables that you can access from your function code. These variables give you information about your execution runtime environment.

Appwrite SDKs in Functions

You can integrate Appwrite Functions with other Appwrite services by using the appropriate Server SDK for your runtime. You can find starter code for your function's runtime in the Appwrite Function Starter repository.

To initialize a Server SDK in a function, you need to provide your Appwrite project's endpoint and an API key as variables in the Settings tab of your Function. The ID of your Appwrite project is passed in automatically as APPWRITE_FUNCTION_PROJECT_ID.

Monitor & Debug

You can monitor your function execution usage stats and logs from your Appwrite console. To access your functions usage stats and logs, click the 'Usage' tab in your function dashboard.

The usage screen in your console will allow you to track the number of execution and your function CPU usage time. You can also review a detailed log of your function execution history, including the function exit code, output log, and error log.

Demos & Examples

There are many Cloud Function demos and examples created by the Appwrite team and community in multiple coding languages. These examples are available at our demos repository on GitHub. You can also submit your examples by submitting a pull-request.