DEV Community: Christy Jacob

Introducing Password Dictionary In Appwrite: A New Layer Of Security

Christy Jacob — Wed, 12 Apr 2023 09:45:28 +0000

The internet has undeniably brought a myriad of benefits to our lives, making it easier than ever to connect, share, and learn. However, these benefits come with a price. Our digital identities, personal information, and financial data are constantly at risk of being compromised. One of the primary culprits? Weak, commonly used passwords.

If you're an app developer, security is always on your mind. You'll also know your secure APIs are only as strong as your user's passwords, and users who aren't tech-savvy pick horrible passwords!

In Appwrite 1.3, we released two new features to help mitigate this risk and protect user data. Password History in combination with Password Dictionary prevent common pitfalls when users are faced with the need to set or update their passwords. In this post, we'll show you how Appwrite's Password Dictionary can prevent a potential data breach in your app.

⛔ The Problem: Commonly Used Passwords and Data Breaches

To understand the extent of the problem, let's take a look at some real-life examples of data breaches caused by commonly used passwords.

The Yahoo Data Breach (2013-2014)

In 2013 and 2014, Yahoo suffered two massive data breaches affecting over 3 billion user accounts. While the breaches were orchestrated by a state-sponsored hacker group that used various sophisticated techniques, the use of weak passwords by Yahoo users exacerbated the situation. Once the hackers had access to Yahoo's databases, they were able to crack and compromise many user accounts more quickly and easily because a significant portion of the users had weak, commonly used passwords.

An analysis of the leaked data revealed that many users relied on simple, easily guessable passwords like "123456," "password," and "qwerty." These weak passwords made it easier for the attackers to use brute-force or dictionary attacks to crack them, thus providing an open door for attackers to compromise user accounts and gain unauthorized access to personal information.

The LinkedIn Data Breach (2012)

In 2012, LinkedIn suffered a data breach that affected 167 million user accounts. Again, weak passwords played a significant role in the breach. A staggering 65% of the leaked passwords were easily crackable due to their simplicity or their appearance on common password lists. This breach not only highlighted the importance of strong, unique passwords but also the need for organizations to protect users from themselves by implementing better security measures.

These examples demonstrate the risks associated with using weak, commonly used passwords. But what can be done to mitigate this problem?

🔐 Introducing Password Dictionary

A password dictionary is a tool designed to help address the issue of weak, commonly used passwords. It is essentially a large database of commonly used passwords that are considered insecure. When a user attempts to set a new password, the password dictionary checks if the proposed password is on the list. If it is, the user is prompted to choose a different, more secure password.

The newly introduced password dictionary in Appwrite adds an additional layer of security for user accounts. By preventing users from setting commonly used passwords, the password dictionary:

Reduces the risk of password-based attacks
Encourages stronger passwords
Enhances overall system security

By default, the Password Dictionary is disabled. To enable it, head over to the Auth section in your project and look for the Security tab in the top navigation bar.

Scroll down to find the Password Dictionary settings and enable it. Password Dictionary will now be enforced for all new users that sign up as well as when users try to update their passwords.

⏭️ What’s next?

As we continue to rely on digital services in our daily lives, it is crucial for individuals and organizations alike to prioritize security. By making strong, unique passwords the norm rather than the exception, we can all contribute to a safer and more secure digital world.

You can learn more about Password History, which is another security measure to protect users from reusing their old passwords and all the other cool features added in the latest version of Appwrite in our announcement post.

Phone Authentication with Appwrite and Twilio

Christy Jacob — Wed, 29 Jun 2022 14:28:58 +0000

Appwrite 0.15 was just announced and brings with it one of the most anticipated Appwrite features! Yes, you guessed that right! We’re introducing phone authentication in Appwrite! With this release you’ll now be able to authenticate users using their phone numbers. This release also introduces 3 new phone providers including Twilio, TextMagic & TeleSign!

In this tutorial we’ll learn how to set up a Twilio account and configure it for use with Appwrite and build a Svelte app to put it all together! The app will demonstrate the usage of all the new phone authentication endpoints introduced in Appwrite 0.15! Here's what we will learn:

To create sessions using a phone number and verify them.
To update a user’s phone number, send verification codes and update the verification status.

Without further ado, let’s get started!

🤔 New to Appwrite?

Appwrite is an open-source back-end-as-a-service that abstracts all the complexity of building a modern application by providing you with a set of REST and Realtime APIs for your core back-end needs. Appwrite takes the heavy lifting for developers and handles user authentication and authorization, databases, file storage, cloud functions, webhooks, and much more!

🧑‍💻 Setting up Twilio

The first step is to create a Twilio account. Head over to the Sign Up page, fill in your details, verify your email and phone number. On the Twilio Dashboard, click on the Get a Twilio phone number button.

This generates a phone number that we can use to send messages from. Under the Account Info section, you’ll find the Account SID, Auth Token and the newly generated phone number. Keep these handy as you’ll need them in the next step.

There’s one last thing that we need to do in the Dashboard before we move to the next step. Since we’re using Twilio’s free trial, we can only send an SMS to verified phone numbers. Head over to the Verified Callers IDs page and enter the numbers that you’d like to send messages to.

⚙️ Install Appwrite

Next, we need to get an Appwrite server up and running. You can either choose to install it locally on your system or deploy it on the cloud with one of our one click setups.

TLDR; It only takes a single magic command! 😊



docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:0.15.1

This command installs Appwrite and creates an appwrite folder with docker-compose.yml and .env files. Once the installation is complete, head over to the appwrite folder.

We need to update two variables in the .env file namely _APP_PHONE_PROVIDER and _APP_PHONE_FROM. _APP_PHONE_FROM is the phone number you just obtained from Twilio and _APP_PHONE_PROVIDER is a DSN string that helps Appwrite connect to the Twilio API.

_APP_PHONE_PROVIDER takes the following format



_APP_PHONE_PROVIDER=phone://<Account SID>:<Auth Token>@twilio

_APP_PHONE_FROM takes the following format



_APP_PHONE_FROM=+14344251928

You can obtain the Account SID, Auth Token and the phone number from the Account Info section of the Twilio Dashboard.

Once that is done, we need to restart the Appwrite server for the environment variables to take effect. Please note that this command needs to be executed from the appwrite folder that was created during installation.



docker compose up -d --force-recreate

Next, head over to localhost ( or your public IP address ) and create a new user account followed by a project with a name of your choosing.

Copy the projectId and the endpoint from the Settings page as we’ll need it for the web app we build in the next step!

🔮 Setting up Our SvelteKit Project

For the sake of this example, we’ll be using SvelteKit but the concepts and code examples remain true for all frameworks out there. First, we’ll need to create a new SvelteKit project and set up Tailwind CSS. I’ve found the official Tailwind installation guide to be extremely helpful here.

Instead of re-inventing the wheel here, I’d recommend you to complete the setup and return back to this tutorial.

Alright! It’s time to install some of our dependencies! We’ll be using two dependencies for our project. Head over to the project folder and install them with the following commands



npm i -D @zerodevx/svelte-toast
npm i appwrite

Next, add the following entries into your .env file. You might need to create this file if it does not exist already.



VITE_APPWRITE_ENDPOINT=http://localhost/v1
VITE_APPWRITE_PROJECT_ID=<YOUR_PROJECT_ID]

Don’t forget to replace the values with your own Appwrite projectId and endpoint that you obtained from the Dashboard earlier.

🔨 Setting up the Appwrite SDK

Next, let’s create our Appwrite service that will help abstract all the SDK calls to a single place. Create a new file src/lib/appwrite.ts and fill in the following contents



import { Client, Account } from 'appwrite';

const client = new Client();

client
    .setEndpoint(import.meta.env.VITE_APPWRITE_ENDPOINT)
    .setProject(import.meta.env.VITE_APPWRITE_PROJECT_ID);

const account = new Account(client);

export class AppwriteService {
    public static async getAccount(): Promise<any> {
        return account.get();
    }

    public static async createAccount(email: string, password: string, name?: string): Promise<any> {
        return account.create('unique()', email, password, name);
    }

    public static async createEmailSession(email: string, password: string): Promise<any> {
        return account.createEmailSession(email, password);
    }

    public static async deleteSession(): Promise<any> {
        return account.deleteSession('current');
    }

    /** Phone Authentication endpoints */
    public static async createPhoneSession(number: string): Promise<any> {
        return account.createPhoneSession('unique()', number);
    }

    public static async updatePhoneSession(userId: string, secret: string): Promise<any> {
        return account.updatePhoneSession(userId, secret);
    }

    public static async updatePhone(number: string, password: string): Promise<any> {
        return account.updatePhone(number, password);
    }

    public static async createPhoneVerification(): Promise<any> {
        return account.createPhoneVerification();
    }

    public static async updatePhoneVerification(userId: string, secret: string): Promise<any> {
        return account.updatePhoneVerification(userId, secret);
    }
}

Here, we import the appwrite SDK and initialize the Client and Account services. We also export an AppwriteService class with a lot of static methods that we can use across our app. The appwrite.ts file is all it takes to integrate Appwrite into the project. All the other files deal with the UI of the project and should be fairly straightforward to read and understand.

In order to keep this tutorial concise, we’ll just copy over the contents for all the other files from the completed GitHub project. Here are a list of files we need to copy

Toast.ts - This file contains the theming configuration for our toast messages
__layout.svelte - This file defines the base layout for all our screens
index.svelte - UI for the user profile page
login.svelte - UI for the login with email page
loginPhone.svelte - UI for the login with phone page
signup.svelte - UI for the signup page

Once complete, we’re all ready to preview the project. Run the following command to run a local development server.



npm run dev

That brings us to the end of this tutorial! I hope this guide helped you set up phone authentication in your web app and above all, I hope you enjoyed learning something new! I had a lot of fun learning Svelte and building a web app for this tutorial and I can’t wait to build some more apps!

📚 Resources

If you’re stuck at any point during the tutorial, feel free to reach out for help in our friendly discord channels run by humans! If you like what we do at Appwrite, don’t forget to drop us a tiny star on GitHub 😉 Here are some great resources to help you get started.

Cloud Functions Using the New Java Runtime

Christy Jacob — Fri, 20 May 2022 12:21:02 +0000

One of the highlights of Appwrite’s latest release is the addition of four new Cloud Function runtimes! Java, Kotlin, .NET and C++ are now a part of our ever growing list of runtimes! 🤯

In this article, we’ll take a look at writing Cloud Functions using the Java runtime. If you’re an Android developer, you could essentially build your app and write any necessary Cloud Functions without the need to learn any new language! 🤩

🤔 New to Appwrite?

Appwrite is open source backend-as-a-service that abstracts all the complexity involved in building a modern application by providing you with a set of REST APIs for your core backend needs. Appwrite handles user authentication and authorization, realtime databases, file storage, cloud functions, webhooks and much more! If there is anything missing, you can extend Appwrite using your favorite backend language.

📝 Prerequisites

Before we get started, there are a couple of prerequisites. If you have the prerequisites setup already, you can skip to the following section.

In order to follow along, you’ll need a few things beforehand.

🖥 An Appwrite instance

If you haven’t set up an Appwrite instance yet, you can follow the getting started guides to get up and running quickly. You can choose between One-click installations on DigitalOcean or Manual installations with Docker.

TL;DR - It's just a single command to install Appwrite

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:0.14.2

Once your server is up and running, head over to the Appwrite Dashboard on your server’s public IP address ( or localhost if you installed locally ) and create a new user account.

🧑‍💻 The Appwrite CLI

We’ll use the Appwrite CLI during this exercise as it makes the process super simple. If you have Node.js installed, the installation command is a simple

npm install -g appwrite-cli

If npm is not your thing, we have numerous installation options you can find in the getting started guide for the CLI

🏁 Getting Started

With everything set up, we can now begin! Login to the Appwrite CLI using the following command and use the credentials we used when setting up the Appwrite server to login.

appwrite login
? Enter your email test@test.com
? Enter your password ********
✓ Success

Next, we need to create a new Appwrite project to work with. We can use the following command to set it up

appwrite init project
? How would you like to start? Create a new Appwrite project
? What would you like to name your project? My Awesome Project
✓ Success

You can give your project any name of your choice. I’m going to stick to the defaults in this case. You’ll notice a new appwrite.json file in the current directory which stores all the information about your project.

It’s time to start writing our function! But wait, we don't need to start from scratch! The CLI can setup all the boilerplate for us using the following command

appwrite init function
? What would you like to name your function? java-example
? What runtime would you like to use? Java (java-17.0)
✓ Success

Give your function a name and choose the Java 17.0 runtime. This will create a new Appwrite Function in your project and set up all the boilerplate code necessary. Feel free to examine the files created in the functions/java-example directory. You’ll find the CLI created a simple Java function that returns a very important JSON message

{
    "areDevelopersAwesome":true
}

Before we go ahead and modify the function, let’s deploy it to get a feel of the end-to-end workflow from initializing the function to deploying it.

appwrite deploy function
? Which functions would you like to deploy? java-example (6286f6905af1e032e934)
ℹ Info Deploying function java-example ( 6286f6905af1e032e934 )
ℹ Info Ignoring files using configuration from appwrite.json
✓ Success Deployed java-example ( 6286f6905af1e032e934 )

The appwrite deploy function command packages your source code, uploads it to the Appwrite server and initiates the build process. During this time, all the function’s dependencies are installed and a .jar file is generated for your function.

You can head over to your Appwrite Dashboard to track the progress of your deployment.

Once the deployment completes, you can execute your function by clicking the Execute Now button.

The first execution results in what we call a Cold Start. Essentially this is the first time a runtime is created, so it takes a bit longer. As you can see, the first execution took about 331ms and subsequent executions were around 4ms. Now that we have an idea of the complete workflow, we can start tinkering with the code and write some cool functions.

🧮 Answering the Most Fundamental Question in Mathematics

As the title suggests we’re going to write a cloud function to answer one of the most fundamental questions in Mathematics.

Is the given number odd or even? I know what you’re thinking… It’s so easy! Why do I need a Cloud Function for it? I could just write

class Main {
    public static void main(String[ ] args) {
        int x = 12;
        System.out.println( x%2 == 0 ); // true
        System.out.println( (x/2) * 2 == x ); // true
        System.out.println( (x & 1) == 0 ); // true
        System.out.println( ( x >> 1) << 1  == x ); // true
    }
}

But wait! We’re taking this to the next level. We’re going to decide if our number is even or odd using one of the most sophisticated and well written APIs out there! The isEven API.

Jokes aside, this example aims to illustrate how you can make API calls from your Cloud Function which will enable you to build anything you’d like.

Firstly, open the java-example folder in your favorite IDE. Let’s start with a blank canvas and clean up our src/Index.java file to

import java.util.Map;
import java.util.HashMap;

public RuntimeResponse main(RuntimeRequest req, RuntimeResponse res) throws Exception {
    Map<String, Object> data = new HashMap<>();
    data.put("message", "Hello World!");
    return res.json(data);
}

In order to deal with JSON objects more easily, we’ll make use of the popular gson library. Include the following dependency in the deps.gradle file.

dependencies {
    implementation 'com.google.code.gson:gson:2.9.0'
}

Next, let’s write some code to read and parse a number sent as an argument to this function.

import java.util.Map;
import java.util.HashMap;
import com.google.gson.Gson;

final Gson gson = new Gson();

public RuntimeResponse main(RuntimeRequest req, RuntimeResponse res) throws Exception {

    String payloadString = req.getPayload() == null || req.getPayload().isEmpty() 
        ? "{}" 
        : req.getPayload();

    Map<String, Object> payload = gson.fromJson(payloadString, Map.class);

    String number = "2";
    if (payload.containsKey("number") && payload.get("number") != null) {
        number = payload.get("number").toString();
    }

    Map<String, Object> data = new HashMap<>();
    data.put("message", "Hello World!");
    return res.json(data);
}

Let’s go over the code we just wrote. From the functions documentation, we see that the payload is available through the request object and is a JSON string that needs to be converted to a JSON object to parse further. If the payload is empty, we replace it with an empty JSON object.

We then retrieve the number that was passed to the function and default to the number 2 in case it’s empty. We also import the gson library and create an instance of it.

Next, let’s make the call to the API using the native HTTP client.

import java.util.Map;
import java.util.HashMap;
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import com.google.gson.Gson;

final Gson gson = new Gson();

public RuntimeResponse main(RuntimeRequest req, RuntimeResponse res) throws Exception {

    String payloadString = req.getPayload() == null || req.getPayload().isEmpty() 
        ? "{}" 
        : req.getPayload();

    Map<String, Object> payload = gson.fromJson(payloadString, Map.class);

    String number = "2";
    if (payload.containsKey("number") && payload.get("number") != null) {
        number = payload.get("number").toString();
    }

    URL url = new URL("https://api.isevenapi.xyz/api/iseven/" + number);
    HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("GET");
    con.getResponseCode();

    BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
    String inputLine;
    StringBuilder responseString = new StringBuilder();
    while ((inputLine = in.readLine()) != null) {
        responseString.append(inputLine);
    }
    in.close();
    con.disconnect();

    Map<String, Object> response = gson.fromJson(responseString.toString(), Map.class);

    return res.json(response);
}

Awesome! We’re all set to test our function! If you remember the drill, all we need to do is deploy our function.

appwrite deploy function
? Which functions would you like to deploy? java-example (6286f6905af1e032e934)
ℹ Info Deploying function java-example ( 6286f6905af1e032e934 )
ℹ Info Ignoring files using configuration from appwrite.json
✓ Success Deployed java-example ( 6286f6905af1e032e934 )

You can now head over to the Appwrite console and execute the function with the following payload.

Head over to the Logs tab to check the status and response from the function.

Perfect! Looks like we’ve managed to solve one of the most pressing problems in Mathematics after all! Not to mention, the API also comes with a host of quirky Ads!

And that brings us to the end of this tutorial. Feel free to modify the function to your liking and play around with the API. If you’re stuck or need any help, we’re always here to help. Simply head over to the #support channels on our Discord Server 😊

📚 Resources

Here are some handy links for more information

Cloud Functions Using the New Kotlin Runtime

Christy Jacob — Fri, 20 May 2022 12:02:18 +0000

One of the highlights of Appwrite’s latest release is the addition of four new Cloud Function runtimes! Java, Kotlin, .NET and C++ are now a part of our ever growing list of runtimes! 🤯

In this article, we’ll take a look at writing Cloud Functions using the Kotlin runtime. If you’re an Android developer, you could essentially build your app and write any necessary Cloud Functions without the need to learn any new language! 🤩

🤔 New to Appwrite?

Appwrite is open source backend-as-a-service that abstracts all the complexity involved in building a modern application by providing you with a set of REST APIs for your core backend needs. Appwrite handles user authentication and authorization, realtime databases, file storage, cloud functions, webhooks and much more! If there is anything missing, you can extend Appwrite using your favorite backend language.

📝 Prerequisites

Before we get started, there are a couple of prerequisites. If you have the prerequisites setup already, you can skip to the following section.

In order to follow along, you’ll need a few things beforehand.

🖥 An Appwrite instance

TL;DR - It's just a single command to install Appwrite

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:0.14.2

Once your server is up and running, head over to the Appwrite Dashboard on your server’s public IP address ( or localhost if you installed locally ) and create a new user account.

🧑‍💻 The Appwrite CLI

We’ll use the Appwrite CLI during this exercise as it makes the process super simple. If you have Node.js installed, the installation command is a simple

npm install -g appwrite-cli

If npm is not your thing, we have numerous installation options you can find in the getting started guide for the CLI.

🏁 Getting Started

With everything set up, we can now begin! Login to the Appwrite CLI using the following command and use the credentials we used when setting up the Appwrite server to login.

appwrite login
? Enter your email test@test.com
? Enter your password ********
✓ Success

Next, we need to create a new Appwrite project to work with. We can use the following command to set it up

appwrite init project
? How would you like to start? Create a new Appwrite project
? What would you like to name your project? My Awesome Project
✓ Success

It’s time to start writing our function! But wait, we don't need to start from scratch! The CLI can setup all the boilerplate for us using the following command

appwrite init function
? What would you like to name your function? kotlin-example
? What runtime would you like to use? Kotlin (kotlin-1.6)
✓ Success

Give your function a name and choose the Kotlin 1.6 runtime. This will create a new Appwrite Function in your project and set up all the boilerplate code necessary. Feel free to examine the files created in the functions/kotlin-example directory. You’ll find the CLI created a simple Kotlin function that returns a very important JSON message

{
    "areDevelopersAwesome":true
}

Before we go ahead and modify the function, let’s deploy it to get a feel of the end-to-end workflow from initializing the function to deploying it.

appwrite deploy function
? Which functions would you like to deploy? kotlin-example (62863924adaff7c88a10)
ℹ Info Deploying function kotlin-example ( 62863924adaff7c88a10 )
ℹ Info Ignoring files using configuration from appwrite.json
✓ Success Deployed kotlin-example ( 62863924adaff7c88a10 )

You can head over to your Appwrite Dashboard to track the progress of your deployment.

Once the deployment completes, you can execute your function by clicking the Execute Now button.

The first execution results in what we call a Cold Start. Essentially this is the first time a runtime is created, so it takes a bit longer. As you can see, the first execution took about 450ms and subsequent executions were around 4ms. Now that we have an idea of the complete workflow, we can start tinkering with the code and write some cool functions.

🧮 Answering the Most Fundamental Question in Mathematics

As the title suggests we’re going to write a cloud function to answer one of the most fundamental questions in Mathematics.

Is the given number odd or even? I know what you’re thinking… It’s so easy! Why do I need a Cloud Function for it? I could just write

fun main() {
    val x = 12
    println( x%2 == 0 ) // true
    println( (x/2) * 2 == x ) // true
    println( x and 1 == 0 ) // true
    println( ( x shr 1) shl 1  == x ) // true
}

But wait! We’re taking this to the next level. We’re going to decide if our number is even or odd using one of the most sophisticated and well written APIs out there! The isEven API.

Jokes aside, this example aims to illustrate how you can make API calls from your Cloud Function which will enable you to build anything you’d like.

Firstly, open the kotlin-example folder in your favorite IDE. Let’s start with a blank canvas and clean up our src/Index.kt file to

@Throws(Exception::class)
fun main(req: RuntimeRequest, res: RuntimeResponse): RuntimeResponse {
    return res.json(mapOf(
        "message" to "Hello, World!"
    ))
}

In order to deal with JSON objects more easily, we’ll make use of the popular gson library. Include the following dependency in the deps.gradle file.

dependencies {
    implementation 'com.google.code.gson:gson:2.9.0'
}

Next, let’s write some code to read and parse a number sent as an argument to this function.

import com.google.gson.Gson

private val gson = Gson()

@Throws(Exception::class)
fun main(req: RuntimeRequest, res: RuntimeResponse): RuntimeResponse {

    val payload = gson.fromJson<Map<String, Any>>(
        req.payload.ifEmpty { "{}" },
        MutableMap::class.java
    )

    val number = payload["number"] ?: 2

    return res.json(mapOf(
        "message" to "Hello, World!"
    ))
}

We then retrieve the number that was passed to the function and default to the number 2 in case it’s empty. We also import the gson library and create an instance of it.

Next, let’s make the call to the API using the native HTTP client.

import com.google.gson.Gson
import java.io.BufferedReader
import java.io.InputStreamReader
import java.net.HttpURLConnection
import java.net.URL

private val gson = Gson()

@Throws(Exception::class)
fun main(req: RuntimeRequest, res: RuntimeResponse): RuntimeResponse {

    val payload = gson.fromJson<Map<String, Any>>(
        req.payload.ifEmpty { "{}" },
        MutableMap::class.java
    )

    val number = payload["number"] ?: 2

    val url = URL("https://api.isevenapi.xyz/api/iseven/$number")
    val con = (url.openConnection() as HttpURLConnection).apply {
        requestMethod = "GET"
        responseCode
    }

    val responseString = buildString {
        BufferedReader(InputStreamReader(con.inputStream)).useLines { lines ->
            lines.forEach { append(it) }
        }
    }

    con.disconnect()

    val response = gson.fromJson<Map<String, Any>>(
        responseString,
        MutableMap::class.java
    )

    return res.json(response)
}

Awesome! We’re all set to test our function! If you remember the drill, all we need to do is deploy our function.

appwrite deploy function
? Which functions would you like to deploy? kotlin-example (62863924adaff7c88a10)
ℹ Info Deploying function kotlin-example ( 62863924adaff7c88a10 )
ℹ Info Ignoring files using configuration from appwrite.json
✓ Success Deployed kotlin-example ( 62863924adaff7c88a10 )

You can now head over to the Appwrite console and execute the function with the following payload.

Head over to the Logs tab to check the status and response from the function.

Perfect! Looks like we’ve managed to solve one of the most pressing problems in Mathematics after all! Not to mention, the API also comes with a host of quirky Ads! Like this one to purchase old people 👴

📚 Resources

Here are some handy links for more information

Deploying Functions Just Got Easier with Appwrite CLI 2.0!

Christy Jacob — Fri, 11 Mar 2022 14:04:34 +0000

Appwrite 0.13 was just released and one of the biggest highlights this time around is the brand new Appwrite CLI! The CLI underwent a major overhaul including a complete rewrite in Node.js, easier creation and deployment of cloud functions, the ability to manage your Appwrite projects, collections, CI support and a lot more!

In this article we’ll cover how you can get started with the Appwrite CLI and be on your way to deploying cloud functions!

What is Appwrite you may ask?
Appwrite is open source backend-as-a-service that abstracts all the complexity involved in building a modern application by providing you with a set of REST APIs for your core backend needs. Appwrite handles user authentication and authorization, databases, file storage, cloud functions, webhooks and much more! If there is anything missing, you can extend Appwrite using your favorite backend language.

⚙️ Installation

We’ve made sure developers have multiple installation options from an npm package to standalone binaries and even a Homebrew package.

If you have npm installed, it's pretty simple

npm install -g appwrite-cli

Instead if you prefer the standalone binary, you can install the CLI on Linux and MacOS using

curl -sL https://appwrite.io/cli/install.sh | bash

Please note that the binary method of installing the CLI does not work with macOS on ARM.

If you’re on a Windows system, we’ve got something for you as well!

iwr -useb https://appwrite.io/cli/install.ps1 | iex

If Homebrew is your thing, we have you covered too!

brew tap appwrite/sdk-for-cli https://github.com/appwrite/sdk-for-cli
brew update
brew install --HEAD appwrite

With installation now complete, it's time to verify your installation

appwrite -v
0.0.15

This will print the latest version of your CLI.
Getting Started
Before you can start using the CLI, you need to login to your Appwrite account with:

appwrite login
? Enter your email test@test.com
? Enter your password ********
? Enter the endpoint of your Appwrite server http://localhost/v1
✓ Success

You’ll be prompted to enter your email, password and the endpoint of your Appwrite server. If you’re running Appwrite locally, you can use the default value for the endpoint in the prompts.

The CLI is designed to work with multiple Appwrite projects and you can configure the CLI to connect to your project using:

appwrite init project

You can choose to create a new project or connect to an existing one associated with your account. The init project command creates a new appwrite.json file in the current directory with all the information about your current project like the ID, name, collection and function definitions and so on.

You’re now all set to interact with the Appwrite CLI!

⚡️ Deploying Functions

One of the major highlights of the CLI are the new Function starters and easier ways to deploy the cloud functions. You can get started with your first cloud function using:

appwrite init function
? What would you like to name your function? My Awesome Function
? What runtime would you like to use? Node.js (node-17.0)
✓ Success

This command creates a new cloud function on your Appwrite server, and also clones some starter code to help you get going quickly. The starter code is designed to be simple enough to help you get started writing your own functions while being extensive enough to cover most common use cases like dependencies and accessing environment variables. Feel free to examine the code that was just created.

Great! All that’s left now is to deploy your cloud function! Head back to your CLI and use:

appwrite deploy function
? Which functions would you like to deploy? My Awesome Function (6221eff3e289b17042b8)
ℹ Info Deploying function My Awesome Function ( 6221eff3e289b17042b8 )
✓ Success Deployed My Awesome Function ( 6221eff3e289b17042b8 )

Follow the prompts and if everything goes well, your function should now be deployed! You can then head to the Functions section in the Appwrite console and execute your function.

⬆️ Deploying Collections

The CLI also serves a similar utility with your collection definitions. You can pull all your projects’ collection definitions into your appwrite.json file which you can later use to deploy to a different Appwrite project or server.

appwrite init collection
ℹ Info Found 1 collections
ℹ Info Fetching Millenium Problems ...
✓ Success

If you’re migrating to a new server, be sure to create a new Appwrite project and update the values of projectId and projectName in the appwrite.json file. Don’t forget to update your server endpoint using:

appwrite client --endpoint https://endpoint.com/v1

And also login to the CLI using your new server’s credentials using the appwrite login command.

Once the CLI is configured to connect to your new project, you can use the deploy command to create all your collection definitions to the server.

appwrite deploy collection

👩‍💻 Usage

In the following section, we’ll cover the usage instructions of some common tasks.

You can create a new user using:

appwrite users create --userId "unique()" --email hello@appwrite.io --password very_strong_password

To list users in your project, you can use the following command:

appwrite users list

Oops. Looks like we forgot to give our first user a name! You can update user information using:

appwrite users updateName --userId 6222455985f1c3d14b35 --name "Awesome User"

Let’s take a look at our users now.

If you wish to parse the response further, you can print it in a more parser friendly JSON format using the –json flag.

appwrite users list –json

If you plan to use the CLI in a CI environment, you need to authenticate using an API key. This can be done with the appwrite client command. Everything else remains the same.

appwrite client –key <YOUR_API_KEY>

The CLI also ships with a handy –verbose flag that displays a more detailed error message in case you’re trying to debug something.

The CLI is basically a reflection of the Appwrite API, so any methods you expect in the SDKs should be present as commands in the CLI. At any point, if you need to explore a command, you can do so using the help command or its variants.

appwrite users
appwrite users -h
appwrite users –help
appwrite users help

🤩 What's next?

We’ll continue to iterate on community feedback and be back with even better versions of the CLI packed with a lot more features! Eventually, the CLI will become the only tool you’ll need to install, migrate, manage and monitor your Appwrite server.

Meanwhile, we’d love you to check it out and share your valuable feedback and hang out with us on our Discord. If you like what we do at Appwrite, don’t forget to drop us a tiny star on GitHub. It means a lot.

Send Welcome Emails using Appwrite's Swift Cloud Functions

Christy Jacob — Fri, 22 Oct 2021 09:18:55 +0000

For all the Swift developers out there, we have good news! We just announced our Swift SDK to work with server side APIs of Appwrite. You can learn more about our Swift SDK in our Swift SDK announcement post.

In this tutorial however, we are going to write, deploy and run our very own Welcome Email Cloud Function with Swift. Let's get started.

🤔 What are Appwrite Cloud Functions?

Appwrite Cloud Functions are a way for you to extend and customize your Appwrite BaaS functionality by allowing you to execute custom code. Appwrite can execute your function either explicitly or in response to any Appwrite system event like account creation, user login, database updates and much more. You can also schedule your functions to run according to a CRON schedule or trigger them manually by hitting an HTTP endpoint using the Appwrite client or server APIs.

🗒️ Prerequisites

In order to continue with this tutorial, you'll need to have the latest version of Appwrite installed and an Appwrite project setup to test this function. If you have not already installed Appwrite, please do so. Installing Appwrite is really simple. Based on your operating system, run one of the following commands and installation should be complete in less than 2 minutes.

Unix

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:0.11.0

Windows CMD

docker run -it --rm ^
    --volume //var/run/docker.sock:/var/run/docker.sock ^
    --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^
    --entrypoint="install" ^
    appwrite/appwrite:0.11.0

Windows PowerShell

docker run -it --rm ,
    --volume /var/run/docker.sock:/var/run/docker.sock ,
    --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ,
    --entrypoint="install" ,
    appwrite/appwrite:0.11.0

You can also find detailed installation instructions in the official Appwrite installation docs.

Another requirement to follow along is that you have a Mailgun account with a valid Mailgun Domain and API Key. With that aside, we're ready to get started.

🔓️ Activate Swift Functions Runtime

The Swift runtime needs to be enabled for you to be able to use it. This can be done easily using environment variables. The environment variables can be found in the .env file located in the Appwrite installation folder. If it's not present already, you'll need to add the following key-value pair to the .env file.

_APP_FUNCTIONS_RUNTIMES=swift-5.5

Next, restart your stack using docker-compose up -d

🔑 Initialize Your Swift Function

First, create a project folder where you will create all the necessary files for your function. We will call this folder welcome-email. Once inside this folder, you can create a new Swift project with the following command.

docker run --rm -it -v $(pwd):/app -w /app swift:5.5 swift package init WelcomeEmail

This will initialize a new Swift package project. It should create bunch of files, important ones to notice are

.
├── Sources/WelcomeEmail/main.swift
└── Package.swift

➕ Add Appwrite Swift SDK dependency

Open the welcome-email folder in your favorite IDE and add the following code to your Package.swift file.

import PackageDescription

let package = Package(
    name: "WelcomeEmail",
    dependencies: [
        .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.0.0"),
    ],
    targets: [
        .target(
            name: "WelcomeEmail",
            dependencies: [
                .product(name: "AsyncHTTPClient", package: "async-http-client"),
            ])
    ]
)

Here we add the async-http-client SDK for swift under dependencies as well as under the executable's target dependencies.

✍️ Write your Function

Open Sources/WelcomeEmail/main.swift and fill in the following code:

import AsyncHTTPClient
import Foundation

func sendSimpleMessage(name: String, email: String) throws  {
    let message = "Welcome \(name)!"
    let targetURL = "https://api.mailgun.net/v3/\(MAILGUN_DOMAIN)/messages"
    let params =  [
        "from" : "Excited User <hello@appwrite.io>",
        "to" : email,
        "subject" : "hello",
        "text" : message
    ]

    var request: HTTPClient.Request
    do {
        request = try HTTPClient.Request(
            url: targetURL,
            method: .RAW(value: "POST")
        )

        let auth = "api:\(MAILGUN_API_KEY)".data(using: String.Encoding.utf8)!.base64EncodedString()
        request.headers.add(name: "Content-Type", value: "multipart/form-data")
        request.headers.add(name: "Authorization", value: "Basic \(auth)")

        buildMultipart(&request, with: params)

        httpClient.execute(request: request).whenComplete { result in
            switch result {
            case .failure(let error):
                print("Error: \(error)")
            case .success(let response):
                if response.status == .ok {
                    print("Message sent!")
                } else {
                    print("Error: \(response.status)")
                }
            }

            group.leave();
        }

    } catch let error {
        print(error)
        return
    }
}

let MAILGUN_DOMAIN = ProcessInfo.processInfo.environment["MAILGUN_DOMAIN"] ?? "";
let MAILGUN_API_KEY = ProcessInfo.processInfo.environment["MAILGUN_API_KEY"] ?? "";
let APPWRITE_FUNCTION_EVENT_DATA = ProcessInfo.processInfo.environment["APPWRITE_FUNCTION_EVENT_DATA"] ?? "{}"

let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
let group = DispatchGroup()

do {
    let data = Data(APPWRITE_FUNCTION_EVENT_DATA.utf8)

    guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
        throw "Unable to parse APPWRITE_FUNCTION_EVENT_DATA"
    }

    guard let name = json["name"] as? String else {
        throw "Unable to parse name"
    }

    guard let email = json["email"] as? String else {
        throw "Unable to parse email"
    }

    group.enter()
    try sendSimpleMessage(name: name, email: email)
    group.wait()

} catch let error {
    print(error)
}

The environment variables that we are accessing here are either already available or are later set in the Appwrite Function's settings.

Next create a new file under Sources/WelcomeEmail/File.swift that will house one of our helper classes

import NIO

open class File {

    public let name: String
    public var buffer: ByteBuffer

    public init(name: String, buffer: ByteBuffer) {
        self.name = name
        self.buffer = buffer
    }
}

Lastly, we need to create one more file Sources/WelcomeEmail/Utils.swift for some of our utility functions.

import AsyncHTTPClient
import NIO

let DASHDASH = "--"
let CRLF = "\r\n"
let boundaryChars = "abcdefghijklmnopqrstuvwxyz1234567890"

func randomBoundary() -> String {
    var string = ""
    for _ in 0..<16 {
        string.append(boundaryChars.randomElement()!)
    }
    return string
}

func buildMultipart(
    _ request: inout HTTPClient.Request,
    with params: [String: Any?] = [:]
) {
    func addPart(name: String, value: Any) {
        bodyBuffer.writeString(DASHDASH)
        bodyBuffer.writeString(boundary)
        bodyBuffer.writeString(CRLF)
        bodyBuffer.writeString("Content-Disposition: form-data; name=\"\(name)\"")

        if let file = value as? File {
            bodyBuffer.writeString("; filename=\"\(file.name)\"")
            bodyBuffer.writeString(CRLF)
            bodyBuffer.writeString("Content-Length: \(bodyBuffer.readableBytes)")
            bodyBuffer.writeString(CRLF+CRLF)
            bodyBuffer.writeBuffer(&file.buffer)
            bodyBuffer.writeString(CRLF)
            return
        }

        let string = String(describing: value)
        bodyBuffer.writeString(CRLF)
        bodyBuffer.writeString("Content-Length: \(string.count)")
        bodyBuffer.writeString(CRLF+CRLF)
        bodyBuffer.writeString(string)
        bodyBuffer.writeString(CRLF)
    }

    let boundary = randomBoundary()
    var bodyBuffer = ByteBuffer()

    for (key, value) in params {
        switch key {
        case "file":
            addPart(name: key, value: value!)
        default:
            if let list = value as? [Any] {
                for listValue in list {
                    addPart(name: "\(key)[]", value: listValue)
                }
                continue
            }
            addPart(name: key, value: value!)
        }
    }

    bodyBuffer.writeString(DASHDASH)
    bodyBuffer.writeString(boundary)
    bodyBuffer.writeString(DASHDASH)
    bodyBuffer.writeString(CRLF)

    request.headers.remove(name: "content-type")
    request.headers.add(name: "Content-Length", value: bodyBuffer.readableBytes.description)
    request.headers.add(name: "Content-Type", value: "multipart/form-data;boundary=\"\(boundary)\"")
    request.body = .byteBuffer(bodyBuffer)
}

extension String: Error {}

⚙️ Build the Function Binary

In order to deploy our function, we need to first build the project. Our runtime is based on the slim version of official Swift docker image, so we'll use the official Swift docker image to build our project.

From the welcome-email directory, run the following command

$ docker run --rm -it -v $(pwd):/app -w /app swift:5.5 swift build

This should build the project. Ensure that your folder structure looks like this

.
├── .build/x86_64-unknown-linux-gnu/debug/WelcomeEmail
├── Package.swift
├── README.md
└── Sources
    └── WelcomeEmail
        ├── File.swift
        ├── main.swift
        └── Utils.swift

There could be other files and folders as well, but you can ignore those.

☁️ Create a Function in Your Appwrite Console

Login to your Appwrite console and open the project of your choosing. On the sidebar, tap on the Functions menu. In the following screen, tap the Add Function button.

We'll call our Cloud function WelcomeEmail. and select swift-5.5 for the environment. Then tap Create.

🧑‍💻 Deploy Tag

Once your function is created, you'll be taken to the Function Overview screen. Click the Deploy Tag button at the bottom of the function overview page and then switch to the Manual tab.

Let's first create a tarfile that contains our function.

$ tar -zcvf code.tar.gz -C .build/x86_64-unknown-linux-gnu/ debug/WelcomeEmail

Head back to the Deploy a New Tag dialog and upload the code.tar.gz that we just created and use ./WelcomeEmail for the Command.

✅ Activate tag

Once you deploy your tag, it will be listed under Tags on the Overview page. Activate your most recent tag ( if you have multiple versions ).

💡 Adding Triggers and Environment Variables

On the Functions page, switch to the Settings tab. A function can be triggered based on an event or a schedule you choose. This particular function should be triggered by the users.create and the account.create events. Select these events from the events section.

In the Variables section, tap the Add Variable button and add the following variables and click the Update button.

MAILGUN_API_KEY - Your Mailgun API Key.
MAILGUN_DOMAIN - Your Mailgun domain.

✨️ Verify it's working

It's about time to check if all our hard work has finally paid off! Let's create a user and verify that our Cloud Function has sent them a welcome email!

Head to the Users page from the Sidebar and click the Add User button. Give your user a valid name and email ID and click Create. Back in the Functions page, you can now examine the logs of your function execution.

If you're using a sandbox Mailgun account, ensure that the email ID is an Authorized Recipient

📚️ Resources

Hope you enjoyed this article! We love contributions and encourage you to take a look at our open issues and ongoing RFCs.

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans 👩‍💻.

Here are some handy links for more information:

A guide to Maven Repositories

Christy Jacob — Wed, 14 Jul 2021 18:17:13 +0000

We at Appwrite recently published our Android SDK to Maven Central and we learnt a whole lot about the Gradle and Maven ecosystem in the process.

In this series of articles, we'll aim to teach you how you can build and publish your own Android Libraries using Gradle. Before we dive into building and publishing artifacts with Gradle, we need to get familiar with Maven because after all, Gradle is a build tool for Java based projects ( among several others ).

If you've worked on a Java project, it's highly likely that you would've heard of Maven, as it is the most popular build tool for Java projects. Most of us associate Maven with a pom.xml file. However, there's much more to Maven than meets the eye and you can very quickly get lost in a sea of knowledge. This article will aim to walk you through the important concepts in Maven and introduce you to various terminologies in the Maven ecosystem.

🗃️ The POM file

The POM file is the cornerstone of any Maven project. Think of it as an entry point to any Maven project. The POM file has all the information required to build the project; a recipe book of sorts. If you're familiar with the package.json file in node projects, composer.json file in php projects, requirements.txt in python projects and build.gradle in other Java/Kotlin projects, the POM file should seem familiar.

Though we will be using Gradle for building and publishing artifacts, it's a good idea to learn about the structure of the POM file as these concepts can be extended to Gradle as well.

Let's take a sample POM file to understand its structure. You can use the following command to create a simple Maven project if you want to test it out yourself.

mvn -B archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4

Once you have executed this command, you will notice a few things have happened. First, you will notice that a directory named my-app has been created for the new project, and this directory contains a file named pom.xml that should look like this:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>my-app</name>
  <!-- FIXME change it to the project's website -->
  <url>http://www.example.com</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
       ... lots of helpful plugins
    </pluginManagement>
  </build>
</project>

pom.xml contains the Project Object Model (POM) for this project. The POM is the most basic unit of work in Maven. This is important to remember because Maven is inherently project-centric in that everything revolves around the notion of a project. In short, the POM contains every important piece of information about your project and is the go-to place for finding anything related to your project.

This is a very simple POM but still displays the key elements every POM contains, so let's walk through each of them to familiarize you with the POM essentials:

project This is the top-level element in all Maven pom.xml files.
modelVersion This element indicates what version of the object model this POM is using. The version of the model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when the Maven developers deem it necessary to change the model.
groupId This element indicates the unique identifier of the organization or group that created the project. The groupId is one of the key identifiers of a project and is typically based on the fully qualified domain name of your organization. For example org.apache.maven.plugins is the designated groupId for all Maven plugins.
artifactId This element indicates the unique base name of the primary artifact being generated by this project. The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use the artifactId as part of their final name. A typical artifact produced by Maven would have the form -. (for example, myapp-1.0.jar).
version This element indicates the version of the artifact generated by the project. Maven goes a long way to help you with version management and you will often see a SNAPSHOT designator in a version, which indicates that a project is in a state of development. We will discuss the use of snapshots and how they work further on in this guide.
name - This element indicates the display name used for the project. This is often used in Maven's generated documentation.
url This element indicates where the project's site can be found. This is often used in Maven's generated documentation.
properties This element contains value placeholders accessible anywhere within a POM.
dependencies This element's children list the dependencies. The cornerstone of the POM.
build This element handles things like declaring your project's directory structure and managing plugins.

For a complete documentation of all the POM attributes, you can refer to the official docs.

🧩 Artifacts

An artifact is something that is either produced or used by a project. Examples of artifacts produced by Maven for a project include: JARs ( Java Archives ), source and binary distributions, WARs, AARs ( Android Archives ) etc. Each artifact is identified by a group id, an artifact ID, a version, an extension and a classifier.

Take a look at Appwrite's Android SDK. You will find the following artifacts ( and more ).

sdk-for-android-0.0.1-javadoc.jar                  2021-06-29 15:13       261            
sdk-for-android-0.0.1-sources.jar                  2021-06-29 15:13     18663      
sdk-for-android-0.0.1.aar                          2021-06-29 15:13     46437      
sdk-for-android-0.0.1.pom                          2021-06-29 15:13      3277

You will find a lot of .md5, .sha1, .sha256, .sha512 and .asc files which are all used by Maven Central and other consumers for verifying the signature and authenticity of your artifacts.

You will notice that, these artifacts follow a naming convention as mentioned below.

<artifactId>-<version>-<classifier>.<extension>

Note : classifier is an optional field and is absent in the case of Primary Artifacts which in the case of our Android project are the aar and pom files.

In our case the following artifacts are the primary artifacts

sdk-for-android-0.0.1.aar
sdk-for-android-0.0.1.pom

Our aar file can contain Android resources and a Manifest file, which allows you to bundle in shared resources like layouts and drawables in addition to all the Java classes and methods. Our pom file contains information about our library including all the dependencies we use internally.

And the following are the secondary artifacts ( which are supplementary to the primary artifacts and are not necessarily required to build your project. )

sdk-for-android-0.0.1-javadoc.jar
sdk-for-android-0.0.1-sources.jar

When we talk about publishing our project in the next article, we will be referring to all these artifacts.

🗺️ Maven Coordinates

We've talked about the pom file and primary and secondary artifacts. In this section we will dive into the structure of a Maven repository and understand how Maven resolves dependencies when you build your project!

What's a Maven dependency you ask ? A Maven Dependency is any artifact that your project depends on. A typical dependency declaration in a Maven project looks like this

<dependencies>
  <dependency>
    <groupId>io.appwrite</groupId>
    <artifactId>sdk-for-android</artifactId>
    <version>0.0.1</version>
  </dependency>
</dependencies>

Together, the groupID, artifactID, and version make up the Maven Coordinates. Every Maven artifact is identified by these coordinates.

The next question arises. Given the Maven coordinates, how does maven locate an artifact? Maven uses the coordinates values for a given dependency to construct a URL according to the maven repository layout.

Let's take the example of Appwrite's Android SDK with the following coordinates

<dependency>
  <groupId>io.appwrite</groupId>
  <artifactId>sdk-for-android</artifactId>
  <version>0.0.1</version>
</dependency>

According to the official specification, the URL for primary artifacts looks like:

/$groupId[0]/../${groupId[n]/$artifactId/$version/$artifactId-$version.$extension

The groupId array in the URL is formed from the <groupId> element in the pom file as follows

$groupId is a array of strings made by splitting the groupId’s on “.” into directories.

So for the groupId value of org.example.subdomain, our $groupId array would be [org, example, subdomain], which when translated into directories, becomes org/example/subdomain.

In our case, the groupId io.appwrite is translated to the following path io/appwrite/.

Our next step is to build the URL for the primary and secondary artifacts.

🔧 Primary Artifacts

One of the core features of Maven is its ability to handle Transitive Dependencies. That is, to find and download the dependencies of your dependencies, and their dependencies and so on until all of dependencies are satisfied.

Just how your own Maven project has a pom.xml file listing its main dependencies, those dependencies also have a remote pom file serving a similar purpose. Maven uses this file to figure out what other dependencies to download. When a coordinate does not contain a <classifier>, it is considered a primary artifact and is expected to have a pom available.

In our case, the primary artifacts are the .pom file and the .aar file.

pom - If we follow the URL convention above, the pom file for Appwrite's Android SDK can be located at

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.pom

aar - If we follow the URL convention above, the aar file for Appwrite's Android SDK can be located at

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar

⛏️ Secondary Artifacts

Secondary artifacts, or “attached artifacts” on the other hand are dependencies that you want Maven to download that are ancillary to your project. Most often they are used to download the javadocs and/or sources for a particular dependency. However, unlike a primary artifact, a secondary artifact is not expected to have a remote pom and thus never has any dependencies.

They can be specified in the <dependencies> section just like primary artifacts:

<dependency>
  <groupId>io.appwrite</groupId>
  <artifactId>sdk-for-android</artifactId>
  <version>0.0.1</version>
  <classifier>sources</classifier>
</dependency>

The URL for secondary artifacts is similar to that of the primary artifacts except that they have an optional $classifier variable.

/$groupId[0]/../$groupId[n]/$artifactId/$version/$artifactId-$version-$classifier.$extension

In our case, the secondary artifacts are the javadocs and the sources.

javadoc - If we follow the URL convention above, the javadoc file for Appwrite's Android SDK can be located at

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1-javadoc.jar

sources - If we follow the URL convention above, the sources file for Appwrite's Android SDK can be located at

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1-sources.jar

🏁 Checksums

To verify the downloaded artifacts Maven computes the md5, sha1, sha256 and sha512 checksum for that artifact and compares it to the values found in the checksum files located at $ARTIFACT_URL.md5, or $ARTIFACT_URL.sha1, respectively.

This is strictly meant as a way to quickly verify downloads, and it is NOT meant to be used for authentication or security purposes. This is also NOT a substitute for using HTTPS, as checksums can be trivially intercepted and modified along with the modified artifacts.

sha1 - the sha1 checksum for our aar artifacts for example, would be present at

  io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar.sha1

md5 - the md5 checksum for our aar artifacts for example, would be present at

  io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar.md5

Similarly for all other artifacts (javadoc.jar.md5, pom.md5, sources.jar.md5 and so on).

🔐 Signatures

The Maven Central repository makes in mandatory to include a signature for all the uploaded artifacts and checksums. This ensures absolute confidence in the authenticity of the downloaded artifacts. Every artifact and checksum has a corresponding .asc file that contains the signature of the author of the artifact.

$artifacts.asc

For our .aar file for example, the corresponding .asc file would be located at
```
io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar.asc
```
$checksum.asc

For our .md5 ( sha1, sha256 etc.) files, the corresponding .asc file would be located at
```
io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar.md5.asc
```

📦 The Maven Repository

A Repository is Maven holds artifacts and dependencies of all kinds. There are exactly two kinds of repositories

Local
The local repository is a directory on the computer where Maven runs. It caches remote downloads and contains temporary build artifacts that you have not yet released. This is usually located in $HOME/.m2/repository
Remote
Remote repositories refer to any other type of repository, accessed by a variety of protocols such as file:// and https://. These repositories might be a truly remote repository set up by a third party to provide their artifacts for downloading (for example, repo.maven.apache.org). Other remote repositories may be internal repositories set up on a file or HTTP server within your company, used to share private artifacts between development teams and for releases.

Local and remote repositories are structured the same way so that scripts can run on either side, or they can be synced for offline use. The layout of the repositories is completely transparent to the Maven user, however.

The last topic that we'll discuss is the concept of a Release repository and a SNAPSHOT repository.

🏆 Release repository

A release repository is where all the published artifacts are stored in Maven. Because caching plays a really important role in maven repositories, it is highly recommended to make the Release repositories immutable. i.e. artifacts once uploaded cannot be modified. Let's say you published 0.0.1 of your library, you must not modify the existing version, instead publish the next version let's say 0.0.2. This is enforced by default in Maven Central.

There is also the concept of a Staging repository in Maven which serves as a staging area for you to verify all your artifacts before promoting it to the release repository.

🧪 SNAPSHOT repository

A SNAPSHOT variant of a library refers to the latest code along a development branch, and provides no guarantee the code is stable or unchanging and these variants are published to the SNAPSHOT repository. Conversely, the code in a Release variant (any version value without the suffix SNAPSHOT) is unchanging.

In other words, a SNAPSHOT version is the development version before the final Release version. The SNAPSHOT is older than its release.

During the release process, a version of x.y.z-SNAPSHOT changes to x.y.z. The release process also increments the development version to x.y.(z+1)-SNAPSHOT. For example, version 1.0.0-SNAPSHOT is released as version 1.0.0, and the new development version is version 1.0.1-SNAPSHOT.

We already discussed that a Release repository is immutable. So the idea behind a SNAPSHOT repository is to allow mutability and easy development. You can continuously push your latest changes to 1.0.0-SNAPSHOT and anyone depending on it will get the latest changes every time they build their project. Then, after a few iterations, and everyone is happy the latest state of 1.0.0-SNAPSHOT, it can be permanently released as 1.0.0, and rapid development can continue on 1.0.1-SNAPSHOT.

Sonatype's Open Source Software Repository Hosting (OSSRH) service allows open source projects and individuals to create a Maven Central repository and publish artifacts for free! In the next article, we'll go through all the steps involved in publishing an Android library to Maven Central. So stay tuned 😉

✨️ Credits

Hope you enjoyed this article! We love contributions and encourage you to take a look at our open isuses and ongoing RFCs.

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans 👩‍💻.

Here are some handy links for more information:

Clean up your storage using Appwrite Cloud functions!

Christy Jacob — Wed, 14 Jul 2021 05:36:42 +0000

Appwrite 0.9 adds support for both Java and Kotlin runtimes in Cloud Functions, growing the list of supported runtimes to over 15(!)

This example will walk you through the process of creating and uploading a Kotlin cloud function. In particular, we'll teach you how to use cloud functions to periodically clean up your storage and delete unnecessary files! This example also highlights how Appwrite can integrate seamlessly with 3rd party APIs and coexist with your existing stack. Without further ado, let's dive right in!

📝 Prerequisites

At this stage, we assume that you already have an Appwrite instance up and running. If you do not have Appwrite setup yet, you can follow the super easy installation step over at appwrite.io. It's not a typo. There really is only 1 step!

You also need to create an API Key from the Appwrite dashboard with the following scopes granted

files.read
files.write

📽️ Create your project

Create a new Kotlin project using IntelliJ ( or Eclipse ) and choose Maven as your build system. Set the artifact ID accordingly and click proceed.

Once the project is created, we'll add our dependencies. For this example, we will be using two dependencies.

Appwrite Kotlin SDK (io.appwrite:sdk-for-kotlin:0.0.0-SNAPSHOT)
Google's GSON Library (com.google.code.gson:gson:2.8.7)

Add the following lines to the <dependencies> section of your pom.xml file.



<dependencies>
    <dependency>
        <groupId>io.appwrite</groupId>
        <artifactId>sdk-for-kotlin</artifactId>
        <version>0.0.0-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.8.7</version>
    </dependency>
</dependencies>

Load the Maven changes from the UI or using the shortcut Ctrl + Shift + O

👩‍💻 Write some code

Now that the dependencies are fetched, it's time to write some code.

Create a new Kotlin file under src/main/kotlin and name it StorageCleaner.kt.

Next, create a main function and initialize the Appwrite Client and Storage APIs. We'll be using environment variables to store our secrets and other configurable values. We will also store the file expiry date as an environment variable so that the cloud function can be configured without a redeployment.



import io.appwrite.Client
import io.appwrite.services.Storage
import kotlin.system.exitProcess

fun main(args: Array<String>) {
    val client = Client()
        .setEndpoint(System.getenv("APPWRITE_ENDPOINT"))
        .setProject(System.getenv("APPWRITE_FUNCTION_PROJECT_ID"))
        .setKey(System.getenv("APPWRITE_API_KEY"))
    val storage = Storage(client)

    val daysToExpire = System.getenv("DAYS_TO_EXPIRE").toFloatOrNull()
    if (daysToExpire == null) {
        println("Unable to parse DAYS_TO_EXPIRE.")
        exitProcess(1)
    }
}

Before the next step, we need to create a few model classes to parse our JSON response. Create a new Kotlin file Models.kt under src/main/kotlin and add the following code.



data class Permissions(val read: List<String>, val write: List<String>)

data class File(
    val `$id`: String,
    val name: String,
    val `$permissions`: Permissions,
    val dateCreated: Int,
    val signature: String,
    val mimeType: String,
    val sizeOriginal: Int
)

data class FileList(val sum: Int, val files: List<File>?)

Next, let's fetch the last 100 files that were uploaded to storage. Add the following lines to StorageCleaner.kt.



+import com.google.gson.Gson
import io.appwrite.Client
import io.appwrite.services.Storage
import kotlin.system.exitProcess

+suspend fun main(args: Array<String>) {
    val client = Client()
        .setEndpoint(System.getenv("APPWRITE_ENDPOINT"))
        .setProject(System.getenv("APPWRITE_FUNCTION_PROJECT_ID"))
        .setKey(System.getenv("APPWRITE_API_KEY"))
    val storage = Storage(client)

    val daysToExpire = System.getenv("DAYS_TO_EXPIRE").toFloatOrNull()
    if (daysToExpire == null) {
        println("Unable to parse DAYS_TO_EXPIRE.")
        exitProcess(1)
    }

+   val fileList = storage.listFiles("",100, 0, "DESC").body?.string() ?: ""
+   val files: FileList = Gson().fromJson(fileList, FileList::class.java)
}

Now, let's write the logic to delete files older than daysToExpire.



import com.google.gson.Gson
import io.appwrite.Client
import io.appwrite.services.Storage
+ import java.util.*
import kotlin.system.exitProcess

suspend fun main(args: Array<String>) {
    val client = Client()
        .setEndpoint(System.getenv("APPWRITE_ENDPOINT"))
        .setProject(System.getenv("APPWRITE_FUNCTION_PROJECT_ID"))
        .setKey(System.getenv("APPWRITE_API_KEY"))
    val storage = Storage(client)

    val daysToExpire = System.getenv("DAYS_TO_EXPIRE").toFloatOrNull()
    if (daysToExpire == null) {
        println("Unable to parse DAYS_TO_EXPIRE.")
        exitProcess(1)
    }

    val fileList = storage.listFiles("",100, 0, "DESC").body?.string() ?: ""
    val files: FileList = Gson().fromJson(fileList, FileList::class.java)

+   var deletedFiles =  0
+   for( file in files.files!!) {
+       val diff: Long = Date().time/1000 - file.dateCreated
+       if (diff > daysToExpire * 24 * 60 * 60) {
+           storage.deleteFile(file.`$id`)
+           println("Deleted ${file.`$id`}")
+           deletedFiles++
+       }
+   }
+   println("Total files deleted: $deletedFiles")
}

Now that we've written all the required code, we need to package our function as a .jar. Fortunately, this can be done really easily using IntelliJ, so let's see how.

⚙️ Configure artifacts.

In this step, we will create the .jar artifacts required to deploy our cloud function.

In the following dialog, enter the name of your main class. In our case it is StorageCleanerKt. Don't worry if it doesn't show up in the list. Just click OK.

Note: If you don't see the main class, try to follow the steps in this answer https://stackoverflow.com/questions/10654120/error-could-not-find-or-load-main-class-in-intellij-ide

In the next dialog, click Apply and then OK.

Confirm that a new file was created at src/main/kotlin/META-INF/MANIFEST.MF with the following contents.



Manifest-Version: 1.0
Main-Class: StorageCleanerKt

Now build your artifacts using Build > Build Artifacts > Select your artifact from the list > Build. You will find the output of this step in out/artifacts/mainModule_jar/mainModule.jar

🧪 Test locally

Great! Let's test if your function is working fine and doesn't have any compilation issues. Run the following command from the root directory of your Kotlin project. Make sure you replace the values of the required environment variables with those of your own setup.

APPWRITE_ENDPOINT
APPWRITE_FUNCTION_PROJECT_ID
APPWRITE_API_KEY
DAYS_TO_EXPIRE



docker run --rm --volume $(pwd):/usr/local/src:rw \
    --env APPWRITE_ENDPOINT="http://192.168.1.35/v1"  \
    --env APPWRITE_FUNCTION_PROJECT_ID="60d31170f368f" \
    --env DAYS_TO_EXPIRE="0.00001" \
    --env APPWRITE_API_KEY="7e....879f" \
    appwrite/runtime-for-java:11 \
    java -jar out/artifacts/mainModule_jar/mainModule.jar

The APPWRITE_ENDPOINT is NOT localhost in this case since localhost is not accessible from the cloud functions runtime. You will need to set this to a publicly accessible IP of your Appwrite Server. You can find this by running hostname -I in UNIX systems.

If everything goes well, you should see the following output



Total files deleted: 0

🌩️ Create your cloud function

Head over to the Appwrite Dashboard and navigate to the Functions Tab on the sidebar and click on Add Function . Give your function a Name, select an appropriate Java runtime and click Create.

Next, head over to the Settings tab in your cloud function and add the required environment variables and a suitable CRON schedule. In our case, we want to run it every hour (0 * * * *).

Don't forget to click Update to save your settings.

↗️ Deploying & Execute

We're now ready to deploy our function. This step can be done either with the Appwrite CLI or manually.

👀 Deploying Manually

Head over to the root directory of your Kotlin project and run the following commands to create a tarfile.



$ cd out/artifacts

$ tar -zcvf code.tar.gz mainModule_jar                                                  

mainModule_jar/
mainModule_jar/mainModule.jar

$ ls
code.tar.gz  mainModule_jar

This will create a new archive called code.tar.gz.

With this created, head over to your Appwrite Dashboard > Functions > Overview > Deploy Tag. In the dialog that pops up, upload the tarfile we just created and java -jar mainModule.jar for the entry point command.

Once your function is successfully uploaded you need to activate your tag by clicking the Activate Button You can now go ahead and click Execute and leave the data field empty.

If everything goes well, you should be able to see the execution logs under the Logs tab.

⌨️ Deploying with the CLI

If using the Appwrite CLI, run the following commands from the root directory of your Kotlin project. Be sure to replace the IDs with your own values.



$ cd out/artifacts/

$ appwrite functions createTag --functionId=60d41cdbec776 --command="java -jar mainModule.jar" --code=mainModule_jar

$id : 60d46ee4506d4
functionId : 60d41cdbec776
dateCreated : 1624534756
command : java -jar mainModule.jar
size : 4381381

$ appwrite functions updateTag --functionId=60d41cdbec776 --tag=60d46ee4506d4

$id : 60d41cdbec776
$permissions : 
name : Storage Test
dateCreated : 1624513755
dateUpdated : 1624534608
status : disabled
runtime : java-11
tag : 60d46ee4506d4
vars : 
events : {}
schedule : 0 * * * *
scheduleNext : 
schedulePrevious : 1624532406
timeout : 15

Your Cloud Function is now active and will be triggered every 30 minutes based on our CRON schedule.

Great! You've successfully deployed and executed your first Koltin Cloud Function! This is just the tip of the iceberg and the possibilities with Cloud Functions are endless! Stay tuned for more Cloud Function ideas from the Appwrite Team. If you'd like to learn more about Appwrite or how Appwrite works under the hood, we've just curated all the resources for you during 30 Days of Appwrite.

✨️ Credits

Hope you enjoyed this article! You can find the complete code for this tutorial over at the Cloud Functions Demo repository where we have a lot more examples for various runtimes. We love contributions and encourage you to take a look at our open isuses and ongoing RFCs.

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans.

Here are some handy links for more information:

Send Welcome Emails using Appwrite's Java Cloud Functions!

Christy Jacob — Mon, 12 Jul 2021 09:48:25 +0000

Appwrite 0.9 adds support for both Java and Kotlin runtimes in Cloud Functions, growing the list of supported runtimes to over 15(!)

This tutorial will walk you through the process of creating and uploading a Java Cloud Function. In particular, we'll teach you how to use Cloud Functions to send customized welcome emails to your users when they sign up! This example also highlights how Appwrite can integrate seamlessly with 3rd party APIs and coexist with your existing stack. Without further ado, let's dive right in!

📝 Prerequisites

You also need to setup an Mailgun or SendGrid account to be able to send emails.

📽️ Create your project

Create a new Maven project using IntelliJ ( or any other IDE you're comfortable with ). Set the name and artifact ID accordingly and click Finish.

Once the project is created, we'll add our dependencies. For this example, we will need just one dependency to make our HTTP requests.

Unirest Java (com.mashape.unirest:unirest-java:1.4.9)

Add the following lines to the <dependencies> section of your pom.xml file.

<dependencies>
    <dependency>
        <groupId>com.mashape.unirest</groupId>
        <artifactId>unirest-java</artifactId>
        <version>1.4.9</version>
    </dependency>
</dependencies>

Update your Maven dependencies from the UI or using the shortcut Ctrl + Shift + O

👩‍💻 Write some code

Now that the dependencies are fetched, it's time to write some code.

Create a new Java class under src/main/java and name it WelcomeEmail.java.

Next, create a main function that fetches all the environment variables and parses the JSON string stored in the environment variable APPWRITE_FUNCTION_EVENT_DATA.

APPWRITE_FUNCTION_EVENT_DATA is a special environment variable that is automatically passed to your Cloud Function when it is triggered by an event. In our case, the Cloud Function is triggered by a users.create and account.create event, so the payload in APPWRITE_FUNCTION_EVENT_DATA contains a User Object.

We are interested in the name and email ID of the user so we can send a personalised email. We will extract those values here.

import com.mashape.unirest.http.exceptions.UnirestException;
import org.json.JSONObject;

public class WelcomeEmail {

    private static String YOUR_DOMAIN_NAME;
    private static String API_KEY;

    public static void main(String[] args) throws UnirestException {
        YOUR_DOMAIN_NAME = System.getenv("MAILGUN_DOMAIN");
        API_KEY = System.getenv("MAILGUN_API_KEY");
        String payload = System.getenv("APPWRITE_FUNCTION_EVENT_DATA");

        if (payload != null && !payload.isEmpty()) {
            try {
                // Parse the JSON string into a JSON Object
                JSONObject json = new JSONObject(payload);
                String name = json.getString("name");
                String email = json.getString("email");

            } catch (Exception e) {
                System.out.print("[ERROR] There was an error");
                System.out.println(e.getMessage());
            }
        } else {
            System.out.println("[INFO] APPWRITE_FUNCTION_EVENT_DATA is empty");
        }
    }
}

Don't worry about the other environment variables yet, we will set them up in the Dashboard in the coming sections.

Next, let's create a simple function that sends a POST request to the Mailgun API and sends out our email.

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

public static String sendSimpleMessage(String name, String email) throws UnirestException {

    String message = String.format("Hi %s!", name);

    HttpResponse<String> request = Unirest.post("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/messages")
            .basicAuth("api", API_KEY)
            .field("from", "Your Awesome App <hello@yourawesomeapp.com>")
            .field("to", email)
            .field("subject", "Welcome Onboard")
            .field("text", message)
            .asString();

    return request.getBody();
}

Finally, call this function from our main function.

public static void main(String[] args) throws UnirestException {
        YOUR_DOMAIN_NAME = System.getenv("MAILGUN_DOMAIN");
        API_KEY = System.getenv("MAILGUN_API_KEY");
        String payload = System.getenv("APPWRITE_FUNCTION_EVENT_DATA");

        if (payload != null && !payload.isEmpty()) {
            try {
                JSONObject json = new JSONObject(payload);
                String name = json.getString("name");
                String email = json.getString("email");
+               String response = sendSimpleMessage(name, email);
+               System.out.println(response);
            } catch (Exception e) {
                System.out.print("[ERROR] There was an error");
                System.out.println(e.getMessage());
            }

        } else {
            System.out.println("[INFO] APPWRITE_FUNCTION_EVENT_DATA is empty");
        }

    }

Now that we've written all the required code, we need to package our function as a .jar. Fortunately, this can be done really easily using IntelliJ so let's see how.

⚙️ Configure artifacts.

In this step, we will create the .jar artifacts required to deploy our Cloud Function. Select File > Project Structure > Artifacts as seen in the screenshot.

In the following dialog, select your main class ( WelcomeEmail ) as shown in the image.

Note: If you don't see the main class, try to follow the steps in this answer https://stackoverflow.com/questions/10654120/error-could-not-find-or-load-main-class-in-intellij-ide

In the next dialog, click Apply and then OK.

Confirm that a new file was created at src/main/java/META-INF/MANIFEST.MF with the following contents.

Manifest-Version: 1.0
Main-Class: WelcomeEmail

Now build your artifacts using Build > Build Artifacts > Select your artifact from the list > Build. You will find the output of this step in out/artifacts/welcome_email_jar/welcome-email.jar

🧪 Test locally

Great! Let's test if your function is working fine and doesn't have any compilation issues. Run the following command from the root directory of your Java project. Make sure you replace the values of the required environment variables with those of your own setup.

MAILGUN_API_KEY
MAILGUN_DOMAIN
APPWRITE_FUNCTION_EVENT_DATA

Your MAILGUN_DOMAIN should look something like sandboxee5d....b85.mailgun.org. Also ensure that the email address is an authorized recipient.

docker run --rm --volume $(pwd):/usr/local/src:rw \                                   
    --env MAILGUN_API_KEY="YOUR_API_KEY" \
    --env MAILGUN_DOMAIN="sandboxee5d...b85.mailgun.org" \
    --env APPWRITE_FUNCTION_EVENT_DATA="{ \"name\" : \"Example\", \"email\": \"example@example.com\"}" \
    appwrite/runtime-for-java:11 \
    java -jar out/artifacts/welcome_email_jar/welcome-email.jar

If everything goes well, you should see the following output

{
  "id": "<20210625073914.1.D719405DDA651887@sandboxee5d...b85.mailgun.org>",
  "message": "Queued. Thank you."
}

🌩️ Create your Cloud Function

Next, head over to the Settings tab in your Cloud Function and add the required environment variables and select the events that should trigger this function. In our case this would be account.create and users.create.

Don't forget to click Update to save your settings.

↗️ Deploying & Execute

We're now ready to deploy our function. This step can be done either with the Appwrite CLI or manually.

👀 Deploying Manually

Head over to the root directory of your Java project and run the following commands to create a tarfile.

$ cd out/artifacts

$  tar -zcvf code.tar.gz welcome_email_jar 

welcome_email_jar/
welcome_email_jar/welcome-email.jar

$  ls
code.tar.gz  welcome_email_jar

This will create a new archive called code.tar.gz.

With this created, head over to your Appwrite Dashboard > Functions > Overview > Deploy Tag. In the dialog that pops up, upload the tarfile we just created and use java -jar welcome-email.jar for the entry point command.

Once your function is successfully uploaded you need to activate your tag by clicking the Activate Button.

Great, in order to trigger our function, we need to create a user. Head over to the Users section on the sidebar and create a new user using an email ID that is present in the list of authorized recipients. If everything goes well, you should be able to see the execution logs under the Logs tab.

⌨️ Deploying with the CLI

If using the Appwrite CLI, run the following commands from the root directory of your Java project. Be sure to replace the IDs with your own values. You can get your function ID from your Appwrite Dashboard.

$ cd out/artifacts/

$ appwrite functions createTag --functionId=60d5839682e94 --command="java -jar welcome-email.jar" --code=welcome_email_jar

$id : 60d58cacb0748
functionId : 60d5839682e94
dateCreated : 1624607916
command : java -jar welcome-email.jar
size : 1808608

$  appwrite functions updateTag --functionId=60d5839682e94 --tag=60d58cacb0748

$id : 60d5839682e94
$permissions : 
name : Welcome Email Test
dateCreated : 1624605590
dateUpdated : 1624606138
status : disabled
runtime : java-11
tag : 60d58cacb0748
vars : 
events : 
schedule : 
scheduleNext : 
schedulePrevious : 0
timeout : 15

Your Cloud Function is now active and will be triggered whenever a new user is created.

Great! You've successfully deployed and executed your first Java Cloud Function! This is just the tip of the iceberg, and the possibilities with Cloud Functions are endless! Stay tuned for more Cloud Function ideas from the Appwrite Team.

If you'd like to learn more about Appwrite or how Appwrite works under the hood, we've just curated all the resources for you during 30 Days of Appwrite.

✨️ Credits

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans.

Here are some handy links for more information:

Getting started with Appwrite's Android SDK

Christy Jacob — Fri, 09 Jul 2021 07:51:07 +0000

One of the major highlights of Appwrite 0.9 is the official support for Android. We've also released a brand new Android SDK to go alongside it 😉!

In this tutorial, we'll learn to setup Appwrite's Android SDK, interact with Appwrite's Accounts API and also learn to setup OAuth Logins in your App! We'll extensively use JetPack components like Fragments, ViewModels, Data Binding, LiveData and Kotlin Coroutines! I hope you're as excited as I am! Let's get started!

📝 Prerequisites

You should have also setup an OAuth provider with Appwrite to be able to follow the OAuth section of this tutorial. You can learn to setup OAuth providers in Appwrite by going through our tutorial.

🛠️ Create a new Android Project

Setup your Android project and choose the Empty Activity Template. Give your project a name, Choose Android 6.0 ( Marshmallow ) as your minimum SDK and click Finish.

Now is also a good time to add our Android App as a platform in the Appwrite Console. Head over to your AndroidManifest.xml and locate the package name of your app. It should look something like com.example.myapplication.

In your Appwrite dashboard, click on Add Platform and select a New Android App. Give your app a name, add the package name and click Register.

Once this is complete, it's time to head back to our Android project add our dependencies.

👷 Setup Appwrite's Android SDK

Appwrite's Android SDK is hosted on Maven Central, so you'll first need to add the mavenCentral() repository to your project's build.gradle file ( if it's not already present ).

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

Then add the Appwrite Android SDK to your app's build.gradle file.

dependencies {
    // ... Other dependencies
    implementation 'io.appwrite:sdk-for-android:0.0.1'
}

We'll also be using Data Binding and we need to enable that in our app's build.gradle file

android {
    // ...
    buildFeatures {
        dataBinding true
    }
}

Sync your gradle dependencies and if there are no errors, we're ready to proceed!

⌨️ Create helper classes

The first step is to initialise the Client() class from the Appwrite SDK. For this, we will create a new file utils/Client.kt where we will create a Singleton object to use across our App.

package com.example.myapplication.utils

import android.content.Context
import io.appwrite.Client

object Client {
    lateinit var client : Client

    fun create(context: Context) {
        client = Client(context)
             // Replace with your own endpoint and project ID
            .setEndpoint("https://demo.appwrite.io/v1")
            .setProject("6070749e6acd4")
    }
}

If your Appwrite setup is running on localhost, you will need to make sure localhost is accessible from your emulator by using a proxy. Else, you can replace localhost with your private IP address which you can find using the command hostname -I on UNIX systems.

If you're using Appwrite on localhost, you need to set the setSelfSigned(true) flag to true.

client = Client(context)
            .setEndpoint("https://192.168.1.35/v1")
            .setProject("6070749e6acd4")
            .setSelfSigned(true)

Next, we're going to create another utility class called utils/Event.kt. This utility class will allow us to handle LiveData Events ( Changes that need to be observed only once ).

package com.example.myapplication.utils

/**
 * Used as a wrapper for data that is exposed via a LiveData that represents an event.
 */
open class Event<out T>(private val content: T) {

    var hasBeenHandled = false
        private set // Allow external read but not write

    /**
     * Returns the content and prevents its use again.
     */
    fun getContentIfNotHandled(): T? {
        return if (hasBeenHandled) {
            null
        } else {
            hasBeenHandled = true
            content
        }
    }

    /**
     * Returns the content, even if it's already been handled.
     */
    fun peekContent(): T = content
}

🏗️ Create the layouts

Now, we're going to update the layout in activity_main.xml to allow us to host fragments. Replace the contents of activity_main.xml with this snippet.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/fragment_container_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Now, create layout file for our Fragment at layout/fragment_account.xml

<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools">

    <ScrollView
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <androidx.constraintlayout.widget.ConstraintLayout
            android:id="@+id/constraint_layout"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:padding="16dp">

            <EditText
                android:id="@+id/responseTV"
                android:layout_width="match_parent"
                android:layout_height="200dp"
                android:background="@null"
                android:enabled="true"
                android:fadeScrollbars="false"
                android:focusable="true"
                android:longClickable="true"
                android:scrollbars="vertical"
                android:textIsSelectable="true"
                app:layout_constraintEnd_toEndOf="parent"
                app:layout_constraintStart_toStartOf="parent"
                app:layout_constraintTop_toTopOf="parent" />

            <EditText
                android:id="@+id/email"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:layout_marginTop="16dp"
                android:hint="Email"
                android:inputType="textEmailAddress"
                android:text="test@test.com"
                app:layout_constraintStart_toStartOf="@id/responseTV"
                app:layout_constraintTop_toBottomOf="@id/responseTV" />


            <EditText
                android:id="@+id/password"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:layout_marginTop="16dp"
                android:hint="password"
                android:inputType="textPassword"
                android:text="testtest"
                app:layout_constraintStart_toStartOf="@id/email"
                app:layout_constraintTop_toBottomOf="@id/email" />

            <EditText
                android:id="@+id/name"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:layout_marginTop="16dp"
                android:hint="name"
                android:inputType="text"
                app:layout_constraintStart_toStartOf="@id/password"
                app:layout_constraintTop_toBottomOf="@id/password" />

            <Button
                android:id="@+id/login"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:layout_marginTop="8dp"
                android:text="Login"
                app:layout_constraintEnd_toStartOf="@+id/signup"
                app:layout_constraintHorizontal_bias="0.5"
                app:layout_constraintHorizontal_chainStyle="spread"
                app:layout_constraintStart_toStartOf="parent"
                app:layout_constraintTop_toBottomOf="@+id/name" />

            <Button
                android:id="@+id/signup"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:layout_marginTop="8dp"
                android:text="Signup"
                app:layout_constraintEnd_toStartOf="@id/getUser"
                app:layout_constraintHorizontal_bias="0.5"
                app:layout_constraintStart_toEndOf="@+id/login"
                app:layout_constraintTop_toBottomOf="@+id/name" />

            <Button
                android:id="@+id/getUser"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:layout_marginTop="8dp"
                android:text="Get User"
                app:layout_constraintEnd_toEndOf="parent"
                app:layout_constraintHorizontal_bias="0.5"
                app:layout_constraintStart_toEndOf="@+id/signup"
                app:layout_constraintTop_toBottomOf="@+id/name" />

            <Button
                android:id="@+id/oAuth"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:layout_marginTop="8dp"
                android:text="Login with Facebook"
                app:layout_constraintEnd_toEndOf="parent"
                app:layout_constraintEnd_toStartOf="@+id/logout"
                app:layout_constraintHorizontal_bias="0.5"
                app:layout_constraintHorizontal_chainStyle="spread"
                app:layout_constraintStart_toStartOf="parent"
                app:layout_constraintTop_toBottomOf="@id/signup" />

            <Button
                android:id="@+id/logout"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:text="Logout"
                app:layout_constraintEnd_toEndOf="parent"
                app:layout_constraintHorizontal_bias="0.5"
                app:layout_constraintStart_toEndOf="@+id/oAuth"
                app:layout_constraintTop_toTopOf="@id/oAuth" />

        </androidx.constraintlayout.widget.ConstraintLayout>
    </ScrollView>

</layout>

🔨 Create the ViewModel

Let's now create a ViewModel at ui/accounts/AccountsViewModel.kt to manage our app state.

package com.example.myapplication.ui.accounts

import android.text.Editable
import androidx.activity.ComponentActivity
import androidx.lifecycle.*
import com.example.myapplication.utils.Client.client
import com.example.myapplication.utils.Event
import io.appwrite.exceptions.AppwriteException
import io.appwrite.services.Account
import kotlinx.coroutines.launch
import org.json.JSONObject


class AccountsViewModel : ViewModel() {

    private val _error = MutableLiveData<Event<Exception>>().apply {
        value = null
    }
    val error: LiveData<Event<Exception>> = _error

    private val _response = MutableLiveData<Event<String>>().apply {
        value = null
    }
    val response: LiveData<Event<String>> = _response

    private val accountService by lazy {
        Account(client)
    }

    fun onLogin(email: Editable , password : Editable) {
        viewModelScope.launch {
            try {
                var response = accountService.createSession(email.toString(), password.toString())
                var json = response.body?.string() ?: ""
                json = JSONObject(json).toString(8)
                _response.postValue(Event(json))
            } catch (e: AppwriteException) {
                _error.postValue(Event(e))
            }
        }

    }

    fun onSignup(email: Editable , password : Editable, name: Editable) {
        viewModelScope.launch {
            try {
                var response = accountService.create(email.toString(), password.toString(), name.toString())
                var json = response.body?.string() ?: ""
                json = JSONObject(json).toString(2)
                _response.postValue(Event(json))
            } catch (e: AppwriteException) {
                _error.postValue(Event(e))
            }
        }

    }

    fun onGetUser() {
        viewModelScope.launch {
            try {
                var response = accountService.get()
                var json = response.body?.string() ?: ""
                json = JSONObject(json).toString(2)
                _response.postValue(Event(json))
            } catch (e: AppwriteException) {
                _error.postValue(Event(e))
            }
        }
    }

    fun onLogout() {
        viewModelScope.launch {
            try {
                var response = accountService.deleteSession("current")
                var json = response.body?.string()?.ifEmpty { "{}" }
                json = JSONObject(json).toString(4)
                _response.postValue(Event(json))
            } catch (e: AppwriteException) {
                _error.postValue(Event(e))
            }
        }
    }

}

Our ViewModel has 2 LiveData Objects: One to keep track of errors and one to keep track of the response.

We also have 4 functions

onLogin - onClick handler for the Login Button
onSignup - onClick handler for the Signup Button
onLogout - onClick handler for the Logout Button
onGetUser - onClick handler for the Get User Button

📝 Create the Fragment

Awesome! Let's move on to create our Fragment at ui/accounts/AccountsFragment.kt

package com.example.myapplication.ui.accounts

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.widget.Toast
import androidx.activity.ComponentActivity
import androidx.databinding.DataBindingUtil
import androidx.fragment.app.Fragment
import androidx.lifecycle.Observer
import androidx.lifecycle.ViewModelProvider
import com.example.myapplication.R
import com.example.myapplication.databinding.FragmentAccountBinding


class AccountsFragment : Fragment() {

    private lateinit var binding: FragmentAccountBinding
    private lateinit var viewModel: AccountsViewModel

    override fun onCreateView(
        inflater: LayoutInflater ,
        container: ViewGroup? ,
        savedInstanceState: Bundle?
    ): View {
        viewModel = ViewModelProvider(this).get(AccountsViewModel::class.java)
        binding = DataBindingUtil.inflate(
            inflater,
            R.layout.fragment_account,
            container,
            false
        )
        binding.lifecycleOwner = viewLifecycleOwner
        binding.login.setOnClickListener{
            viewModel.onLogin(binding.email.text, binding.password.text)
        }

        binding.signup.setOnClickListener{
            viewModel.onSignup(binding.email.text, binding.password.text, binding.name.text)
        }

        binding.getUser.setOnClickListener{
            viewModel.onGetUser()
        }

        binding.logout.setOnClickListener{
            viewModel.onLogout()
        }

        viewModel.error.observe(viewLifecycleOwner, Observer { event ->
            event?.getContentIfNotHandled()?.let { // Only proceed if the event has never been handled
                Toast.makeText(requireContext(), it.message , Toast.LENGTH_SHORT).show()
            }
        })

        viewModel.response.observe(viewLifecycleOwner, Observer { event ->
            event?.getContentIfNotHandled()?.let {
                binding.responseTV.setText(it)
            }
        })

        return binding.root
    }
}

🔧 Update Main Activity

Finally, let's update our MainActivity.kt, that will initialise our Client singleton and add the AccountsFragment to the FragmentContainerView.

package com.example.myapplication

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import androidx.fragment.app.add
import androidx.fragment.app.commit
import com.example.myapplication.utils.Client

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        Client.create(applicationContext)

        if (savedInstanceState == null) {
            supportFragmentManager.commit {
                setReorderingAllowed(true)
                add<AccountsFragment>(R.id.fragment_container_view)
            }
        }
    }
}

You should now be able to run your app and create users, login, logout and get information about the currently logged in user!

🔐 Adding OAuth Support

You would have noticed that we have a Login With Facebook button in our UI but it doesn't really do anything yet. So let's now add Facebook OAuth to our app!

The first step is to add a callback activity in the AndroidManifest.xml file.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">
    <application

        <!-- Other Activities -->
        <activity android:name="io.appwrite.views.CallbackActivity" >
            <intent-filter android:label="android_web_auth">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="appwrite-callback-6070749e6acd4"  />
            </intent-filter>
        </activity>

    </application>
</manifest>

Make sure you replace the Project ID in <data android:scheme="appwrite-callback-[PROJECT-ID]" /> with your own.

Next, we'll add a function to our ViewModel to call the createOAuth2Session() method of the Appwrite SDK.

fun oAuthLogin(activity: ComponentActivity) {
        viewModelScope.launch {
            try {
                accountService.createOAuth2Session(activity, "facebook", "appwrite-callback-6070749e6acd4://demo.appwrite.io/auth/oauth2/success", "appwrite-callback-6070749e6acd4://demo.appwrite.io/auth/oauth2/failure")
            } catch (e: Exception) {
                _error.postValue(Event(e))
            } catch (e: AppwriteException) {
                _error.postValue(Event(e))
            }
        }
    }

The success and failure URLs take the following form
appwrite-callback-[PROJECT-ID]://[YOUR APPWRITE ENDPOINT]/auth/oauth2/[ success | failure ]

Make sure you replace the Project ID and Endpoint with that of your own.

The last step is to invoke this function from AccountsFragment.kt

override fun onCreateView(
        inflater: LayoutInflater ,
        container: ViewGroup? ,
        savedInstanceState: Bundle?
    ): View? {

        // ... Existing Methods

        binding.oAuth.setOnClickListener{
            viewModel.oAuthLogin(activity as ComponentActivity)
        }
    }

Re-run your app and you should now be able to trigger your Facebook OAuth Flow! With that, you now know how to interact with Appwrite's Accounts API in your Android Apps!

We've built a complete app that interacts with all of Appwrite's APIs, which you can find over at our Github Repo. If you'd like to learn more about Appwrite or how Appwrite works under the hood, we've just curated all the resources for you during 30 Days of Appwrite.

✨️ Credits

Hope you enjoyed this article! We love contributions and encourage you to take a look at our open isuses and ongoing RFCs.

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans 👩‍💻.

Here are some handy links for more information:

Announcing Appwrite 0.9: The open source Firebase alternative

Christy Jacob — Wed, 07 Jul 2021 14:27:41 +0000

The last month was a crazy one. We've put together over 250 commits, 20k lines of code and countless hours to bring you the best Appwrite version ever! With that, we're incredibly excited to announce the release of Appwrite 0.9, packed with a ton of cool new features like Android support, Kotlin Server SDK, Flutter Desktop Support, and much more! Without spending any more time, let's dive in! 🤿

Appwrite is an open-source, self-hosted Backend-as-a-Service that aims to make app development easier with SDKs available in a variety of programming languages. Come hang out with us on Discord.

🤖 Android Support

It's finally here 📌 Appwrite now has official support for Android! Our SDK has been out in the wild for over 2 weeks now - we've gathered some amazing feedback from the community, and we're now ready to present it to all of you! We've got all the setup instructions in our new Getting Started Guide, but here's what you'll need to do, in a nutshell 🥜.

Include the mavenCentral() repository in your project's build.gradle(.kts) file

repositories {      
    mavenCentral()
}

Add the Android SDK in your app's build.gradle(.kts) file.

dependencies {
    implementation("io.appwrite:sdk-for-android:0.0.1")
}

🤩 Then make your first request using

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.Account

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 account = Account(client)

        GlobalScope.launch {
            val response = account.create(
                email = "email@example.com",
                password = "password",
            )      
        }
    }
}

We also have some example apps to help you get started

A bare minimum Playground App to help you quickly start building apps.
A Getting Started App that has interactions with all of Appwrite's endpoints.
A Simple Quiz App built with Appwrite.

🦾 Kotlin Server SDK

We also released a brand new Kotlin Server SDK to go along with the Android one! Setting up the Kotlin SDK is a similar drill. You can check out our Getting Started Guide or follow along for a quick summary.

Add the dependency to your pom.xml file.

<dependencies>
    <dependency>
        <groupId>io.appwrite</groupId>
        <artifactId>sdk-for-kotlin</artifactId>
        <version>0.0.1</version>
    </dependency>
</dependencies>

Or your build.gradle(.kts) file if using Gradle as your build system.

dependencies {
    implementation("io.appwrite:sdk-for-kotlin:0.0.1")
}

🚀 Then make your first request using

import io.appwrite.Client
import io.appwrite.services.Users

suspend fun main() {
    val client = Client(context)
      .setEndpoint("https://[HOSTNAME_OR_IP]/v1") 
      .setProject("5df5acd0d48c2")
      .setKey("919c2d18fb5d4...a2ae413da83346ad2")

    val users = Users(client)
    val response = users.create(
        email = "email@example.com",
        password = "password",
    )

    val json = response.body?.string()
}

We also have some example apps to help you get started

A bare minimum Playground App to help you quickly start building apps.
We also have some really cool Cloud Function demos using our Kotlin SDK.

🖥️ Flutter Desktop Support

With Appwrite 0.9, we've enabled platform wide support for your Flutter Desktop Apps! You can now register your Linux, Windows and Mac apps from the Dashboard!

🏃 New Cloud Function Runtimes

Our Cloud Function runtimes list continues to grow with over 20+ (!) runtimes. This time we've added support for deno-1.10, deno-1.11, dart 2.13, node-16.0 , java-11.0 and java-16.0. We've got you covered 💪 no matter what your favourite language is! If you're looking for some creative ways to get started with Cloud Functions, feel free to check out our demos.

⚒️ Breaking Changes

Breaking changes are hard, but unfortunately, they're a necessary evil! We've kept those nasty breaking changes to a bare minimum with this release and only made changes to our Server SDKs:

env has been renamed to runtime in the POST v1/functions endpoint. If you're using named parameters in your server SDKs, you will need to update them.
deleteUser has been replaced in favour of the delete method in all our Server SDKs.

🚀 Everything else

Our Image Preview 📸 endpoint now let's you specify a gravity giving you much more control when cropping your images!
One of our community members @Meldiron, helped speed up our Cloud Function executions by upto a whopping 4s 🤯 in some cases.
We revamped our User Sessions UI in the Dashboard to give you more fine grained information about a user's session.
We've added some additional metadata in our File Preview Dialog to make it easier to view your file types, file size and the creation date.
Internally, we've optimized our database connection pools for overall improved server performance 🤩
Gone are the days of running multiple migration scripts to upgrade to the latest version of Appwrite! From Appwrite 0.9, it's just a single script!
Based on popular demand, we've added a new endpoint to get a session by ID and another endpoint to force update the user verification status from Server Side SDKs.
Last but not the least, we've overhauled our Email Templates in an attempt to offer lot more customization in the future!
Let's not forget, you also helped us reach a major milestone of 10k Github stars ⭐️ making us one of the top 2000 projects in Github history! We also crossed a landmark 2.2M Docker pulls and over 40k reads on our blog posts! Thank you so much for all your support!

😍 And More!

We still haven't covered everything! There's lots more bug fixes and other micro optimizations we made under the hood to make your experience with Appwrite better! To get all the details on Appwrite 0.9, check out all the changes in the changelog on GitHub.

If you're upgrading from an older version of Appwrite, be sure to follow our Upgrading guide so that you don't loose your way in uncharted territories 😉.

Are you curious about the big ideas we have up next, or have a great idea for Appwrite's future? Check out the RFC Repository for more details. Also, our awesome-appwrite repository keeps growing with new tutorials, videos, and demos.

If you've just discovered Appwrite and would like to get started, check out out our 30 Days of Appwrite series where we explain step-by-step everything you need to know to build awesome Appwrite-powered apps. Follow us on Twitter, Dev.to, or anywhere you find your friendly neighbourhood Appwrite.

#30DaysOfAppwrite: Grafana Integration

Christy Jacob — Sat, 29 May 2021 13:13:04 +0000

Intro

Appwrite is an open-source, self-hosted Backend-as-a-Service that makes app development easier with a suite of SDKs and APIs to accelerate app development. #30DaysOfAppwrite is a month-long event focused on giving developers a walkthrough of all of Appwrite's features, starting from the basics to more advanced features like Cloud Functions! Alongside we will also be building a fully-featured Medium clone to demonstrate how these concepts can be applied when building a real-world app. We also have some exciting prizes for developers who follow along with us!

Grafana Integration

Welcome to Day 29 👋 - today marks the last day of #30DaysOfAppwrite, and we thought it would be a fun little exercise to show you how you can add external services to the Appwrite stack and make it work seamlessly! We love Dashboards, and we thought it would be great to add Grafana support to Appwrite.

Appwrite doesn't come with Grafana out of the box for several reasons. First, you may already have your own set of monitoring tools in your stack, and we believe that our stack should be un-opinionated and allow you to work with the tools you feel comfortable with. The second reason is that we try to ship the Appwrite setup with minimal components to make Appwrite easy to start but still flexible enough to grow.

Add Grafana to Appwrite

We will be creating two Dashboards: one for monitoring Appwrite's usage stats and one for monitoring your Server stats.

The first step is to add the Grafana service to Appwrite's docker-compose.yml file.

  grafana:
    image: grafana/grafana
    container_name: appwrite-grafana
    ports:
      - "3000:3000"
    networks:
      - appwrite
    volumes:
      - appwrite-grafana:/var/lib/grafana

Next, you need to add the appwrite-grafana volume to the list of all volumes. This will allow your Grafana container to persist data.

volumes:
  appwrite-mariadb:
  appwrite-redis:
  appwrite-cache:
  appwrite-uploads:
  appwrite-certificates:
  appwrite-functions:
  appwrite-influxdb:
  appwrite-config:
  appwrite-grafana:

Now run:

docker-compose up -d

Dashboard #1 - Appwrite Metrics

We don't need any additional configuration for your first Dashboard in our services. Now head over to http://localhost:3000 to configure Grafana. You can log in using the default credentials:

username : admin
password : admin

You will be prompted to enter a new password, and it is highly recommended that you change the default password. Learn more about managing users and passwords in their official guide.

The first step is to configure your Data Source. In our case, we will be using the InfluxDB plugin.

Once you add the InfluxDB data source, it's time to configure it. Here, you need to fill in the values of 2 fields,

URL - http://influxdb:8086
Database - telegraf

Finally, click Save and Test to check your database connection. If all goes well, you will see a success message.

The next step is to import the Dashboard we created for you. Head to the Grafana's Dashboard Library and copy the ID of our Dashboard.

You can then Import the Dashboard in your Grafana instance like so.

And that's it! You should now see this fancy Dashboard

Dashboard #2 - Server Metrics

The next Dashboard is one that will monitor our server metrics. This includes CPU usage, Disk I/O, Network I/O, and much more. This Dashboard requires some additional info, so we need to make a few changes in our telegraf Docker image to make this information available.

We'll start by cloning Appwrite's telegraf image

git clone https://github.com/appwrite/docker-telegraf.git 
cd docker-telegraf

We need to make more metrics available to the collector. Add the following lines to line 83

[[inputs.cpu]]
    percpu = true
    totalcpu = true
    collect_cpu_time = false
    report_active = false
[[inputs.disk]]
    ignore_fs = ["tmpfs", "devtmpfs", "devfs"]
[[inputs.io]]
[[inputs.mem]]
[[inputs.net]]
[[inputs.system]]
[[inputs.swap]]
[[inputs.netstat]]
[[inputs.processes]]
[[inputs.kernel]]

Now we need to build a new Docker image using the changes we made.

docker build -t telegraf-local .

Once this build is complete, we can make use of our new telegraf-local image in the main Appwrite docker-compose.yml. Replace the appwrite/telegraf:1.1.0 image in line 434 with our telegraf-local image.

  telegraf:
    image: telegraf-local
    container_name: appwrite-telegraf
    networks:
      - appwrite

Now run docker-compose up -d --remove-orphans from your appwrite directory to restart your services.
Now head over to your Grafana Dashboard and import this new Dashboard the same way as you did the previous one, and if everything goes well, you should see the following Dashboard!

And just like that, you now have access to all your server information in one place! This was just the tip of the iceberg! Grafana has many more amazing features. It's completely open-source, has support for over 30 Data Sources, has support for Alerting etc. You can set up custom alerts, and Grafana will continuously evaluate and send notifications to systems like Slack, PagerDuty, VictorOps, and OpsGenie. You can learn more about all of Grafana's features in their dedicated tutorials section.

Credits

We hope you liked this write-up. You can follow #30DaysOfAppwrite on Social Media to keep up with all of our posts. The complete event timeline can be found here

Feel free to reach out to us on Discord if you would like to learn more about Appwrite, Aliens, or Unicorns 🦄. Stay tuned for tomorrow's article! Until then 👋