DEV Community: Obisike Treasure

Steps to manipulating MongoDB with AI

Obisike Treasure — Tue, 07 Jan 2025 17:12:26 +0000

Meta: Integrate AI into your MongoDB workflow with Cody. This tutorial helps you automate database tasks, create queries, and manage data more effectively in VSCode.

MongoDB has become a popular choice for developers, offering features like time series data, full-text search, vector search, and aggregation pipelines. Since its introduction in 2007, it has been downloaded over 365 million times, largely due to its open-source development model.

However, working with MongoDB‘s features, such as replica sets and built-in replication, can sometimes be challenging. Advanced querying, building complex aggregations, and managing tasks like indexing or replication through its integrated set of related services can become cumbersome and time-consuming.

That is where Sourcegraph‘s Cody comes in. Cody is an AI assistant designed to streamline development tasks by helping you generate efficient queries, simplify aggregation creation, and manage key operations like indexing and replication.

In this tutorial, you will learn how to integrate AI into your MongoDB project. You will be guided through using Cody to write queries, perform aggregations, and manage database operations step by step.

Prerequisites

To follow along, you will need:

Visual Studio Code (VSCode): Ensure it is installed as your code editor.
Basic MongoDB knowledge: Familiarity with MongoDB is needed to follow the tutorial effectively.
JavaScript knowledge: Basic JavaScript skills are required for scripting and writing uncomplicated queries.

Setting up the environment

To continue with the tutorial, you must install and set up both MongoDB and Cody in your code editor (VSCode).

Installing and setting up MongoDB

Start by installing the MongoDB server. For instructions specific to your operating system, refer to the official MongoDB installation documentation

Note: For this tutorial, install the MongoDB community edition.

Follow the guide that matches your operating system to get MongoDB running. You can also use MongoDB Atlas, the cloud-hosted database service.

Next, install the official MongoDB extension for VS Code to interact with your locally hosted MongoDB server. Search for “MongoDB for VS Code” in the extensions section, or use the MongoDB extension link to get it from the marketplace.

Click Install when you find the extension. After installation, you will need to connect your MongoDB extension to your local MongoDB server.

Connecting your MongoDB server to the extension

To connect your VSCode MongoDB client to the database server, you'll need the host address, port number, and password. For the community edition, your host address is usually localhost, and the port is 27017, provided the MongoDB server is running, and the port is available.

Open the MongoDB extension from the sidebar in VSCode.

Click Add Connection to create a new connection.

Next, click Open form to enter your credentials (host, port, and password if needed).

Click Save & Connect, then update the URI field with your credentials in the format below:

mongodb://<host>:<port>

Your MongoDB setup is now complete.

Next, you will create a playground to run your MongoDB commands. Click Create New Playground.

This will generate a playground-1.mongodb.js file where you can write and test your commands.

Delete the file content, keeping only use("mongdbVSCodePlaygroundDB"), which specifies the database for the playground.

Now that you’ve completed the setup for MongoDB let’s proceed to set up Cody in your VSCode environment.

Installing and configuring Cody

Cody supports multiple development environments, including JetBrains IntelliJ and VSCode. To install it in VSCode, open the VSCode Marketplace and search for “Cody AI” in the extensions search bar. Locate the Cody extension as shown below:

Once located, select Install to add Cody to your VSCode setup.

If you do not have an account, create one to access Cody.
Follow the on-screen instructions to sign in and start coding with Cody.

Writing MongoDB operations, queries, and aggregations

While MongoDB offers a flexible database language, writing queries manually can often lead to errors and take up a significant amount of time, particularly for complex operations. Let’s look at how you can perform the following operations:

InsertMany
Find
Aggregations

InsertMany Operation

For example, suppose you have a collection called students and need to insert around 30 records from a JSON or CSV file.

Manual approach: You would need to format all the records as an array of objects, ensuring that each entry matches the fields in the collection. This might look something like this:

const data = [
    { 
       firstName: "Mike", 
       lastName: "Owen", 
       grade: 2, 
       houseNumber: 5, 
       nextOfKin: "Ben"
       // additional fields...
    },
    { 
       firstName: "Patrick", 
       lastName: "Elijah", 
       grade: 1, 
       houseNumber: 5, 
       nextOfKin: "Ben"
       // additional fields...
    }
    // more records...
];
db.students.insertMany(data);

Manually entering data in this format can be tedious and error-prone, especially when dealing with large datasets.

Cody’s approach: With Cody, streamlining this process is simple. Copy the data from your file, then press Opt + K (or Alt + K) or right-click, select Cody, and choose Edit code to open the Edit Code interface.

Next, type in the following instructions:

Write a MongoDB query to insert `<paste your data here>` into the student's collection.

Here is a video on how you can perform the insertMany using Cody.

Cody will generate the query for you. Simply click Accept to confirm the generated code.

You can then run the code by clicking on the play icon in the playground.

Find Query

Let’s say you need to retrieve all students with a GPA above 3.5 who enrolled between March and November. Here is how to do it.

Manual approach: You might use the find method to handle this query. However, dealing with date ranges in MongoDB can get tricky, especially when you need to match specific months.

Here is an example of what you might come up with:

db.students.find({
  gpa: { $gt: 3.5 },
  enrolmentDate: {
    $gte: new Date("1900-03-01T00:00:00Z"),
    $lt: new Date("3000-12-01T00:00:00Z")
  }
});

While this query seems to work, it has some potential issues; first, it won't fetch data beyond the year 3000. Additionally, the query retrieves data based on the date rather than specifically targeting the month. If you're not highly experienced with MongoDB, finding the correct function can be challenging.

Cody approach: With Cody, you can open the Edit interface once again, then type:

Write a query to fetch all students with a GPA above 3.5 and an enrolment date between March and November.

Cody generates the query for you, saving time and effort, as demonstrated in the video below.

Similarly, you can do the same for the update, updateMany, and delete operations.

Performing Aggregations

The aggregation pipeline allows you to perform more complex queries and subqueries.
Let's say you need to calculate the average GPA of students who enrolled between March and November and group them by their enrollment year. Aggregation can be complex, especially when you're trying to perform calculations or grouping.

Manual approach: You would have to use the aggregate method to group and calculate, possibly using multiple stages like $match, $group, and $project. This can be quite challenging if you‘re not familiar with MongoDB's aggregation framework.

Here is an example of what you might come up with:

db.students.aggregate([
  {
    $match: {
      enrollment_date: {
        $gte: new Date("1900-03-01T00:00:00Z"),
        $lt: new Date("3000-12-01T00:00:00Z")
      }
    }
  },
  {
    $group: {
      _id: { $year: "$enrollment_date" },
      averageGPA: { $avg: "$gpa" }
    }
  },
  {
    $project: {
      _id: 0,
      enrolmentYear: "$_id",
      averageGPA: 1
    }
  }
])

While this works, it involves multiple stages and requires some knowledge of the MongoDB aggregation pipeline. Getting it right can be tricky, especially when working with date ranges and grouping data.

Cody’s approach: With Cody, you can just open the Edit interface and type:

Write an aggregation query to group students by the year they enrolled, calculate the average GPA for each group, and only consider students who enrolled between March and November.

Next, Cody generates the aggregation pipeline:

db.students.aggregate([
  {
    $match: {
      $expr: {
        $and: [
          { $gte: [{ $month: "$enrollment_date" }, 3] },
          { $lte: [{ $month: "$enrollment_date" }, 11] }
        ]
      }
    }
  },
  {
    $group: {
      _id: { $year: "$enrollment_date" },
      averageGPA: { $avg: "$gpa" }
    }
  },
  {
    $project: {
      _id: 0,
      enrollmentYear: "$_id",
      averageGPA: { $round: ["$averageGPA", 2] }
    }
  },
  {
    $sort: { enrollmentYear: 1 }
  }
])

Here is a video of Cody in action.

Creating Cody’s custom command to help with writing queries and operations

Creating Cody’s custom command allows you to automate tasks related to your MongoDB database interactions, making your workflow more efficient. These commands can be fine-tuned to generate, optimize, or refactor data requests, all while leveraging Cody's context-aware capabilities to ensure they fit seamlessly within your codebase.

Let's create one. First, click the Cody extension icon:

Next, click Manage:

Then, click New Custom Command:

Enter “MongoDBExpert” as the command name.

Select Ask for the command mode, which controls how Cody interacts with the editor (VSCode):

Now, enter the following prompt:

You are a MongoDB expert skilled in writing optimized queries, operations, and aggregation pipelines. You provide practical advice on managing tasks like sharding, replication, and indexing to improve performance and scalability.

The above prompt tells Cody to assume a role as an expert in MongoDB.

Ensure that Selected Code and Current File are both checked so the command has access to the highlighted source code and the current file you are working with:

Choose Workspace Settings to store the command for this workspace:

Your Cody command is ready and can be used within the project's workspace.

Updating operation using the command

Building on our previous example with student records, imagine you need to update the expected graduation dates for students born in March by adding five years. You need to perform the following actions.

First, click the Cody extension icon and select the MongoDBExpert command:

In the chat box, type:

Write an operation to update the students database so that for every student born in March, add 5 more years to their expected_graduation.

Click the Play icon to execute the instruction:

After that, click Copy, then paste it into your playground to test:

Managing MongoDB operations

Managing MongoDB operations involves various tasks, including indexing and replication. Understanding and effectively utilizing these tasks is crucial for maintaining the performance, availability, and scalability of your MongoDB database.

Indexing

Indexes improve query performance by allowing MongoDB to quickly locate data without scanning every document in a collection. Here's how you can work with indexes.

Manual approach: To create indexes, you must be aware of the data points that affect the speed of querying information. For example, you can create an index with the following command:

db.students.createIndex({ email: 1, enrollment_date: 1 })

While this works, it's not necessarily the most efficient approach.

Cody’s approach: You can leverage Cody to optimize this process. First, activate Cody‘s chat by using Opt + L (or Alt + L). Cody will automatically access the context of your playground file.

Enter the following prompt:

Given that I would mostly be trying to get students by their enrollment_date, name, and probably by when they graduate and their GPA, suggest the best approach to indexing.

After that, Cody will provide an optimized solution and a step-by-step guide to implementing your indexing.

You can then click on Apply to add these changes to your file.

Here is the Code Indexing code generated by Cody.

Here is the final result:

Replication

Replication involves creating copies of your data across multiple servers to ensure redundancy, high availability, and fault tolerance. Here’s how you can perform replication.

Manual approach: To set up replication, you must decide the number of servers based on your available resources and database load. Then, perform the following steps:

Spin up different instances of MongoDB:

# On server 1:
mongod--auth--replSet "rs0" --bind_ip localhost, server1_ip--port 27017 --dbpath / data / db1

# On server 2:
mongod--auth--replSet "rs0" --bind_ip localhost, server2_ip--port 27017 --dbpath / data / db2

# On server 3:
mongod--auth--replSet "rs0" --bind_ip localhost, server3_ip--port 27017 --dbpath / data / db3

Connect to one instance and configure the replica set:

rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "server1_ip:27017" },
    { _id: 1, host: "server2_ip:27017" },
    { _id: 2, host: "server3_ip:27017" }
  ]
})

You may encounter issues such as determining the appropriate number of replicas, choosing the best approach for handling read and write within the replica set, and ensuring optimal replication.

Cody's approach: To simplify this process, use a custom command in Cody. Navigate to the custom command section and enter the following prompt:

What is the best approach to setting up replication in MongoDB for a students database that requires high availability and minimal downtime during failovers? Consider a setup that includes at least one primary and two secondary nodes, and explain how to configure read preferences for optimal performance while ensuring data consistency.

Next, Cody will suggest how you can approach replication to improve the availability of your database.

After following Cody's instructions, click Apply to add the code-related section to the file to be executed.

You can even ask Cody to write the commands (in any of your preferred programming languages) that efficiently handle the Read or Write across the replicas.

Overall, using AI tools like Cody is about making your MongoDB operations smoother and more effective—working alongside your expertise to overcome any challenge.

Key takeaways

By integrating AI into your development teams’ workflow, you can further improve your development process and create better solutions faster. It‘s not about replacing your MongoDB skills but amplifying them with the support of AI.
With an AI tool like Cody, you can:

Adapt quickly to new challenges.
Write efficient queries and improve operations.
Enhance your database management skills.

So, by combining your creativity and expertise with AI's vast knowledge, you can build better tools and deliver improved products to your customers.

Ready to take the next step? Sign up for Cody today.

Quickly build UI components with AI

Obisike Treasure — Tue, 17 Dec 2024 14:52:56 +0000

Building UI components usually means writing a lot of code from scratch, fixing minor bugs, and working closely with designers to bring static designs to life. It’s always time-consuming, with you manually handling every detail, from layout to performance tweaks.

AI is now changing how you can approach building UI elements. Instead of spending hours on repetitive tasks, you can use AI tools to quickly build and refine your UI components.

In this guide, you’ll learn how to build and customize UI elements, create style guides, and develop more complex UIs using AI. By the end, you'll see how tools like Cody reduce the time and effort involved in your UI development.

Prerequisites

To follow along with this tutorial, you’ll need the following:

Visual Studio Code (VSCode)
Fundamental knowledge of React and TailwindCSS
Node.js installed

Once these are in place, you'll need to set up the development environment.

Setting up the environment

You’ll need to set up a React project, install Cody on your VSCode editor, and use Cody to configure TailwindCSS. This setup will serve as your development environment. Check out this GitHub repository to see the full project you'll be building.

Let’s start by creating the React project.

Creating your React project

To create your React project, open your terminal and run the following command:

yarn create vite cody-react --template react-ts

This command initializes a new React project with TypeScript, creating a project folder named cody-react in your current directory.

Next, open the project folder in your VSCode editor. Once it's open, you can proceed to install and configure Cody.

Steps to install and configure Cody

To set up Cody on your VSCode editor, start by installing Cody’s VSCode extension.

Next, you’ll have to sign up to be able to use Cody on your VSCode. Select your preferred sign-up method to continue and complete the account creation flow.

For additional information, you can refer to the Cody documentation.

To improve your workflow and avoid the need to rewrite prompts multiple times, utilize Cody's custom commands. This will allow you to apply the same prompts across all the components you create, saving you time and effort.

Let's set up some of Cody's custom commands.

Setting up the Cody commands

To create custom commands in your workspace, follow these steps:
First, open the VS Code Command Palette by pressing Ctrl + Shift + P (Windows/Linux) or Cmd + Shift + P (Mac). Type Cody Menu: Custom Commands and select it.

In the Cody commands menu, select Custom Commands > New Custom Command.

Enter a descriptive name for your new custom command, such as ui-components-creator.

Next, select the “ask” mode since you’ll mostly be using the Cody chat.

After that, enter the instructions that Cody will use when executing the command. You'll be creating two commands, and here are the detailed instructions for each:

For the ui-components-creator command, use the following prompt:
You are an expert in React+Tailwind+TS UI component design. Design the component. Note: Do not use template literals for tailwind classes.
For the ui-components-customizer command, use the following prompt:
You are an expert in React+Tailwind+TS component design. Customize the component to follow the design system defined in the tailwind.config.js file, create variants based on sizes and colors, and also add things like the hover and active states. Note: Do not use template literals for tailwind classes.

For this project, the ui-components-creator command will be used to generate the basic UI components, while the ui-components-customizer command will be used to customize these components to align with the design system.

Choose one or more options for the context Cody should use to generate responses. This should include the Current File, Selected Code, and the Current Directory.

Since you’re setting up the command for just this workspace, select the User Settings option.

Press Enter to finalize the creation of your custom command. For further information, you can refer to the documentation;

Here is how your custom commands should look in your VSCode workspace settings:

// .vscode/cody.json
{
   "ui-components-creator": {
     "prompt": "You are an expert in React+Tailwind+TS UI component design. Design the component. Note: Do not use template literals for tailwind classes.",
     "context": {
        "selection": true,
        "currentFile": true,
        "currentDir": true
     },
     "mode": "ask"
  },
  "ui-component-customizer": {
     "prompt": "You are an expert in React+Tailwind+TS component design. Customize the component to follow the design system defined in the tailwind.config.js file, create variants based on sizes and colors, and also add things like the hover and active states. Note: Do not use template literals for tailwind classes.",
     "context": {
       "selection": true,
       "currentFile": true,
       "currentDir": true,
    },
    "mode": "ask"
  }
}

Next, let’s set up Tailwind CSS in your development environment.

Setting up Tailwind CSS for your development environment

To set up Tailwind CSS on the project, you'll need to install Tailwind CSS and its peer dependencies. This can be done by running the command.

yarn install -D tailwindcss postcss autoprefixer

With the dependencies installed, generate the Tailwind configuration files. This is easily done by executing the command below:

npx tailwindcss init -p

This command will create both tailwind.config.js and postcss.config.js files in your project.

To ensure Tailwind can remove unused styles in production, open the tailwind.config.js file and specify the paths to all your template files. Your configuration should look something like this:

module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Next, you need to add Tailwind’s directives to your CSS. Create a CSS file in the src directory, for example, src/index.css, and include the following directives:

@tailwind base;
@tailwind components;
@tailwind utilities;

Import this CSS file into your React application by adding import './index.css'; to your src/index.js or src/index.tsx file.

For more detailed information, you can refer to the Tailwind CSS documentation.

Next, you’ll need to set up your Tailwind CSS theme configuration, which will serve as the design guide for your components. This configuration will include defining colors, padding, and other style properties. For this tutorial, we’ll be using the following color codes: #00CBEC, #A112FF, and #FF5543.

Navigate to your tailwind.config.json file. Use Opt + K (or Alt + K on Windows) to open Cody’s Edit Command interface. Highlight all the content of the file.

Next, enter the following prompt:

Update the Tailwind configuration to include the colors #00CBEC, #A112FF, and #FF5543, along with custom fonts, spacing, and other design systems elements like border-radius, box shadows, and breakpoints.

Then click Submit.

After that, review and Accept the changes proposed by Cody.

Once you’ve successfully set up tailwind on your project, let’s create the UI components.

Creating basic UI components

A good UI is built with components like buttons, switches, text inputs, progress bars, tabs, and many more. These elements are the core of a UI design system and shape the user experience.

Traditionally, creating these components involves manually writing the code, which can be time-consuming, especially when handling multiple components. Cody simplifies this by generating code for a component directly within your project.

You’ll build the following components:

Button: Allows users to perform actions by clicking.
Switch: This lets users toggle between different states.
Text input: Allows users to enter text.
Progress bar: Shows the progress of an operation.
Tabs: Organizes high-level content.

To build these components with Cody, start by creating a dedicated components directory. Then, create a .tsx file for each component, such as Switch.tsx or TextInput.tsx. Let's begin by creating the button component.

Creating the button component

Here’s how to create a button component with Cody:

Note: The steps for creating this button can be used to create other UI elements.

After creating your Button.tsx file, open a new Cody chat by right-clicking on the code editor, selecting the Cody option from the menu, and choosing New Chat in Editor.

Alternatively, you can click the Cody icon. If an existing conversation is open, click New Chat to start a new one.

Next, click the Prompts and select the ui-components-creator option on the palette.

Then click the play icon or press Enter.

Cody will then generate the required code for the component, which you can review.

Next, click Apply to add the code to the file.

Then click Accept to accept the modifications made to the file.

Here is the code generated by Cody:

Be sure to save the changes in the file.
This is how the component would look.

The switch component

The switch component lets users toggle between different states on your website or your application. It's a straightforward way to turn features or settings on and off, with clear visual feedback showing the current state.
Once you have created your Switch.tsx component file, follow the same steps used when creating the button component.

This is the react component code generated by Cody:

Here is how the component is going to look.

The text input component

The text input component allows users to enter the text on a website or an application.
In your created TextInput.tsx component file, follow the steps illustrated in the first button component example.

The generated code is as follows.

This is the input component designed by Cody.

The progress bar component

A progress bar component shows that the application has received a user's request and is moving closer to carrying out a requested action from that user.
In the ProgressBar.tsx you created, replicate the procedures shown in the initial button component example.

See the code example generated by Cody:

This generates the output:

The tabs component

A tab component organizes high-level content in an application and supports switching between views, data sets, or functional aspects of the application.
In your created Tabs.tsx component file, apply the steps demonstrated in the button component example.

Cody generates the following:

Customizing your UI components

A consistent design enhances user experience. Customizing your components to follow a design pattern is crucial for achieving this consistency. Here's how to do it using Cody.

The button component

A button component for a design system must have variants such as size and color. Let's get Cody to do this. Since you’ve created the prompt to handle the customization request, all you need to do is follow the following steps:

First, open the Button.tsx component file. Then, open a New Chat in Editor by following the previously highlighted steps.

On the chat field, type in @. This brings out a list of files you can select from to add the file as context to your prompt. Select the tailwind.config.js file.

Next, click Prompts and select the ui-components-customizer option.

Then press Enter.

Review the generated code, apply the changes, and accept them.

Note: You can choose to accept some of the changes, depending on what you want.

Here is the final code update for the button.

This is how the button looks afterward.

Customizing the switch component

To customize the switch component, first, open the Switch.tsx file so Cody can add it to its prompt context. Then, start a new chat by following the same steps you used earlier when customizing the buttons.
Just like with the button customization, add the tailwind.config.js file to the chat's context, then select the ui-component-customizer command from the prompts.
Cody will generate this:

Here is the final look of the switch component.

Customizing the text input component

Similar to the switch component, follow the steps used in customizing the component, then apply and accept the changes from Cody.

After applying and accepting the code changes, you’ll notice that on line 3, there is a typescript error. You can use Cody to rectify this.

To do this, hover over the underlined error to display the menu.

Next, click Quick Fix.

Then click Ask Cody to Fix.

Once that is completed, accept the changes Cody suggested.

Here is the final result.

Also, here is the final output of the modifications.

You can repeat similar steps for the Progress Bar and the Tabs components.
Here is the progress bar customized look.

And here is the new tab component.

Building complex UI component systems

Now that you’ve generated the basic UI components and customized them to match your design system, you can combine these components to create a complete user interface. You can achieve this by referencing the components via their files using the @ key within your prompt.

To demonstrate, let’s create a login and register UI using all the components you created.
Navigate to your App.tsx file and open a new chat in the editor.

Next, add all your component files and the tailwind.config.json file in the chat section.

Then add the following prompt:

You are an expert in designing UI pages. You are good with react+tailwind+ts. Use the components and images from free sources like Unsplash to design a login and register UI. The login and register should be separate using the Tabs and the progress bar should calibrate when the form is being filled. Once a form field is filled out, the progress should be increased on the progress bar, and the terms and conditions should switch, too.

Next, apply the changes to your App.tsx.

After applying and accepting the changes, save the file, and then on your terminal, run the following command to start your application.

npm run dev

This starts the react development server at localhost.

As you can see, the image is broken. You can use Cody to fix it.
Navigate to the <img> tag on the App.tsx file and highlight it.

Use the Opt + K command (on Mac) or the Alt + K command (on Windows) to bring out Cody’s Edit Code interface. Then, enter the following prompt.

Replace the src with "https://images.pexels.com/photos/27582545/pexels-photo-27582545/free-photo-of-neon-lights.jpeg"

Next, accept and save the changes.

Here is the final code generated by Cody.

This is how the page looks.

Watch the video to see the Login and Register screen designed by Cody using the components.

Now that you have completed the UI, you can enhance it further by adding more context to your prompt to specify how you want your UI to look. Feel free to experiment with different prompts that you come up with.

Final thoughts

Throughout this article, you've seen how Cody can transform how you build UI components, from basic buttons to complex, dynamic systems. Cody handles the heavy lifting so you can focus on crafting good UI/UX designs. Whether you’re customizing components or managing complex UI systems, Cody provides the tools to make the process faster and more efficient.

Now, it's your turn to put these capabilities into practice. Here are a few ideas to get you started:

E-commerce product page: Create a responsive product page with a carousel, product details, and an "Add to Cart" button.
Dashboard interface: Build a dashboard with interactive charts, data tables, and navigation tabs.
Form validation: Design a multi-step form with real-time validation and progress indicators.
Landing page: Develop a landing page with a hero section, feature highlights, and a call-to-action button.

Experiment with these projects and see how Cody can assist you in building faster and improving your development workflow. Sign up now to build UIs faster with Cody.

How to collect marketing campaign email leads with Mailgun and Appwrite in minutes

Obisike Treasure — Mon, 08 Jan 2024 16:22:31 +0000

Collecting marketing campaign email leads is fundamental to modern digital marketing strategies. It systematically gathers contact information, primarily email addresses, from individuals interested in a brand's products, services, or content.

This process is crucial for building and maintaining an email marketing list, a valuable tool for organizations to establish and nurture connections with their audience.

Various methods can be employed to collect email leads, such as utilizing web opt-in forms on websites and incorporating incentives like discounts or exclusive content. Web surveys, content or product upgrades, and online events like webinars or virtual summits can also capture email addresses during audience participation.

One of the significant challenges businesses face while setting up the collection of their email leads is the choice of technology. This choice can affect the speed at which organizations set up their campaign, the effectiveness of managing the email list, and the integration with their other existing platforms. This is where Appwrite, through Appwrite Functions and Mailgun — a powerful email service provider — comes in.

Appwrite provides ready-made function templates that allow businesses to set up applications easily. One of these templates is the email contact form. The email contact form template is designed to help gather email leads for marketing campaigns. It also includes a prebuilt contact form user interface that businesses can customize to meet their specific needs.

This tutorial demonstrates how you can set up the email leads collection system on your Next.js website using the email contact form provided by Appwrite and the Mailgun email service provider.

Prerequisites

To follow along comfortably with this tutorial, you’ll need a few things:

Basic web development knowledge and a basic understanding of Next.js.
An active Appwrite cloud account and a Mailgun account.
A code editor or Integrated Development Environment (IDE), preferably VScode.
Basic knowledge of Git, a GitHub account, and a repository on that account.
Node.js installed.
A CLI terminal.

Repository

In case you want to view the repository of the entire Next.js leads collection website, check out this link.

Configuring Mailgun

To initiate email communications through Mailgun, you must retrieve the Simple Mail Transfer Protocol (SMTP) keys that Appwrite requires for sending emails through Mailgun.

In this tutorial, you'll be using the sandbox environment. For instructions on using the live environment, refer to the detailed guidelines.

Retrieving the SMTP keys
To perform this task, go to your Mailgun account dashboard. Once there, locate and click on the Sending menu.

Next, select Overview.

Afterward, navigate to the SMTP section and click Select.

Once complete, you can retrieve the SMTP credentials from the section shown below.

Configuring Appwrite

To proceed with the configuration, navigate to your Appwrite Cloud account dashboard, create a new project by entering the desired project name, and click Create project, as indicated below.

After that, click on the Functions menu.

Next, click the templates tab to view the available templates.

In the search field, enter email contact form to search for the template.

Afterward, click Create function to initiate the setup.

Setting up the email contact form
This phase involves selecting a runtime environment, adding the credentials obtained from Mailgun, and setting up the GitHub repository.

Select Node.js - 16.0 as the runtime environment, then click Next.

After that, add the credentials obtained from Mailgun, as shown below.

The template sends the email leads to the email address provided in the SUBMIT_EMAIL field. Add your preferred email to the field, and then click Next.

When using Mailgun's sandbox environment, make sure the email address you provided in the SUBMIT_EMAIL field is authorized within Mailgun's system. For additional information, please visit this link. Also, note that emails sent using the sandbox environment are usually sent to the spam folder of the receiving email account.

Connecting and setting up your GitHub repository
At this point, you need to connect your GitHub repository to the platform. Appwrite pushes a copy of the template to your GitHub account, allowing you to personalize your version as required.

Click on the GitHub option as indicated below.

If your GitHub account is not yet connected to Appwrite, you will be redirected to GitHub to complete the connection process.

Afterward, choose the repository that was created as part of the prerequisite.

If you already have a GitHub account connected to your Appwrite cloud account, select the Add to existing repository option instead of Create a new repository and click Next.

Select the GitHub account and the repository of your choice, then click Next.

After that, select the branch you want to use and add the root directory as function/src, then click Create.

Your email contact form template is set to deploy automatically once a copy of the template's code is successfully pushed to your repository.

Next, navigate to your Appwrite cloud dashboard to confirm the function was deployed successfully.

Setting up your leads collection Next.js website

For this step, you'll create your Next.js leads collection page and integrate Appwrite into the project.

To get started, navigate to your terminal and run the following command:

npx create-next-app@latest leads_pages

This command prompts you to select other packages to be used by the project. Select the options as indicated in the screenshot below.

Once completed, run the command below to change the current working directory to the project's directory.

cd leads_pages

Next, install your project's Appwrite SDK dependency by running this command:

yarn add appwrite

Afterward, open the project on your code editor.

Adding your environment variables.
In the root directory of your project, create a file .env, then add the following:

NEXT_PUBLIC_APPWRITE_FUNCTION_ID=<function_id>
NEXT_PUBLIC_APPWRITE_BASE_URL=https://cloud.appwrite.io/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=<project_id>

You can retrieve your <function_id> and <project_id> Appwrite credentials from the Appwrite dashboard. Replace the <function_id> and <project_id> with the corresponding credentials.

Creating your leads collection custom hook
To promote reusability and modularity, you'll need to create the logic that handles collecting and sending the user's input to Appwrite.

To proceed, create a new folder, hooks in the src/ directory.
Next, create a file useLeadCollector.tsx, then add the following:

In the snippet above, there are two states, which include:

request state: This keeps track of the state of the asynchronous action when the collectLeads function is called.
form state: This stores the value coming from the user input.

The collectLeads function handles requests to the Appwrite Function specified by the process.env.NEXT_PUBLIC_APPWRITE_FUNCTION_ID and process.env.NEXT_PUBLIC_APPWRITE_FUNCTION_KEY. The email contact form function requires the request body to be sent using the content-type application/x-www-form-urlencoded. Additionally, be sure to set the referrer header for proper functionality.

Once the collectLeads function is called, the request state is toggled to loading, which changes the user interface to the loading interface. Next, the throwErrorIfNot200 function handles errors returned from the Appwrite Function. If the request is successful, then the request state will be set to completed; otherwise, it will be set to error. After a 5-second delay on error, the state will be toggled to idle.

Creating your page components
To build the leads page, you'll be creating various components. Here's a breakdown:

Header: This component houses the introductory content for the leads page.
About: Offers additional information to capture the lead's interest.
JoinSteps: Elaborates on the information discussed in the previous sections.
Footer: Provides hyperlinks to different application sections and includes copywriter information.
Form: An abstracted form interface for user interaction.
Contact: The crucial section for collecting leads.

To organize your project, navigate to the src/ directory and create a folder named components to store these page components.

Starting with the Header component, create a file Header.tsx in the components folder, then add the following code snippet.

Next, create the About component by repeating the steps above, create the About.tsx file, and add the following:

After that, create the Footer component by creating the Footer.tsx file and adding the following:

Moving on to the JoinSteps component, create the JoinSteps.tsx file and add the code snippet below.

Next, let's create the Form component. Start by creating a folder named partials within the components directory. Inside this partials folder, create a file Form.tsx. Copy and paste the following snippet into the Form.tsx file:

Last but not least is the Contact component. Create the Contact.tsx file and add the following:

In the provided snippet, the Form component is rendered based on the value of the request state. If the request state is idle, then the Form component is rendered. Similarly, other request states are handled likewise.

The use of "use client" signifies that the Contact component is client-side. This is necessary because, by default, Next.js sets all components to server-side.

Adding the components to the leads page
Once the components are created successfully, you’ll need to add them to the leads landing page.
To do so, open the page.tsx file in the src/app directory and add the following:

import About from "@/components/About";
import Contact from "@/components/Contact";
import Footer from "@/components/Footer";
import Header from "@/components/Header";
import JoinSteps from "@/components/JoinSteps";
export default function Home() {
  return (
    <main className="min-h-screen text-center px-24 py-10">
      <div className="max-w-[1000px] mx-auto pb-24 bg-white">
        <Header />
        <About />
        <JoinSteps />
        <Contact />
        <Footer />
      </div>
    </main>
 );
}

The above snippet renders the components for the user to interact with.

Testing your leads page
To display the page on the browser, navigate to your project's terminal and run the following:

yarn dev

This command sets up a local server environment from the project.

Extract the URL (http://localhost:3000) from your terminal and visit the page on your browser.

Here is a demonstration of the working system.

Conclusion

By combining the capabilities of Appwrite and Mailgun, you can quickly set up your email marketing leads collector, streamline lead collection, and ultimately launch more successful marketing campaigns. The user-friendly setup and detailed instructions make this tutorial accessible even for those with minimal JavaScript and Git knowledge.

Resources

How to automate Appwrite Functions deployment with GitHub

Obisike Treasure — Mon, 30 Oct 2023 16:21:55 +0000

Cloud functions are powerful tools for developing applications and reducing server costs. Appwrite Functions, a cloud function service offered by the backend-as-a-service platform Appwrite, offers the flexibility and efficiency for implementing serverless solutions effortlessly.

Appwrite functions must be deployed, but manual deployment can lead to insufficient version control, wasted time, inconsistent app environments, and exposure of secret environment variables, all of which can cause errors and security issues. Automating your deployments with GitHub can help avoid these problems.

In this tutorial, you'll learn the benefits of automating Appwrite function deployments and explore the step-by-step process of automating your Appwrite function deployments using GitHub without manually configuring environment variables.

Prerequisites

Before you dive into the automation process, you'll need to ensure you have the following prerequisites covered:

Basic knowledge of Node.js: You should have a foundational understanding of Node.js, which is commonly used for developing serverless functions.
An Appwrite cloud account: To use Appwrite functions, you need to have an active Appwrite cloud account. If you don't have one, sign up on the Appwrite website to get started.
A basic knowledge of Git and a GitHub account: You'll need a GitHub account to set up your repository. If you don't have one, sign up at GitHub.

The full project is in this repository.

Setting up Appwrite and GitHub repository

Get started by creating a GitHub repository using these instructions.

Next, you’ll need to create a project within the Appwrite Cloud console. If you just signed up, you’ll be immediately prompted to create a project.

If not, click on the Create a new Project, as indicated below:

Once you've finished this step, you'll be able to see the dashboard for your project.

Creating your Appwrite Function on Appwrite

Next, you’ll need to create your function on the Appwrite console. To continue, click the Functions menu on the navigation bar.

Afterward, click the Create function button indicated below.

Next, select the starter template you’d like to use. For this case, click Node.js.

Enter the name of your function and select Node.js - 18.0 as the runtime. Then, click Next.

In the next step, Appwrite gives you the option to use an existing API key or generate a new one. To continue with this tutorial, select the Generate API key on completion checkbox, then click Next.

Next, you can choose to use an existing repository or have Appwrite clone the template to a new one. Select Create a new repository, then click Next.

Once you've completed that step, you’ll need to connect your GitHub account to your Appwrite console. Click on the GitHub option as indicated below.

If you haven’t connected your GitHub account to Appwrite, you’ll be redirected to GitHub to do so.

Make sure to select the repository you initially created.

Once that’s done, enter the name of the new repository and click Next. This step specifies the name of the new repository Appwrite will create on your GitHub account.

Next, select your desired Git branch and enter the root directory of your function.

At this point, the function has been successfully created and deployed on your Appwrite cloud account. Subsequent deployments will be triggered when you push changes to the GitHub repository Appwrite created for you.

Adding your Appwrite Function code

Now that you've created the Appwrite Function, it's time to update the template in the GitHub repository generated by Appwrite on your GitHub account.

The GitHub repository created by Appwrite is usually a private repository. Therefore, it’s preferred that you use SSH to clone this repository. Check here to configure SSH on your GitHub account.

To continue, go to your GitHub repository created by Appwrite, and then follow these steps to clone your repository locally.

Once the repository is successfully cloned, open the projects folder with your code editor.

The main.js file is the entry point for the function, which means that this is where you should place your function code.

Open the main.js file and replace its contents with the following code.

import axios from "axios";
import cheerio from "cheerio";
async function getSEOInfo(url) {
  try {
    const response = await axios.get(url);
    const html = response.data;
    const $ = cheerio.load(html);
    const title = $("title").text();
    const headers = {};
    for (let i = 1; i <= 6; i++) {
      headers[`h${i}`] = $(`h${i}`).length;
    }
    const metaDescription = $("meta[name=description]").attr("content") || "";
    const metaKeywords = $("meta[name=keywords]").attr("content") || "";
    const images = $("img").length;
    const canonicalURL = $("link[rel=canonical]").attr("href") || "";
    const internalLinks = $('a[href^="/"]').length;
    const externalLinks = $('a[href^="http"]').length;
    return {
      title,
      headers,
      metaDescription,
      metaKeywords,
      images,
      canonicalURL,
      internalLinks,
      externalLinks,
    };
  } catch (error) {
    console.error("Error: ", error);
    return null;
  }
}
export default async ({ req, res, log, error }) => {
  if (req.method !== "GET") {
    return error("Request method not supported");
  }
  const info = await getSEOInfo(req.query.url);
  if (!info) return error("failed to get SEO information");
  log(info);
  return res.json(info);
};

The code above uses axios to fetch the content of a given URL and cheerio to extract the SEO information.

After that, run the following command to install the project’s package dependencies:

yarn add axios cheerio

Triggering and testing the deployment

Once you're finished developing your function locally, you can deploy it by committing your changes to Git and pushing them to the GitHub repository.

You’ll notice that a new deployment has been added to the list of deployments.

To test your deployment, click Execute now.

Next, add the parameters required by your function. In this case, you’re adding a query parameter url as indicated below.

Afterwards, click Execute.

Click on the execution to view more information about it.

Conclusion

Automating your Appwrite function deployments using this method is a great way to streamline your development and deployment workflows, free up valuable time, and improve efficiency while eliminating the need to add your Appwrite environment variables to GitHub.

Resources

How to add DigitalOceans Spaces adapter to an Appwrite instance

Obisike Treasure — Thu, 21 Sep 2023 14:59:37 +0000

The rapid development of the Internet has created an unprecedented need for better storage. The current state of web development makes it crucial for applications to utilize services such as user authentication, file storage, and data delivery. Fortunately, Appwrite offers a solution that includes these services, eliminating the need for complex server setup and management.

What is Appwrite?

Appwrite is an all-in-one solution offering backend services such as authentication, databases, and file storage. It's user-friendly and can be self-hosted or used as a cloud service.
To overcome storage limitations encountered when using a self-hosted Appwrite instance, Appwrite allows you to extend its storage service using several external storage services, such as DigitalOcean Spaces.

What is DigitalOcean Spaces?

DigitalOcean Spaces is an object storage service offered by DigitalOcean, a popular cloud infrastructure provider. Spaces allows you to store and serve large amounts of data, such as images, videos, and other files, in a scalable and cost-effective manner.
This resilient, secure, and cost-effective file storage solution can seamlessly connect with Appwrite via an adapter, enhancing the storage service offered by the Appwrite instance.

Benefits of extending Appwrite storage service with DigitalOcean Spaces

Adding the DigitalOcean's Spaces adapter to an Appwrite instance essentially extends Appwrite's storage service. This extension offers the following advantages.

Scalability and performance: As your application gains traction, the need for storage increases. DigitalOcean’s Spaces scales seamlessly, accommodating large data volumes. Merging it with Appwrite ensures smooth performance and efficient data handling.
Cost efficiency: Unlike conventional server-based storage, Spaces lets you pay solely for used storage, a budget-friendly choice to expand your Appwrite app minus unnecessary costs.
Backup and recovery made simple: With Spaces, crafting Appwrite backups is straightforward. Regular backups ensure that you're well-prepared for unforeseen data loss incidents.

Next, let's dive into extending your self-hosted Appwrite service with DigitalOcean’s Spaces by building a media-gallery application and adding the storage service.

Tutorial: Building a Nuxt.js media-gallery application

Here we’ll build a media gallery application using Nuxt.js, self-hosting Appwrite, extending Appwrite storage with DigitalOcean Spaces, and linking the storage to the application. The project repository can be found here. The application's functionalities will include:

Creating image galleries.
Storing and displaying created galleries.
Generating shareable links for the galleries.

Prerequisites

The following requirements apply:

Basic knowledge of JavaScript, Vue.js, and Nuxt.js.
Node.js and Yarn installed on your computer.
Docker installed for local hosting of Appwrite.
A DigitalOcean account to create and access Spaces. ## Setting up DigitalOcean Spaces

To set up your DigitalOcean Spaces, create a new Spaces bucket on DigitalOcean and extract the Spaces Bucket access credentials.

Creating a new Spaces Bucket

To get started, log into your DigitalOcean account.

Click Store static objects, which takes you to the section for creating Spaces.

Afterward, keep the default values for Choose a datacenter region and the content delivery network (CDN). Enter your preferred bucket name in the Choose a unique Spaces Bucket name section. For this tutorial, you’ll be using nuxt-gallery.

Usually, a Spaces Bucket is linked to a project. For this guide, you’ll use the default project created by Digital Ocean when you sign up successfully.

Next, click Create a Spaces Bucket.

Your Spaces bucket will be created and assigned an Origin Endpoint.

Next, you’ll need to enable anyone to access the content on your bucket. To do this, click on the Settings tab.

Then on the File Listing section, click Edit.

After that, select Enable File Listing.

Getting the Spaces Access Keys
Next, you’ll need to retrieve the following keys:

<bucket-name>
<access-key>
<access-secret>
<bucket-region>

The bucket URL can be found in the Origin Endpoint indicated below.

This bucket URL contains the <bucket-name> and the <bucket-region> in the form:

https://<bucket-name>.<bucket-region>.digitaloceanspaces.com

You can then extract these keys from the URL on your dashboard.

Next, the <access-key> can be obtained by navigating to API menu. Click on API.

After that, click on Spaces Key.

Then, in the Spaces Key section, click Generate New Token.

Enter the name of the key, for this case, nuxt-media-gallery.

Then click the button indicated below to generate the key.

After that, you’ll have the access keys and secret.

The Access Secret is located in the Secret row, and the Access Key is located in the nuxt-media-gallery row. Make a copy and save your Secret key because it will be lost if you leave the page.

Setting up Appwrite

To proceed, you‘ll need to locally host your Appwrite server. Let’s use Docker to accomplish this. Check out the installation guide to learn more about self-hosting Appwrite.

Locally hosting Appwrite with Docker
Ensure Docker is running by using the command below on your terminal to verify.

docker info

Create a directory named appwrite-spaces in the current working directory using the following:

mkdir appwrite-spaces 
cd appwrite-spaces

Then, download the Appwrite base docker-compose.yml and .env files into the created folder.

Open the .env file and update the keys' values as follows:

_APP_STORAGE_DEVICE=DOSpaces
_APP_STORAGE_DO_SPACES_BUCKET=<bucket-name>
_APP_STORAGE_DO_SPACES_REGION=<bucket-region>
_APP_STORAGE_DO_SPACES_SECRET=<access-secret>
_APP_STORAGE_DO_SPACES_ACCESS_KEY=<access-key>

Setting _APP_STORAGE_DEVICE from Local to DOSpaces indicates to Appwrite to use DigitalOcean Spaces instead of a locally implemented storage system.

Make sure you replace <bucket-name>, <bucket-region>, <access-secret>, and <access-key> (which are the keys obtained from the API section of the DigitalOcean dashboard).

Once that is done, execute this command within the appwrite-spaces directory:

docker compose up --remove-orphans -d

Using the --remove-orphans flag will remove containers unrelated to the present services before initiating the new ones.

After the services have been pulled by Docker from the Docker registry, the containers are then created.

After that, navigate to http://localhost to access your Appwrite instance.

Next, click Sign up to create a new account.

After signing up, enter your project’s name. For this case, use nuxt-media-gallery then click Create Project.

Creating the Appwrite storage for the project
To create the storage, Select Storage and click Create bucket.

After that, enter the name of the bucket. In this case, use nuxt-media-bucket, then click Create.

Following that, you must grant CREATE and READ permissions to any user on this storage bucket. To do so, click the Settings tab.

Then, navigate to the Permissions section, click Add a role to get started and select the Any option.

After that, select the CREATE and READ permissions.

Extracting your Appwrite credentials
To retrieve your credentials, you need to get the values for the following:

<appwrite-bucket-id>
<appwrite-project-id>
<appwrite-api-endpoint>

Navigate to Settings by clicking the Settings menu to obtain the <appwrite-project-id>.

After that, find the Project ID and API Endpoint as indicated below.

Next, to get the bucket ID, navigate to the Storage menu; there, you’ll see the bucket ID on the bucket as indicated below.

Setting up the Nuxt.js project

To set up the Nuxt.js project, open your terminal, and run the command below:

npx nuxi@latest init <project-name>

In this case, replace the <project-name> with nuxt-media-gallery. Then run the command below:

cd <project-name>

This changes the current working directory of the terminal to the project’s directory. Next, you’ll need to install all the dependencies.

The dependencies for this project include:

Appwrite SDK
Swiperjs (this will be used to perform the slide show)
TailwindCSS

To install, run the command:

yarn add appwrite swiper @nuxtjs/tailwindcss @vueuse/core

Follow the steps here to set up TailwindCSS for the project.
After that, create an assets folder in the root directory and add the folders and files according to this link.

Adding the environmental variable
To add these variables, create a .env file in the root directory of the project and add the following to the file:

NUXT_APPWRITE_API_ENDPOINT=<appwrite-api-endpoint>
NUXT_APPWRITE_BUCKET_ID=<appwrite-bucket-id>
NUXT_APPWRITE_PROJECT_ID=<appwrite-project-id>

Replace the <appwrite-api-endpoint>, <appwrite-bucket-id>, and <appwrite-project-id> values with the values you obtained from the Appwrite dashboard.

Creating the UI components and screens
To do so, first add the pages folder to the project's root directory. This is required for creating the application's routes/screens.

Next, navigate to the app.vue file and change the file's content to look like this:

<template>
  <div class="h-screen">
    <nuxt-page />
  </div>
</template>
<script lang="ts">
import "swiper/css";
</script>

Landing screen
Following that, create a screen to collect the user's name so that the media files can be saved and identified.

In the pages folder, create a file, index.vue, and add the following:

<template>
  <div class="x-container">
    <div class="x-card">
      <h1>Welcome to MShare</h1>
      <p>Please provide your name so we can setup your unique profile</p>
      <div class="mt-2">
        <input
          type="text"
          class="w-full"
          v-model="store.name"
          placeholder="Name: e.g. Obisike Treasure"
        />
      </div>
      <div class="mt-2">
        <input
          type="button"
          @click="navigateTo('/gallery')"
          :disabled="!!!store.name"
          class="w-full bg-orange-400 disabled:bg-orange-200 disabled:text-gray-600"
          value="Create"
        />
      </div>
    </div>
  </div>
</template>
<script setup lang="ts">
const store = useAppSession();
</script>

The vue template above consists of a card-like UI element with the heading "Welcome to MShare" and a paragraph prompting users to provide their name to create their gallery. Two input elements are present: one for the user's name and another for a "Create" button. The button is disabled until the user enters their name and then changes color. When users enter their name and click the button, the "create" method is triggered, allowing them to continue with the gallery creation.

Gallery screen

Following that, you need to add the route/screen for the users to upload their gallery. To do this, create a file gallery.vue in the pages directory, then add the following:

<template>
  <div class="h-screen p-[3rem]">
    <div class="x-card !max-w-full" v-if="store.previewKey"> 
      <h3> Sharable Link: 
        <span class="bg-slate-200 inline-block px-2"> {{ location?.origin }}/share/{{ store.previewKey }} </span>
      </h3>
    </div>
    <div class="x-card !max-w-full"> 
      <h1> Select your media file:</h1>
    </div>
    <div class="x-card !max-w-full"> 
      <div class="grid grid-cols-2 sm:grid-cols-4 gap-[2rem]">
        <transition-group appear name="fade"> 
          <div class="w-full aspect-square x-border" v-for="(img, idx) in images" :key="img.idx"> 
            <div class="w-full h-full relative">
              <img :src="img.url" class="w-full h-full object-cover" />
              <div class="absolute inset-0 backdrop:bg-slate-500">
                <button class="bg-white rounded-md m-3 px-3" @click="removeImage(idx)">Remove</button>
              </div>
            </div>
          </div>
        </transition-group>
        <div class="w-full aspect-square"> 
          <label class="x-input__file w-full h-full"> 
            <svg xmlns="http://www.w3.org/2000/svg" height="48" viewBox="0 -960 960 960" width="48"><path d="M450-450H200v-60h250v-250h60v250h250v60H510v250h-60v-250Z"/></svg>
            <p> Add Image</p>
            <input
              type="file"
              ref="imageField"
              @change="setImages"
              name="images"
              multiple
              class="hidden"
              accept="image/*"
            />
          </label>
        </div>
      </div>
    </div>
    <div class="x-card !max-w-full"> 
      <button 
        class="bg-orange-300 disabled:bg-orange-100 w-full py-[1rem]" 
        @click="submit" 
        :disabled="!images?.length"
      >{{ loading ? 'Uploading...': 'Upload' }}</button>
    </div>
  </div>
</template>

The template above consists of a container with multiple cards and grids. The first card displays a sharable link if the store.reviewKey data exists. The second and third cards show static content. The fourth card contains a grid with images that can be added or removed using a Remove button. Users can upload multiple images using a hidden file input, and an Upload button is disabled until images are selected.

<script setup lang="ts">
import { ID } from "appwrite";
import { IFileImage } from "utils";
const config = useRuntimeConfig();
const store = useAppSession();
const loading = ref<boolean>()
const location = ref<Location>();
const images = ref<IFileImage[]>([]);
onMounted(() => {
  location.value = window.location
})
function removeImage(idx: number) {
  images.value.splice(idx, 1);
}
async function setImages(e: any) {
  const files = (e.target as HTMLInputElement).files || [];
  const fileImages = await Promise.all(
    Array.from(files).map(async (file, idx) => ({
      url: await convertToURL(file), 
      file, 
      idx
    })),
  );
  images.value.push(...fileImages);
}

async function submit() {
  try {
    loading.value = true
    await Promise.all(images.value.map((img, idx) => {
      return pushToAppwrite(img.file, idx)
    }))
    store.value.previewKey = generateKey(images.value.length - 1);
    alert("Successfully published!")

  } finally {
    loading.value = false
  }
}


async function pushToAppwrite(file: File, idx: number) {
  const storage = appwriteStorage();
  await storage.createFile(
    config.public.appwriteBucketId, 
    ID.custom(generateKey(idx)),
    file
  );
}
</script>

In the provided script, the pushToAppwrite() function connects to Appwrite using credentials and uploads a given file object. A unique key is generated using generateKey() for future file retrieval.
The setImages() function extracts images from the file input and creates a base64 URL with convertToURL(). This URL is then used to render the file blob as an image URL in a grid block.
The submit() function uploads images using setImages() to the images state. It also generates a previewKey for creating a shareable URL. To retrieve files with the shareable ID, the file ID has to be in this format:

<name>-<timestamp>-<length-of-array-of-images>

Share screen

Next, create the screen for the shareable link. Begin by creating a folder, share, within the pages directory. Inside the share folder, create a file called [pid].vue.
As per Nuxt guidelines, the route path is /share/[pid].

Then, append the specified content to the [pid].vue file.

<template>
  <div class="py-[10%] px-[15%] w-full h-screen">
    {{ route.params }}
    <div class="flex flex-col w-full h-full">
      <div class="x-card !max-w-full"> 
        <h3> Obisike's Slideshows </h3>
      </div>
      <div class="pb-20"> 
        <swiper
          :effect="'cards'"
          :grabCursor="true"
          :autoplay="{
            delay: 2500,
            disableOnInteraction: true,
          }"
          :modules="modules"
        >
          <template v-for="(img, idx) in images" :key="idx">
            <swiper-slide class="h-[20rem]">
              <div class="w-full">
                <img :src="img" class="w-full object-cover" loading="lazy" />
              </div>
            </swiper-slide>
          </template>
        </swiper>
      </div>
    </div>
  </div>
</template>
<style scoped>
.swiper-cards{
  overflow:visible;
  height: 50%;
}
.swiper-cards .swiper-slide {
  transform-origin:center bottom;
  -webkit-backface-visibility:hidden;
  backface-visibility:hidden;
  overflow:hidden;
}
</style>

The template creates a slideshow using the Swiper library. It arranges images in a card-style layout, with a title given by the name of the gallery’s creator together with SlideShow, above the slideshow. The images transition using a cards effect and autoplay every 2.5 seconds. The template ensures responsiveness and lazy loading for images.

<script setup lang="ts">
import { Swiper, SwiperSlide } from "swiper/vue";
import { EffectCards, Autoplay } from "swiper/modules";
const modules = [Autoplay, EffectCards];
const config = useRuntimeConfig();
const route = useRoute();
const images = ref<string[]>([]);
onMounted(() => {
  getImages()
})
async function getImages() {
  const storage = appwriteStorage();
  const keys = getFileIdsFromPreviewKey(route.params.pid as string);
  if (!keys) return;
  keys.forEach(k => {
    const url = storage.getFileView(config.public.appwriteBucketId, k)
    images.value.push(url.toString())
  })
}
</script>

To break it down, in the script above, when the component loads, a function is triggered to fetch images, and then the getImage() function gets the image from Appwrite using the route parameter pid.

Additional modules, Autoplay and EffectCards, are applied to the Swiper component to enhance the slideshow with a card-stacking effect.

Next, you’ll need to add the utility functions.

Adding the utilities functions

To add utility functions, create a folder utils and a file index.ts within the utils folder. Then copy the contents of this file and paste them into the index.ts file.
The functions in this file is automatically imported due to Nuxt.js.

One of the notable functions you copied is the appwriteStorage() function.

export function appwriteStorage() {
  const config = useRuntimeConfig();
  const client = new Client();
  const storage = new Storage(client);
  client
      .setEndpoint(config.public.appwriteAPIEndpoint)
      .setProject(config.public.appwriteProjectId);
  return storage
}

This function obtains the environment variable via useRuntimeConfig(), establishes a connection to Appwrite Storage service, and returns the storage object, which contains methods for retrieving and uploading files to appwrite.

Application demo

To showcase your application, start by accessing your terminal within the project directory, then execute the following command:

yarn dev

Once the command is successfully executed, the Nuxt.js development server will start on the port 3000.

Visit http://localhost:3000 on the browser to preview the screens.

Next, enter your desired name then click Create.

After that, click Add Image, to add the images.

Then click Upload to upload the selected images.
Once that is done, a shareable link will be generated. Copy and open this link in a different browser window.

Here is a video showcasing the application:

https://www.loom.com/share/0aac3ddd749748ad915b0f438837c6f6?sid=1daab281-7f22-40d4-ba9d-04cc45251084

To prove that the files are uploaded to Digital Oceans directly, here is a screenshot showing the file on Digital Oceans’ spaces.

Conclusion

In this tutorial, we've learned how to extend Appwrite's storage capabilities using DigitalOcean Spaces. By combining the strengths of these two services, developers can create robust applications with secure and scalable storage solutions.

Resources

How to create a Docker Swarm of Appwrite and Swarmpit containers

Obisike Treasure — Fri, 07 Jul 2023 07:33:52 +0000

The demand for efficient and scalable infrastructure management has never been greater in today's dynamic software development landscape. Some of the best tools for this landscape are Docker Swarm, Appwrite, and Swarmpit, which provide high flexibility and performance.

By leveraging the capabilities of these technologies, organizations can achieve increased scalability, reliability, and productivity in their application deployment and management processes. These technologies facilitate seamless containerization, faster development with pre-built services, and easier cluster administration.

In this tutorial, you'll learn how to deploy your Appwrite containers using Docker Swarm and manage the containers using Swarmpit.

Prerequisites

To get the most out of this tutorial, ensure you have the following:

Basic knowledge of Docker
An ARM-based personal computer, such as the M1 MacBook
Terminal

Set up the virtual machine servers

First, you’ll be setting up two virtual machines, Manager and Worker, which will act as the servers for our swarm. To proceed, do the following:

Download and Install the UTM virtualizer from the official website
Download the Ubuntu server 22.04.2 LTS for ARM from their official website

After that, follow the instructions in this documentation to install the Ubuntu server on the virtual machines.

During the Ubuntu server installation, you will have the opportunity to install Docker and OpenSSH. It is recommended that you select both of these options during the installation process.

Once you have completed the installation, you can verify the installation of Docker and OpenSSH. To check the Docker version, run the following command in the terminal:

docker -v

If Docker fails to install during the Ubuntu installation, you can refer to the documentation for installation instructions.

For OpenSSH, you can check the SSH service status by executing the command below:

systemctl status sshd.service

Once you've completed that, execute the following command to install Git:

sudo apt install git

Set up the network file system (NFS) mount

The NFS mount enables the sharing of a directory. As the service needs to be deployed across multiple nodes, it is crucial to share certain resources, such as volumes, across all nodes.

Accessing the nodes via SSH
To ensure smooth server access, start by retrieving the IP address for the servers using the following command:

ip addr | grep “inet 192”

You'll need to repeat the steps to retrieve the IP addresses for both the manager and worker nodes.

Once you have obtained both the manager and worker IP addresses, follow these instructions to SSH into the servers from the virtual machine host computer.

Open two terminal sessions on the virtual machine host computer; in the first terminal, execute the following command to connect to the manager server:

ssh manager@<manager_ip>

For the second terminal, run the command:

ssh worker@<worker_ip>

This connects to the worker server.
Replace both <manager_ip> and <worker_ip> with their corresponding IP addresses.

Setting up the NFS
Next, you can follow these steps to set up the NFS shared directory on the manager's SSH terminal.
First, install the NFS server package on the host by executing the command:

sudo apt install nfs-kernel-server

After installing the NFS server package, you need to create the shared directory on the host using the following command:

sudo mkdir ./nfs/app -p

To ensure security, NFS converts any root actions performed on the worker (client) to the nobody:nogroup credentials. To align the directory ownership with these credentials, you need to execute the following command on the manager node terminal:

sudo chown nobody:nogroup ./nfs/app

Afterward, open the /etc/exports file on the host machine with root privileges:

sudo nano /etc/exports

Within the /etc/exports file, create a configuration line for each directory you want to share. Replace with the actual IP address of the worker node. For example:

/home/manager/nfs/app    <worker_ip>(rw,sync,no_subtree_check)

In this configuration line, the rw option grants read and write access to the client, sync ensures changes are written to disk before replying, and no_subtree_check disables subtree checking to prevent issues when files are renamed while open on the client.

Save and close the /etc/exports file.
Finally, restart the NFS server to make the shares available:

sudo systemctl restart nfs-kernel-server

If you have a firewall, you must adjust the settings to allow the worker node to access the files.

After that, you have to mount this directory on the worker node. To do this, Firstly, install the nfs-common on the worker node using the command:

sudo apt install nfs-common

Then create mount the directory using the following commands:

sudo mkdir -p /nfs/app
sudo mount <manager_ip>:/home/manager/nfs/app /nfs/app

Replace <manager_ip> with the actual manager IP. Once that is done, you can run this command to check that the NFS shared directory has been mounted.

df -h

Setting up the swarm

Docker Swarm provides a native clustering and orchestration solution for Docker, enabling efficient distribution and scalability of services across multiple nodes.

To initiate Docker Swarm on the manager node, execute the following command:

sudo docker swarm init --advertise-addr <manager_ip>

By running this command specifically on the manager node, Docker Swarm is activated, and a join token is generated. This token allows for creating and managing a swarm of Docker worker nodes, empowering you to scale and distribute services seamlessly.

Copy the command and run it on the worker node to join the worker node to the swarm.

Once this is successful, you can check whether the node has been added to the swarm on the manager node by running the command:

sudo docker node ls

Creating and deploying the Appwrite services on the swarm

To do this, you’ll be using the docker stack command. This command allows you to set up multiple Docker services via the compose file. It uses the YAML file to set up its services.
First, you must download the appwrite docker-compose.yml from the Appwrite’s documentation and modify its content to be swarm-compatible.

After downloading the file, you can open it using any text editor you prefer.

Preparing the Appwrite swarm file
To proceed, use the shared directories as volumes, as Docker Swarm does not typically share volumes between nodes. Using the previously created NFS directory, you can easily share directories between nodes.

To make it happen, you must take the following steps:

On your manager node, run the following commands.

cd ./nfs/app

This step is crucial because the compose file relies on specific files from this repository. Afterwards, you can create the necessary volume directories by executing the following command:

mkdir -p ./appwrite/{mariadb,redis,cache,uploads,certificates,functions,influxdb,config,builds,app,src,dev,docs,tests,public,appwrite}

After creating the volume directories, proceed to update the volumes in the downloaded compose file by deleting the volume specifications in the file.

Next, replace the volume specification of each service with their corresponding shared directory volume as indicated in the table below:

Old	New
appwrite-config:/storage/config:ro	./appwrite/config:/storage/config:ro
appwrite-certificates:/storage/certificates:ro	./appwrite/certificates:/storage/certificates:ro
appwrite-uploads:/storage/uploads:rw	./appwrite/uploads:/storage/uploads:rw
appwrite-cache:/storage/cache:rw	./appwrite/cache:/storage/cache:rw
appwrite-certificates:/storage/certificates:rw	./appwrite/certificates:/storage/certificates:rw
appwrite-functions:/storage/functions:rw	./appwrite/functions:/storage/functions:rw

Next, to optimize request handling and resource allocation in a Docker Swarm cluster, restrict the Traefik service to the manager node. Restricting this centralizes routing and load balancing, avoiding conflicts and simplifying management.

Add the following configuration below the Traefik service's port specification to enforce this restriction.

deploy:
      replicas: 1
      placement:
        constraints:
          - "node.role==manager"

The deploy option specifies that only one replica be created, and the service be deployed on the manager node.

Afterward, it is necessary to include the environment variables. Typically, you need to specify the values for each service's environment variable individually. However, in this case, you can simplify the process by using an environment file containing all the required services' secrets. Simply add this file to each service requiring environment variables by adding the following specification.

env_file:
      - .env.appwrite

Next, eliminate any unnecessary specifications in the file to ensure Swarm compatibility. Remove specifications such as x-logging and container-name, as they are incompatible with Swarm. Additionally, remove all occurrences of <<: *x-logging from the compose file.

The docker-compose file should now look like this

Creating the swarm file on the manager node
Once completed, you must copy the compose file to the manager node for deployment. To accomplish this, follow these steps.

First, on the manager node, run the command:

sudo nano /home/manager/nfs/app/appwrite.swarm.yml

Then copy the already modified file content from your text editor and paste it into the manager node’s nano editor interface.

Save the file.

Next, run the following command.

sudo nano /home/manager/nfs/app/.env.appwrite

After doing so, add this content.

Once you have completed all the previous steps, execute the following command on the manager's node to deploy the services:

sudo docker stack deploy -c /home/manager/nfs/app/appwrite.swarm.yml

This command initiates deploying the services.

The deployment takes a while, as the docker stack command pulls the images from the Docker Hub before running the containers.

To list all services, execute:

sudo docker service ls

For more detailed information about a specific service, use:

sudo docker service ps —no-trunc <SERVICE_NAME>

These commands provide valuable insights into the status and details of the services running within the Docker Swarm cluster.

Once the services are up and running, open the web browser on the virtual machine’s host computer and visit http://<manager_ip> to preview the Appwrite app.

Create and deploy the Swarmpit Services on the Swarm

Once Appwrite has been successfully deployed, you can then proceed to set up the Swarmpit on the swarm.

To deploy Swarmpit, run the following command on the manager node:

sudo git clone https://github.com/swarmpit/swarmpit -b master && \
sudo docker stack deploy -c swarmpit/docker-compose.arm.yml swarmpit

Once the swarmpit services have been deployed, navigate to the VM’s host browser, then visit http://192.168.64.12:888.

Managing the swarm with swarmpit

To proceed, create your first admin account on Swarmpit by entering your username and password, then click Create Admin.

After creating your account, the browser will take you to the dashboard where you can manage the deployed services.

Conclusion

Docker Swarm and Swarmpit provide numerous benefits when serving Appwrite. These tools enable rapid and efficient infrastructure setup and management. Swarmpit distinguishes itself by offering a user-friendly graphical interface in addition to swarm management capabilities.
Furthermore, you can gain numerous advantages for your Appwrite applications by leveraging the power of Docker Swarm and Swarmpit. Scalability, high availability, simplified updates, service discovery, load balancing, and centralized control are just a few examples.

Resources

You may find the following resources useful:

Custom OTP input component with VueJS

Obisike Treasure — Mon, 13 Jun 2022 21:25:59 +0000

Sometimes we may not be able to find the components we require to build our projects on the NPM package manager, and sometimes we may find one that does not work either on production or even during development.
Here is when an expertise on building your very own component comes into play.
In the very short tutorial, I would be going through how to build your very own custom VueJS OTP input component with ease.

Requirement

VS Code editor

To build this, we would first have to set up our project. In this tutorial, i would be using

npx -p @vue/cli vue create my-otp-project

to set up the vue project, selecting vue 2 as my preferred option.

After the project has been setup correctly, we then access the folder of our already initialized project with our vscode editor.

We locate the App.vue file and open it. Remove the content of the <div id="app">, that is were the OTPcomponent would be added.

Then we create a new component file with the name OTPInput.vue. this is were our code is going to be in.

src/components/OTPInput.vue

<template>
  <div>
    <!-- Vue template code here -->
  </div>
</template>
<script>
export default {
  // Vue script here
}
</script>
<style>
  /* Otp css here */
</style>

Moving to the template section of the component, we add the snippet below.

<div class="flex flex-row justify-between">
   <input
      :style="style"
      v-model="inputs[idx]"
      :class="inputClass"
      @keyup="inputFocus"
      @focus="check($event)"
      @change="handleChange(idx, $event)"
      v-for="(inp, idx) in inputCount"
      :key="idx"
      :tabindex="idx"
      maxlength="1"
      autocomplete="off"
    />
</div>

For those who are familia with tailwind css, the flex flex-row justify-between would be a familia concept but to those who are not familia with it, you need not to worry because these classes would be added to our <style> section of the component manually.
Normally, OTPs' are a group of inputs field which their collective values are regarded as one and takes on one input per input field, so we try to implement this feature by

using a v-for to generate multiple input fields.
setting maxlength input attribute to 1 to prevent more than one character per field
setting autocomplete input attribute to off to prevent auto-completion which is not a feature of the OTP input
creating event handlers like @keyup, @focus, @change.

The we move to the script section of the component. As we had done before, we add the snippet below to the <script> section

export default {
  props: {
    inputCount: {
      type: Number,
      default: 4,
    },
    inputClass: String,
    dimension: {
      type: String,
      default: "30px",
    },
    value: [String, Number, Object],
  },
  data() { /* state properties */ }
  computed: { /* computed properties */ }
  watch: { /* watched properties */ }
  methods: { /* methods properties */ }
}

The props that this component would accept are inputCount which refers to the number of OTP input fields, inputClass which are extra styling for the fields, the dimension i.e the size of each input field and the value which is the literal value held by the OTP

export default {
  ...
  computed: {
    style() {
      return `
        width: ${this.dimension}; 
        height: ${this.dimension}; 
        text-align: center;
      `;
    },
  },
  data() { /* state properties */ }
  watch: { /* watched properties */ }
  methods: { /* methods properties */ }
}

The computed property handles generating style for the dimensions, which is directly added to the input.

export default {
  ...
  data() {
    return {
      inputs: Array(this.inputCount),
      currentKey: 0,
    };
  },
  watch: { /* watched properties */ }
  methods: { /* methods properties */ }
}

the data property contains the state of this component. It holds and Array with length of the inputCount added by via the props and the currentKey which is the current position of the cursor on the fields.

export default {
  ...
  watch: {
    value() {
      this.inputs = this.value.split("");
    },
  },
  methods: { /* methods properties */ }
}

We watch the value props for any changes externally so the component can be updated too.

export default {
  ...
  methods: {
    handleChange(key, event) {
      this.inputs[key] = event.target.value;
    },

    getChildren(event) {
      return event.target.parentElement.children;
    },

    check(event) {
      const inputs = this.getChildren(event);

      if (inputs[this.currentKey]){
        inputs[this.currentKey].focus();
      }
    },

    inputFocus(event) {
      const data = this.inputs.join("");
      const inputs = this.getChildren(event);

      this.$emit("input", data);
      if (data.length === this.inputCount) {
        this.$emit("completed", data);
      }

      if (event.key === "Delete" || event.key === "Backspace") {
        this.currentKey--;
        if (this.currentKey <= 0) {
          this.currentKey = 0;
        }
        if (inputs[this.currentKey]) {
          inputs[this.currentKey].focus();
        }
      } else {
        this.currentKey++;
        if (this.currentKey >= this.inputCount) {
          this.currentKey = this.inputCount;
        }
        if (inputs[this.currentKey]) {
          inputs[this.currentKey].focus();
        }
      }
    },
  },
}

The methods used includes:

handleChange: This is the handler for the onchange event on the input component. On change, the value of the input field is stored in the this.inputs state at the specified position key.
getChildren: This method gets the NodeList of input fields form the event parameter.
check: This is the onfocus event handler. It calls the .focus() method on the input field specified using the this.currentKey content. Since the current key holds the current position of the cursor, it is easier to just use it the know which input to focus on.
It also prevents focusing on non-existing input fields too.
inputFocus: This is the handler for the onkeyup event. The OTP input are supposed to move to the next input field immediately after the character has been entered. So with this handler we make it happen.
In this handler we emit the data of the total OTP input by joining them and using the this.$emit("input", data); feature of vue components.
Here we also handle the oncompleted feature of the OTP input i.e we emit back to the parent component that the inputs has been completely filled so that the next action can be carried out.
We also handle the deleting of value from the field. This is the most delicate part of the OTP input since the delete feature requires the backwards movement of the cursor.
As indicated in the snippet above, the this.currentKey which hold the current position of the cursor on the input is reduced to handle for the backwards movement during delete.

Here is the full OTP Input component code snippet

<template>
  <div class="flex flex-row justify-between">
    <input
      :style="style"
      v-model="inputs[idx]"
      :class="inputClass"
      @keyup="inputFocus"
      @focus="check($event)"
      @change="handleChange(idx, $event)"
      v-for="(inp, idx) in inputCount"
      :key="idx"
      :tabindex="idx"
      maxlength="1"
      autocomplete="off"
    />
  </div>
</template>
<script>
export default {
  props: {
    inputCount: {
      type: Number,
      default: 4,
    },
    inputClass: String,
    dimension: {
      type: String,
      default: "30px",
    },
    value: [String, Number, Object],
  },
  computed: {
    style() {
      return `
        width: ${this.dimension}; 
        height: ${this.dimension}; 
        text-align: center;
      `;
    },
  },
  data() {
    return {
      inputs: Array(this.inputCount),
      currentKey: 0,
    };
  },
  watch: {
    value() {
      this.inputs = this.value.split("");
    },
  },
  methods: {
    handleChange(key, event) {
      this.inputs[key] = event.target.value;
    },

    getChildren(event) {
      return event.target.parentElement.children;
    },

    check(event) {
      const inputs = this.getChildren(event);

      if (inputs[this.currentKey]){
        inputs[this.currentKey].focus();
      }
    },

    inputFocus(event) {
      const data = this.inputs.join("");
      const inputs = this.getChildren(event);

      this.$emit("input", data);
      if (data.length === this.inputCount) {
        this.$emit("completed", data);
      }

      if (event.key === "Delete" || event.key === "Backspace") {
        this.currentKey--;
        if (this.currentKey <= 0) {
          this.currentKey = 0;
        }
        if (inputs[this.currentKey]) {
          inputs[this.currentKey].focus();
        }
      } else {
        this.currentKey++;
        if (this.currentKey >= this.inputCount) {
          this.currentKey = this.inputCount;
        }
        if (inputs[this.currentKey]) {
          inputs[this.currentKey].focus();
        }
      }
    },
  },
}
</script>
<style>
  /* Otp css here */
</style>

After all that, We add the OTP Input component to our App.vue file to test.

Here is the final result

Bugs
For most of it, it does what an otp input should do, but it still has some few bugs.

After reaching the last input field, the delete feature works differently.
if two keys are entered at the same time, it skips a field

If you have any fix for these or you discover more bugs you can put it down in the comment section or raise an issue in the github repository

Github: https://github.com/Otrex/vue-otp-input.git