Hazem Allbabidi

December 19, 2024 | 7 min read

open-source backend appwrite

Open Source: AppWrite

In this article, we will go through a tool called AppWrite, an open-source tool that offers Authentication, Databases, Storage, Functions, Messaging, and Realtime services with easy-to-use SDKs for most popular programming languages and frameworks, including JavaScript, React, Vue, Flutter, React Native, and many more!

Installation

You can choose to use the cloud version of AppWrite, but we will be self-host it using the available Docker image.

Note: if you are unfamiliar with Docker Images, check out this tutorial: https://hazemhadi.com/articles/docker-images-what-you-need-to-know/

To start, you need to ensure you have Docker installed. You can check by running the following command:

docker -v

You should get the Docker version back.

If you do not have Docker installed, you can simply follow the tutorial below from the official Docker Documentation to install it: https://docs.docker.com/engine/install/ubuntu/#installation-methods

To start the AppWrite Docker image, run the following 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:1.6.0

This will use your Docker service and create the AppWrite app containers, such as the Database container as an example.

You will be asked a few questions, you can simply press enter (i.e. choose the default answers) or input your custom configuration.

Once the command is done running, you can check the running Docker containers:

docker ps

You should see a bunch of different Docker containers running where the container names start with “appwrite-”, these are all the containers needed to run AppWrite with all its features.

Installation is done! We can now navigate to the console page. Simply open your favorite browser and go to localhost. Note: you might be asked to create an account.

Creating A Project

To use AppWrite, you will have to create a project. Simply click on the “Create Project” button in the home page and then insert the project name (in my case, I simply called it “Test”).

You will be asked to choose a platform, such as Flutter, Android, Apple, or even API Keys. For the purpose of this tutorial, choose “Web” as your platform.

Next, you will be asked to input the application name, as well as the hostname. For the project, I simply wrote “My Web App”, and for the hostname, I used localhost since we are doing all of this locally (for testing).

Next, you will see the installation methods:

  1. NPM: install the SDK as a package
  2. CDN: import the SDK through an online link

I recommend using the first method (NPM) since it should work even if your internet is off.

Create a Node JS Project

In order to actually test AppWrite, we will create a new Node JS.

Create a new directory and inside, run:

npm init -y

This will create a package.json with the default values. In the file, add a new key/value:

...
"type": "module"
...

This will allow you to use import in your application instead of require.

Next, install the appwrite Client SDK:

npm install appwrite

Note: there are two types of SDKs for AppWrite. The first SDK (Client) is for client-side actions such as creating a new object in the database. The second SDK (Server) is for more administrative actions, such as creating a new Database. In this tutorial, we will use the Client SDK since we want to do basic actions only.

Next, create a new file called index.js, and inside, add the following (this will be displayed in the steps of app creation in the console):

import { Client } from 'appwrite';

const client = new Client();

client
    .setEndpoint('http://localhost/v1')
    .setProject('<PROJECT ID HERE>');

We now have the base set-up to allow us to use the Client SDK for AppWrite. We will now go back to the console to create a new Database and a new Collection.

Creating The Database

Head to the AppWrite console and choose the project we created.

Next, navigate to the Databases page and click on Create Database, type in a name (I simply used Test) and click on Create (you can leave the Database ID input blank since AppWrite will create a randomly generated ID).

Once that is done, you will be redirected to the database page which displays the database collections.

Click on Create Collection and insert a name for the collection (I inserted Users).

Now we need to create the Attributes of this collection. We will create two attributes which will be of type String, have a size of 25, and will be required. The first attribute will be the first_name and the second attribute will be last_name.

To create those attributes, navigate to the Attributes tab and click on Create attribute, choose String, set the Attribute Key as first_name, set the size to 25, and make sure it is Required. Follow the same steps for the last_step.

Before we move any further, we have to set the access permissions for this collection. While in the Users collection page, navigate to the Settings page, scroll down until you see Permissions. Click on the + sign and choose Any, then make sure you check all the boxes for Create, Read, Update, and Delete.

NOTE: NEVER DO THIS IN PRODUCTION. ALWAYS SET PROPER PERMISSIONS FOR THE PROPER USERS WHO SHOULD HAVE ACCESS. WE ARE ONLY ALLOWING ANY USER FOR TESTING PURPOSES.

Finally, you need to copy both the Database ID (you will find it right beside the database name) and the Collection ID so that we can use them in the next step.

Inserting Into The Database

We will use the copied Database ID and Collection ID from the previous step to insert a new document in the collection using the Client SDK.

Go back to your code editor and open the index.js file and update the content to the following:

import { Client, Databases, ID } from 'appwrite';

const client = new Client();

client
    .setEndpoint('http://localhost/v1')
    .setProject('<PROJECT ID>');

const databases = new Databases(client);

const result = await databases.createDocument("<DATABASE ID>", "<COLLECTION ID>", ID.unique(), {
    "first_name": "Hazem",
    "last_name": "Allbabidi"
})

console.log(result)

First, we imported the Databases class from the appwrite SDK to allow us to read, create, update, and delete documents from the different databases and collections. We also imported the ID class to help us generate random IDs.

Next, we set up the database class:

const databases = new Databases(client);

Next, we create a new document by inserting the Database ID, Collection ID, a uniquely generated ID, and an object with the same attributes we specified the console, which are the first_name and last_name.

Lastly, we will print the output using console.log.

Now, run the file in the terminal:

node index.js

We should similar an output similar to the one below:

{
  first_name: 'Hazem',
  last_name: 'Allbabidi',
  '$id': '<DOCUMENT ID>',
  '$permissions': [],
  '$createdAt': '2024-12-19T08:31:24.118+00:00',
  '$updatedAt': '2024-12-19T08:31:24.118+00:00',
  '$databaseId': '<DATABASE ID>',
  '$collectionId': '<COLLECTION ID>'
}

This means that the document was created successfully!

To view the list of documents we created, you can either edit the index.js file to:

import { Client, Databases, ID } from 'appwrite';

const client = new Client();

client
    .setEndpoint('http://localhost/v1')
    .setProject('<PROJECT ID>');

const databases = new Databases(client);

const result = await databases.listDocuments("<DATABASE ID>", "<COLLECTION ID>")

console.log(result)

And running it:

node index.js

Which will return the list of documents along with the total:

{
  total: 1,
  documents: [
    {
      first_name: 'Hazem',
      last_name: 'Allbabidi',
      '$id': '<DOCUMENT ID>',
      '$createdAt': '2024-12-19T08:31:24.118+00:00',
      '$updatedAt': '2024-12-19T08:31:24.118+00:00',
      '$permissions': [],
      '$databaseId': '<DATABASE ID>',
      '$collectionId': '<COLLECTION ID>'
    }
  ]
}

Or you can head to the console, choose the database, then choose the collection. You should see a list of all the documents that have been created.

Uninstalling AppWrite

To completely remove AppWrite, you can run the following Docker command:

docker container stop $(docker ps -q --filter name=appwrite)

This will find all the AppWrite container using the name filter and then stop them all.

To completely delete the containers, simply run:

docker container rm $(docker ps -aq --filter name=appwrite)

Note: this will delete any data as well.

Conclusion

AppWrite is a great tool to use to speed up the development process and to have more functionality which are much more easily accessible, such as Messaging and Authentication.

I hope you enjoyed this article and benefitted from it. See you in the next one!

Previous

How GitHub Uploads and Secures Images
Sign Up To Binance To Get 10% Off Commission Fees Sign Up To Kucoin