Finding the Perfect CMS

Every CMS is useful. All of them exist because they have a target audience that is willing to pay, since it provides them value.

After years of searching, I created a set of rules that define the "Perfect CMS" for static sites.

1. Own my data. Don't store my content, and don't become a dependency for my projects.

2. Extendable. Allow me to add custom components. Ideally open-sourced too, for ease of learning.

3. Framework agnostic. Don't tell me to use Angular. Integrate with any framework, and without a framework.

4. Free. Don't limit the amount of projects, clients, or features. Don't rely on paid users to keep the product alive.

5. Self-hostable. Don't require Cloud for authentication. Don't vendor lock-in access to CMS.

On top of those points, CMS must be simple to use, quick to implement, and nice-looking. Those all make it easier to convince clients they need a CMS.

Choose Wisely, Choose Git-based CMS

Own my data. Don't store my content, and don't become a dependency for my project.

The biggest difference between Git-based CMS and API-based CMS is complexity. Complexity can be beneficial to large blog platforms or e-commerce platforms, but that is not a typical project of freelancers. Much more common is a landing page, personal website, or community platform.

Simple websites don't benefit from API-based CMS, and get all the downsides. One must use an SDK, or send raw HTTP requests to fetch the data. One must implement caching to make their application quick again. And most importantly, one must have fallback behavior if CMS ever goes into downtime.

Git-based CMS solves all the pain points above. All data is stored in a file defined by you, whether it's JSON, YAML, TOML, or Markdown. Data is always accessible during the build step, so importing it directly gives you access with code auto-completion, and no delays when rendering the website. Data is stored directly as part of your source code, and doesn't create any direct link with the CMS that is used to edit them.

A significant downside of using Git-based CMS is the speed at which changes are reflected. Since a re-build is required after each change, it can take a couple of seconds (or up to a few minutes, depending on which framework you use) to apply changes on production. This can be a bit frustrating, but a typical freelancer's client doesn't mind. If one would honestly need changes instantly reflected on a website, they are at size when they benefit from API-based CMS anyway.

Thankfully, there are many Git-based CMS such as Decap CMS, TinaCMS, or Crafter CMS.

Component Library is Not Enough

Extendable. Allow me to add custom components. Ideally open-sourced too, for ease of learning.

Basic components are enough for the first iteration of your CMS. As client's business grows, so do their demands. Coloring data based on importance, or adding map picker to visually represent location, may sooner or later become highly important for CMS users efficiency.

When that happens, your CMS should provide you with docs on how to extend it, instead of asking you to submit a feature request. Relying on maintainers is the worst outcome when it comes to custom components in CMS.

Many providers such as Directus, Appsmith, or Budibase all have ways to fully customize the viewing and editing experience of each field.

CMS Doesn't Live in My Application

Framework agnostic. Don't tell me to use Angular. Integrate with any framework, and without a framework.

You likely experienced this before. You find an amazing UI library, you decide to use it in your next project, and moments later you realize it only supports Next.js. You find an amazing PDF library to generate great-looking invoices, only to realize it's for PHP. You find ...

Next.js and PHP are great. But it's my decision if they are great for the project I work on. If CMS provided support only for a specific framework, either you can't use it for every project you build, or you throw yourself into a framework you may not be familiar with, or even worse, it may not be the right choice for the job. CMS is there to assist you, not to throw logs under your feet.

Payload, a CMS powered by Next.js, or Sveltia CMS, a Decap CMS alternative using Svelte, are examples of CMS that I recommend to avoid until they become framework agnostic.

Save Money to Make Money

Free. Don't limit the amount of projects, clients, or features. Don't rely on paid users to keep the product alive.

Limits and free tiers are foundation stones of every commercial platform. It may remain open sourced, or a version 2.0 may be released with cloud-only support. It could remain free for unlimited projects, or it could change the limit to 3 projects over the weekend. It's also a matter of trust whether a Cloud doesn't change pricing from $5 per month to $15.

When picking a preferred CMS for simple sites, it should not limit the amount of projects, collaborators, fields, or rows. Allowing pricing to affect you eventually creates expenses, which lower your income from long-term clients.

Sanity, Contentful, and Hygraph are a few examples. Very often a CMS has a pricing page, but is also open-source, and has docs on how to self-host it for free. A great example of that is Directus, and there is no need to avoid those CMS.

Authentication, a Bait for Headless CMS

Self-hostable. Don't require Cloud for authentication. Don't vendor lock-in access to CMS.

Git-based CMS often provide Cloud authentication to simplify process of setting it up. This is perfect for development, and initial integration to ensure everything works well together. As soon as application goes to production, it's a great risk to keep using the Cloud offering.

Primary problem is the fact you are authorizing someone's else GitHub application, not yours. This means maintainers of the Cloud offering of the CMS can see contents of your repository, do changes, and possibly even more. This creates potential for security risks, makes app less likely to comply with strict privacy regulations, and can create helpless situation during authentication gateway downtimes. Such Cloud authentication can also sunset at any moment.

Honorable Mention: Outstatic

Until now, my favourite CMS was Outstatic, a CMS for Next.js applications. It's fully open source project that can be self-hosted, and focuses on keeping your data inside your git repository. It's simple-looking interface is amazing for any small CMS, and AI integration for text generation can be a great plus for some projects.

Downside of Outstatic is limited collaboration features, since it doesn't come with database, so only authentication method is GitHub OAuth. This can be limiting, as explaining to clients what GitHub is and why they need the account can be hard. Additionally, it's SDKs tightly couple you to use Next.js.

Why Pages CMS is the Best CMS

Considering all of the above, the best CMS is Pages CMS, a modern Git-based CMS with a focus on static sites. With a single configuration file, in matter of minutes, it allows you to manage your content and its media files through an intuitive UI. Pages CMS support all collaboration features you or your client might need including MagicURL login, history of changes, and more. It comes with a responsive design to let your client do changes from their phone.

Pages CMS keeps all your contents inside your repository, and only requires a single configuration file to be set up. What's even more, it's framework agnostic and can be used with Astro, Next.js, SvelteKit, or any other framework. Because of the nature of Pages CMS, it doesn't integrate with a framework, and only looks at files containing your data such as JSON, YAML, Markdown, or TOML.

It supports 9 file formats and 13 built-in field types. While this is more than enough, Pages CMS can be forked, self-hosted, and extended with custom components. Doing this requires basic understanding of React, but detailed documentation and existing field types serve as great starting points.

The entirety of Pages CMS is free and open sourced, including its Cloud platform. Cloud offering has no limits on the amount of collaborators, projects, or content. Developers of Pages CMS even announced Free forever as part of their 1.0 release notes.

Let's Integrate with Pages CMS

As with any CMS I come across, I try to use it with an application. This time I decided to use Astrolink, a minimal alternative to Linktree. You can check it out on a demo page, or see it's details in Astro theme catalog.

Prepare the Website

Initial observation shows Astrolink already sources all of the page data from a single file src/data/user.json. This means, Pages CMS will only need access to this file, and I don't need to make any adjustments to source code.

If you want to use Pages CMS with your project, and you have your data inside components or JavaScript/TypeScript files, I highly recommend moving data to JSON files first. Many frameworks have ability to import JSON files directly into components. Those that don't can store JSON files in public assets folder, and be loaded with a fetch() request.

Getting Astrolink live was matter of a few very simple steps:

1. Fork GitHub repository

2. Deploy website to Cloud (Vercel, Netlify, or others)

3. Connect custom domain using DNS

Once deployed, it was time to configure Pages CMS.

Connect with Pages CMS

To get started with Pages CMS, I visited their Cloud platform, and signed in with GitHub. Through this process I authorized with Pages CMS OAuth application, and gave their GitHub application access to my repositories, including read and write access.

Pages CMS can be self-hosted very easily, and they have a step-by-step guide on how to do that. I highly recommend self-hosting Pages CMS and authorizing your own GitHub application for security and privacy reasons.

Once my GitHub was connected, I saw my newly forked Astrolink repository in the list of Pages CMS projects.

The project was not ready to be used yet, because Pages CMS needs a .pages.yml configuration file that will hold all the Pages CMS configuration. Frankly, I didn't need to know that. A nice-looking error page explained it all, and provided a button to create an empty configuration file to continue.

Afterwards, I spent a couple of minutes reading Pages CMS documentation, more specifically Configuration and Examples pages.

While fields in YAML file were not any standard knowledge developers usually have, it was very easy to understand. I am nowhere near knowing the exact schema by heart, but I already feel confident setting up a configuration file for any kind of data thanks to its highlighting, and schema validation directly in Pages CMS.

Below you can find configuration file I used for the Astrolink project:

content:
  - name: user
    label: User
    path: src/data/user.json
    type: file
    fields:
      - name: name
        type: string
      - name: profession
        type: string
  - name: links
    label: Links
    path: src/data/user.json
    type: file
    fields:
      - name: links
        type: object
        list: true
        fields:
         - name: title
           type: string
         - name: description
           type: string
         - name: icon
           description: Icon names can be found at www.remixicon.com
           type: string
         - name: url
           type: string
           pattern: ^(https?:\/\/)?(www\.)?[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(\/[^\s]*)?$

As I saved the configuration file, new options appeared in the left side menu. Inside, I found my schema applied in a simple interface of inputs and buttons. What's even more interesting, all data was already loaded, indicating the connection to data stored in src/data/user.json was successful.

I updated a few texts, and saved the changes. A commit was created automatically, pushed, and a Vercel deployment started. After couple of seconds, I refreshed my website and changes I made were live.

Collaboration with Client

Since the main purpose of CMS is to provide the client with a simple interface to update content on their static site, I decided to try the full experience with Pages CMS.

In collaboration settings, I added a friend of mine to the project through email invitation. They received the invitation in their inbox, and followed steps provided. An amazing feature presented itself when I noticed the sign-in page supports passwordless email login alongside GitHub OAuth. I can't stress enough how important this is since clients almost never have GitHub accounts.

After a passwordless login using Magic URL, my friend already saw the Astrolink project in their list, and started editing content. No setup was needed from his side.

Finally, yet another feature amazed me. When my friend started making changes, I saw it all on the right side of Pages CMS, which served as a history of changes. If a client ever does a change that breaks the website, as a developer I can easily see what the change was, when, and within a few clicks I can rollback the changes to make the website stable again. Moments like this make business relations more stable and lucrative.

Both website and CMS are now live! Within less than hour of finding out about Pages CMS, I was able to deploy my first site with CMS integrated. You can visit my Astrolink website, and I invite you to make yours to try out Pages CMS. Additionally, I recommend you to make picture URL on the website configurable, to gain further experience with Pages CMS. For those looking for challenge, Pages CMS supports media, so you can switch from picture URL to proper drag&drop file input.

Pages CMS in Production

As mentioned above, Pages CMS requires read and write access to your repository, which can be scary for multiple reasons:

• Security: Pages CMS Cloud has full access to your repository, possibly deleting the entire project.

• Privacy: Pages CMS Cloud has permission to see the source code of your application.

• Billing: Pages CMS Cloud can become paid. They promised it won't, but it can.

While self-hosting doesn't fully address security, it surely makes it more secure. Bugs in code can still cause problems, but the risk is much more manageable.

Setting up self-hosted Pages CMS looks like complex task since it has many moving parts, but their docs are amazing and provide follow-along instructions to set everything up. The entire setup was made with developers in mind, as it recommends Resend and Turso, both Cloud applications that provide free tiers.

What caught me by surprise was how easy it is to add custom components. From my past experience building CMS for clients, I know simple component changes can make a big difference. For example, simply coloring a date red or green depending on package shipping status can avoid delayed deliveries. Not only was the process of adding custom components documented, it also linked to over a dozen existing components providing a starting point.

If you are interested to gain confidence with custom components, I recommend to build component that stores latitude and longitude of location on a map, and provide interface using Google Maps, OpenStreetMap, or similar map provider.

If you use Pages CMS in production, and successfully self-hosted the application, it's the best time to consider sponsoring Pages CMS. Engineers behind this amazing open-source project are active, and providing them with financial support allows them to develop new features, which can benefit you in the long run.

Conclusion

I am finally at peace. No more searching for a better CMS. Pages CMS is my go-to, if I ever need one for sites I build. It provides a nice-looking and simple interface that's quick and easy to setup. It's free, open-source, self-hostable, framework-agnostic, and doesn't lack collaboration features. What more should I ask for.

If you don't share my passion for Pages CMS, take inspiration from my criteria for the perfect CMS. Many of them make sense in every situation, and help you find a solution that is long-term, and sustainable. If it wasn't clear already, every static site deserves a CMS.

🙌 Team Details

• Matej Bačo - @_meldiron

🎶 Oh, it's just me, myself and I 🎶

ℹ️ Description of Project

Auth UI is a fully customizable login flow for your applications. Using Auth UI gives you a ready-made UI for all key features of the Authorization Server. Thanks to the adapter approach, you can connect Auth UI to any backend of your choice, such as Appwrite.

When a user needs to authenticate, your application redirects the user to Auth UI, where the user can pick one of many options to sign in. Not only that, users can also sign up, recover passwords or even manage their accounts.

When using Auth UI, you don't need to make any application-level changes. You can simply add one redirect to Auth UI page, and we will handle the rest. Your applications will also benefit from any improvements we make to Auth UI without the need for you to change your code.

Auth UI was made to take place in your existing applications with ease. With configurable redirect URLs, you can set up and integrate Auth UI within a few minutes.

Auth UI page is configurable and lets you design it, decide on the domain name, and select which sign-in methods are allowed. By customizing brand color, company logo, and even border roundness, you can make the authentication page look and feel almost exactly the same as the rest of your application.

Sadly, Auth UI is not a one-stop shop. Some applications need more complex auth flow or even fully customizable authentication pages. If that's your case, you might be better off implementing everything on your own. Auth UI was created to simplify the creation of web apps and take care of the most repetitive pages.

And that's not all! The future of Auth UI is bright and includes some exciting features such as new providers, new sign-in methods, and more.

🧰 Tech Stack

Technologies:

• Appwrite | Backend taking care of Authentication, Databases, and File Storage 🗃️

• Svelte Kit | Rendering framework to help with SSR, SEO, and routing 🤖

• Svelte | JavaScript framework to make the website dynamic and quick ⚡

• TypeScript | Programming language to keep website strongly typed and stable for production

• Pink Design | UI framework making websites look nice by default ✨

Production:

• Appwrite Cloud | Hosted solution of Appwrite

• Vercel | Website hosting provider

💢 Challenges I Faced

Like every (good) developer, I was finding lazy ways to do stuff, not the good ones 😅 Since I needed the ability to edit an existing page, I added an extra section when creating a page called Master Password. Here, a developer would enter his password, which will later be necessary later, to delete or edit their Auth UI page. Only when I was done with the implementation I noticed passwords were saved unhashed, unprotected, and this whole idea was not the proudest moment of my creativity 🤦

A solution to this was actually pretty crazy. I needed authentication pages for Auth UI, so I thought hmmmm, why not use Auth UI for that? 🤔 Now authentication into Auth UI is powered by Auth UI itself. Eat your own dog food! 😄

Thankfully the rest of the journey was pretty straightforward. I am yet to face production on fire, bugs in the core of the application, and database migrations deleting all the pages 🤪 Let's see where future takes Auth UI 😇

🔗 Public Code Repo

GitHub: meldiron/authui

⚡ Demo Link

Live Demo: authui.site

What’s even more amazing is that we recently became number 1! 🥳 Long-awaited 1.0 release brings amazing features to make web and app development even more FUN. One of them being a new query syntax that brings numerous possibilities, but first, let’s understand what it means to query.

🔍 What Is a Query?

The database is a critical part of any application. It’s a place where all the information generated by users is stored. Storing data is important but only useful if you can read the data. In the end, who would use an app where they can create a profile but never look at it? 🤔

It’s as simple as that! Querying is the process of reading the data of your application. Queries can be as simple as “Give me all you got”, but can also get robust with many conditions, sorting operations, or pagination.

Let’s see a query in action! For this example, I will use SQL (Structured Query Language), which lets us read data from a database by writing a human-like sentence.

Let’s start with a simple query to get all JavaScript frameworks in the world:

SELECT * FROM frameworks;

This query could serve all of our needs but would get extremely slow as our database starts to grow. Let’s improve the query by filtering the results and only get popular frameworks:

SELECT * FROM frameworks WHERE popularity > 0.9;

We might still be getting thousands of results, but we never show that on the website, right? Let’s only get the first 10 results:

SELECT * FROM frameworks WHERE popularity > 0.9 LIMIT 10;

Finally, let’s make sure to show the most popular frameworks first:

SELECT * FROM frameworks WHERE popularity > 0.9 ORDER BY popularity DESC LIMIT 10;

We just built a basic query! 💪 Let’s now take this knowledge and build some queries that we can use to read data from Appwrite Database.

🖋️ Appwrite Query Syntax

Let's start by taking a look at filter queries. These queries are meant to reduce the amount of results by checking if a condition is met regarding each document. Appwrite supports many filter queries that let you compare against a word, text, number or booleans. Following is a table of all available filter queries and an example of how such a query could look like in SQL world to make understanding easier:

Next you can take advantage of sort queries that lets you order results of a query in a specific way. You can see this feature on all eshops that let you sort products by popularity, price or reviews. Following queries are available in Appwrite:

Last but not least, you can write pagination queries. There are different ways of paginating over your database that you can learn more in our Database Paginations article. In short, we could do offset pagination using limit and offset queries, or cursor pagination using limit and cursor. All of that is possible in Appwrite using following queries:

🧰 Querying Any Appwrite Service

If you used Appwrite before, you might have noticed that all of the above features were already available, just in a different syntax. So… Why the change?

✨ Consistency ✨

These features were only available in some services! 😦 Our mission was to implement queries into all list methods (where it makes sense), but that would be pain for you to learn, and pain for us to maintain. Thanks to Queries syntax Appwrite now offers a consistent interface to query any resource in an exactly the same way. Let’s see it in action!

import { Client, Databases, Query } from 'appwrite';
const client = new Client();
client
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1')
    .setProject('PROJECT_ID]');
const database = new Databases(client);

// Get products from eshop database that are published and cost below 50$. Ordered by price to get most expensive first on third page, getting 10 items per page
const productsList = await database.listDocuments('eshop', 'products', [
    Query.equal("published", true),
    Query.lessThan("price", 49.99),
    Query.limit(10),
    Query.offset(20),
    Query.orderDesc("price")
]);

// Get up to 50 disabled collections in eshop database
const collectionsList = await database.listCollections('eshop', [
    Query.equal("enabled", false),
    Query.limit(50)
]);

// Get database by name
const databasesList = await database.list([
    Query.equal("name", 'eshop'),
    Query.limit(1)
]);

Let’s see a few more examples with different services 😇

const storage = new Storage(client);

// Get all JPEG or PNG files ordered by file size
const filesList = await storage.listFiles('productPhotos', [
    Query.equal("mimeType", [ "image/jpeg", "image/png" ]),
    Query.orderAsc("sizeActual")
]);

const functions = new Functions(client);

// Get failed executions that were triggered by http request and lasted at least 5 seconds
const executionsList = await functions.listExecutions('createOrder', [
    Query.equal("status", "failed"),
    Query.equal("trigger", "http"),
    Query.greaterThanEqual("time", 5) // in seconds
]);

const teams = new Teams(client);

// Get 5th biggest team that has at least 100 members
const teamsList = await teams.list([
    Query.greaterThan("total", 100),
    Query.orderDesc("total"),
    Query.limit(1),
    Query.offset(5)
]);

const users = new Users(client);

// Find all Johns that verified their email address
const usersList = await users.list([
    Query.equal("emailVerification", true),
    Query.search("name", "John")
]);

As you can see, possibilities are limitless! 🤯 What’s more, the new syntax opens doors for new exciting features such as join, specific selects, subqueries, and new operators. We will continue working and making the Appwrite database more flexible and closer to the under the hood database being used, whether it’s MySQL, MariaDB, or in the future, MongoDB.

👨‍🎓 Conclusion

New Appwrite queries syntax introduced in 1.0 brings long-awaited consistency across all Appwrite services. This not only eases a learning curve of Appwrite, but also introduces new possibilities to allow you to create even more amazing applications!

📚 Learn more

You can use the following resources to learn more and get help:

• 🚀 Appwrite Github
• 📜 Appwrite Docs
• 💬 Discord Community

👁️ Fair analytics tool

Offen’s main product is web analytics, which is quite unique if you ask me. The analytics tool is a core requirement of any commercial website out there, as it provides many KPIs to define marketing success. Not only that, analytics can help you target your services to the right clients, increasing your overall income.

There are many (even self-hosted) analytics tools, but Offen is unique enough to beat them all in my eyes. While others focused on collecting valuable information and storing them lawfully, Offen’s core value is to create visitor-friendly analytics. At your first interaction with Offen, you will notice it only allows first-party cookies, which is a great example of how they focus on visitor security in exchange for making setup a bit more complex. Once you set it up, you notice a second important feature, you can’t really see visitors in your dashboard yet. Offen is opt-in only, which means, you don’t track visitor until he clicks ‘Allow’. Offen also comes with a dashboard for visitors to see what exact information you have about them, with an option to opt-out or delete all data with 1 click.

Alongside these product-defining features, you can see functionality that can easily compare with industry-leading competitors:

• Customizable consent banner
• Comply with GDPR
• End-to-end encryption
• Much more!

I am yet to use Offen analytics tool on a real project, but since day one I learned about it, I have been recommending it as a Plausible and Google Analytics alternative.

🧰 Developer tooling

Alongside the amazing analytics project Offen has to provide, their GitHub organization includes many different tools such as schemaify, analyticstxt or l10nify. The one tool I like the most is docker-volume-backup.

Nowadays many self-hosted projects provide Docker support to ensure simple setup, upgrade, deployment and maintenance. Docker also often solves the legendary quote ‘It works on my machine’. Once you start using Docker on production (which you can and should), you will notice there is no backup&restore mechanism available by default.

Offen provides a Docker image that you can run alongside your Docker application to back up anything you might need. Under the hood, the Offen container mounts to the exact same volumes your application does, and backups files depending on your configuration.

What’s cool is Offen’s Docker Volume Backup can be as simple or as complex as your project needs. On my server, I started with a simple backup.sh script, but gradually improved it to a more mature solution with many features Offen has to provide:

• Recurring backups (daily/weekly/monthly)
• Upload backups to the cloud
• Mirrored backups to multiple storage providers
• Maintenance mode during backup to ensure data integrity
• Alerts about failed backups
• Backup encryption
• Backup rotation to remove old ones

With such advanced backup in place, all worries about data loss have been taken from my shoulder. I am so confident with Offen’s backup tool I have been recommending it to the Appwrite community to properly backup their Appwrite instance!

☢️ Open-source Software (OSS) Is Hard

Since Appwrite is open-source, we understand the challenges that OSS projects face. If you fall in love ❤️ with an open-source project (like we have), consider checking out ways to contribute. Most OSS projects happily accept contributions in their own way, whether they be in the form of commits, bug 🐛 reports, advocacy, or even monetary 💰 support. If you love Offen, consider joining us as a sponsor. Or, if you're interested in contributing to Appwrite, check out our contribution guide.

🔗 Learn more about Appwrite

Check out Appwrite as the backend for your next Web, Flutter, or Server application. Here are some handy links for more information:

• Appwrite Contribution Guide
• Appwrite Discord
• Appwrite Github
• Appwrite Documentation

Let's build a project!

In this article, we will build Almost Casino, a web application that allows you to sign in and play coin flip with virtual currency called Almost Dollar.

As you can see, not the brightest idea... The point of the project is not to build a 1B$ company in a weekend, instead, to showcase how we can achieve server-side rendering with Appwrite backend.

🖼️ Pics, pics, pics!

Let's see what we are going to build 😎

A single page that shows the ID of the currently logged-in user, his current balance, and a coin flip game. When playing coin flip, you can configure a bet and pick which side of the coin you would like to bet on. For the sick of simplicity, there will be no coin-flipping animation. Do you know what that means? 👀 YOU can add the cool-looking animation!

📃 Requirements

We will be using multiple technologies in this demo application, and having a basic understanding of them will be extremely helpful.

Regarding the JavaScript framework, we will be using a simple and fun framework Svelte. To allow routing and introduce better folder structure as well as the possibility of SSG and SSR, we are going to use Svelte Kit.

To give our application some cool styles, we will use TailwindCSS, a CSS library for rapid designing.

Instead of writing our own backend from scratch, we will be using backend-as-a-service Appwrite to build and deploy server logic easily.

Last but not least, we will use Vercel as our static.

🛠️ Create Svekte Kit Project

The whole Almost Casino application is open-sourced and can be found in GitHub repository. The app is also live on the app.almost-casino.matejbaco.eu.

For those who follow along, let's create a new Svelte Kit project:

$ npm init svelte almost-casino

✔ Which Svelte app template? › Skeleton project
✔ Add type checking? › TypeScript
✔ Add ESLint for code linting? … No / Yes
✔ Add Prettier for code formatting? … No / Yes
✔ Add Playwright for browser testing? … No / Yes

Next, let's enter our new project and run the development server:

$ cd almost-casino
$ npm install
$ npm run dev

We now have the Svelte Kit web application running and listening on localhost:3000 🥳

Let's make sure to follow Tailwind installation instructions to install it into our newly created Svelte Kit project.

Appwrite backend setup

If you don't have the Appwrite server running yet, please follow Appwrite installation instructions.

Once the server is ready, let's create an account and a project with the custom ID almostCasino. Next, we go into the Database section and create a collection with ID profiles. In the setting of this collection, we set collection-level permission with read access to role:member, and write access empty. Finally, we add the float attribute balance and mark it as required.

🤖 Appwrite Service

Let's start by creating a .env file and putting information about our Appwrite project in there:

VITE_APPWRITE_ENDPOINT=http://localhost/v1
VITE_APPWRITE_PROJECT_ID=almostCasino

Before coding the application, let's create a class that will serve as an interface for all communication with our Appwrite backend. Here we will have methods for authentication, managing profile, and playing the coin flip game. Let's create new file src/lib/appwrite.ts with all of the methods:

import { Appwrite, type RealtimeResponseEvent, type Models } from 'appwrite';

const appwrite = new Appwrite();
appwrite
  .setEndpoint(import.meta.env.VITE_APPWRITE_ENDPOINT)
  .setProject(import.meta.env.VITE_APPWRITE_PROJECT_ID);

export type Profile = {
  balance: number;
} & Models.Document;

export class AppwriteService {
  // SSR related
  public static setSSR(cookieStr: string) {
    const authCookies: any = {};
    authCookies[`a_session_${import.meta.env.VITE_APPWRITE_PROJECT_ID}`] = cookieStr;
    appwrite.headers['X-Fallback-Cookies'] = JSON.stringify(authCookies);
  }

  // Authentication-related
  public static async createAccount() {
    return await appwrite.account.createAnonymousSession();
  }

  public static async getAccount() {
    return await appwrite.account.get();
  }

  public static async signOut() {
    return await appwrite.account.deleteSession('current');
  }

  // Profile-related
  public static async getProfile(userId: string): Promise<Profile> {
    const response = await appwrite.functions.createExecution('createProfile', undefined, false);
    if (response.statusCode !== 200) { throw new Error(response.stderr); }

    return JSON.parse(response.response).profile;
  }

  public static async subscribeProfile(userId: string, callback: (payload: RealtimeResponseEvent<Profile>) => void) {
    appwrite.subscribe(`collections.profiles.documents.${userId}`, callback);
  }

  // Game-related
  public static async bet(betPrice: number, betSide: 'tails' | 'heads'): Promise<boolean> {
    const response = await appwrite.functions.createExecution('placeBet', JSON.stringify({
      betPrice,
      betSide
    }), false);

    if (response.statusCode !== 200) { throw new Error(response.stderr); }

    return JSON.parse(response.response).didWin;
  }
}

With this in place, we have everything ready to have proper communication between our Svelte Kit application and our Appwrite backend 💪

You can notice we execute some functions in this class, for instance, createProfile or placeBet. We use Appwrite Functions for these actions to keep them secure and not allow clients to make direct changes to their money balance. You can find the source code of these functions in GitHub repository.

🔐 Authentication Page

We start by creating a button to create an account. Since we are going to be using anonymous accounts, we don't need to ask visitor for any information:

<button
  on:click={onRegister}
  class="flex items-center justify-center space-x-3 bg-brand-600 hover:bg-brand-500 text-white rounded-none px-10 py-3"
  >
    {#if registering}
      <span>...</span>
    {/if}
    <span>Create Anonymous Account</span>
</button>

All of this goes into src/routes/index.svelte.

Next let's add method that runs when we click the button, as well as registering variable indicating loading status:

<script lang="ts">
  let registering = false;
  async function onRegister() {
    if (registering) { return; }
    registering = true;

    try {
      await AppwriteService.createAccount();
      await goto('/casino');
    } catch (err: any) {
      alert(err.message ? err.message : err);
    } finally {
      registering = false;
    }
  }
</script>

Finally, let's add a logic to redirect user to /casino route if we can see he is already logged in. This will allow visitors getting to / to be automatically redirected to casino if they are already logged in:

<script context="module" lang="ts">
  import { browser } from '$app/env';
  import { goto } from '$app/navigation';
  import { Alert } from '$lib/alert';
  import { AppwriteService, type Profile } from '$lib/appwrite';
  import Loading from '$lib/Loading.svelte';

  export async function load(request: any) {
    try {
      const account = await AppwriteService.getAccount();
      const profile = await AppwriteService.getProfile(account.$id);

      return { status: 302, redirect: '/casino' };
    } catch (_err: any) { }

    return {};
  }
</script>

That concludes our authentication page 😅 If you are feeling advantageous, feel free to add some cool styles around it.

🎲 Game Page

Let's make a file src/routes/casino.svelte to register our new route. In this file, let's start by writing a logic of loading the data. In there let's load user's account information, as well as profile:

<script context="module" lang="ts">
  import { browser } from '$app/env';
  import { goto } from '$app/navigation';
  import { Alert } from '$lib/alert';
  import { AppwriteService, type Profile } from '$lib/appwrite';
  import Loading from '$lib/Loading.svelte';

  export async function load(request: any) {
    try {
      const account = await AppwriteService.getAccount();
      const profile = await AppwriteService.getProfile(account.$id);

      return { props: { account, profile } };
    } catch (err: any) {
      console.error(err);

      if (browser) {
        return { status: 302, redirect: '/' };
      }
    }

    return {};
  }
</script>

By getting a profile, it is automatically created if not present already. That will automatically give us a balance of 500 almost dollars.

These information can now be received in a JavaScript variable:

<script lang="ts">
    import type { Models, RealtimeResponseEvent } from 'appwrite';

    // Data from module
    export let account: Models.User<any> | undefined;
    export let profile: Profile | undefined;
</script>

You can ignore types import for now. They will come into play later. Just make sure to keep it there 😛

Next, let's show our account information. For sick of simplicity, we will only show the ID of the account:

<p class="mb-8 text-lg text-brand-700">
  There we go, account created! Don't believe? This is your ID:
  <b class="font-bold">{account?.$id}</b>
</p>

Let's also prepare a button for user to sign out:

<button
  on:click={onSignOut}
  class="flex items-center justify-center space-x-3 border-brand-600 border-2 hover:border-brand-500 hover:text-brand-500 text-brand-600 rounded-none px-10 py-3"
  >
    {#if signingOut}
      <span>...</span>
    {/if}
    <span>Sign Out</span>
</button>

Next let's show user's fake dollars balance:

<h2 class="text-2xl font-bold text-brand-900 mb-8 mt-8">Balance</h2>
<p class="mb-3 text-lg text-brand-700">Your current blalance is:</p>
<p class="mb-8 text-3xl font-bold text-brand-900">
  {profile?.balance}
  <span class="text-brand-900 opacity-25">Almost Dollars</span>
</p>

Lastly, let's add section for betting:

<input
  bind:value={bet}
  class="bg-brand-50 p-4 border-2 border-brand-600 placeholder-brand-600 placeholder-opacity-50 text-brand-600"
  type="number"
  placeholder="Enter amount to bet"
/>

<button
  on:click={onBet('heads')}
  class="flex items-center justify-center space-x-3 border-2 border-brand-600 hover:border-brand-500 bg-brand-600 hover:bg-brand-500 text-white rounded-none px-10 py-3"
>
  {#if betting}
    <span>...</span>
  {/if}
  <span>Heads!</span>
</button>

<button
  on:click={onBet('tails')}
  class="flex items-center justify-center space-x-3 border-2 border-brand-600 hover:border-brand-500 bg-brand-600 hover:bg-brand-500 text-white rounded-none px-10 py-3"
>
  {#if betting}
    <span>...</span>
  {/if}
  <span>Tails!</span>
</button>

With all of that, HTML part of our casino page is ready! Let's start adding the logic by first adding method for signing out:

let signingOut = false;
async function onSignOut() {
  if (signingOut) { return; }
  signingOut = true;

  try {
    await AppwriteService.signOut();
    await goto('/');
  } catch (err: any) {
    alert(err.message ? err.message : err);
  } finally {
    signingOut = true;
  }
}

Next let's add a logic for our betting section, to allow submitting our coin flip bet:

let bet: number;
let betting = false;
function onBet(side: 'heads' | 'tails') {
  return async () => {
    if (!profile || !account || betting) { return; }
    betting = true;

    try {
      const didWin = await AppwriteService.bet(bet, side);
      if (didWin) {
        alert(`You won ${bet} Almost Dollars.`);
      } else {
        alert(`You lost ${bet} Almost Dollars.`);
      }
    } catch (err: any) {
      alert(err.message ? err.message : err);
    } finally {
      betting = false;
    }
  };
}

Let's finish off by adding a real-time subscription to our profile. This will automatically update the balance displayed on the website as soon as it changes on the backend:

$: {
  if (profile && browser) {
    AppwriteService.subscribeProfile(profile.$id, onProfileChange);
  }
}

function onProfileChange(response: RealtimeResponseEvent<Profile>) {
  profile = response.payload;
}

We have just finished the casino page! And.. I think... 🤔

That makes our Almost Casino complete!!! Let's now look at the main topic of this application, 🌟 SSR 🌟.

⚡ Server Side Rendering

Let's do the magic! 🧙

We start by creating src/hooks.ts file. In there, we intercept each request and get Appwrite authorization headers. We also return it in order to later retrieve it as part of our session object:

import * as cookie from 'cookie';

export function getSession(event: any) {
    const cookieStr = event.request.headers.get("cookie");
    const cookies = cookie.parse(cookieStr || '');
    const authCookie = cookies[`a_session_${import.meta.env.VITE_APPWRITE_PROJECT_ID.toLowerCase()}_legacy`];

    return {
        authCookie
    }
}

For this to work, make sure to install 'cookie' library with npm install cookie.

Next, at the beginning of every load() function (one in src/routes/index.svelte, one in src/routes/casino.svelte), let's add these two lines to extract our authentication headers from the session, and apply then to Appwrite SDK:

// Using SSR auth cookies (from hook.ts)
if (request.session.authCookie) {
  AppwriteService.setSSR(request.session.authCookie);
}

With this in place, SSR will now work properly! 😇 You might not see it yet due to cookies following same-domain policy, but we will address that in the deployment section.

🚀 Deployment

Since we will deploy to Vercel, let's make sure we use the correct adapter. We start by installing the adapter:

npm i @sveltejs/adapter-vercel

Next, let's update our svelte.config.js to use our new adapter:

import adapter from '@sveltejs/adapter-vercel'; // This was 'adapter-auto' previously, we just need to rename to 'adapter-vercel`

// ...

const config = {
  // ...
  kit: {
    adapter: adapter({
      edge: false,
      external: [],
      split: false
    })
  }
};

// ...

This makes our app ready for Vercel! 😎 Let's make a Git repository out of our project, sign in to Vercel and deploy the app. There is no need for any special configuration.

Once the application is deployed, make sure to put both Appwrite and Vercel applications on the same domain in order for SSR to work with authentication cookies.

If your application runs on the root of the domain, for instance, mycasino.com, then your Appwrite could be on any subdomain like api.mycasino.com.

If you plan to host your application on a subdomain, make sure to host it under the subdomain on which Appwrite runs. For instance, you could have Appwrite on domain mycasino.myorg.com and Vercel application on domain app.mycasino.myorg.com.

👨‍🎓 Conclusion

We successfully built a project that confirms Appwrite plays well with all technologies out there. I am really happy I got this article out as there were many requests from the Appwrite community regarding SSR, and now I have a place to point them to, even with code examples 😇

This demo application can also serve as an example for building the same SSR logic with other frameworks such as Angular, Vue, or React. They all follow a really similar structure regarding SSR, and it all comes down to extracting cookies from requests and setting them on Appwrite SDK.

🔗 Useful Links

If you are bookmarking this article, here are some highly valuable links for you to keep an eye on:

• Almost Casino: GitHub repository
• Almost Casino: Live Demo
• Appwrite: Homepage
• Appwrite: Discord server (for any support)
• Svelte Kit: Docs

One of the core functionalities of Appwrite is Appwrite Storage. It allows you to upload, view, download, and query your project files. Appwrite Storage not only takes care of encryption, compression and antivirus scans, it’s also built on top of Appwrite’s flexible yet simple permission system. Appwrite lets you store any files such as text documents, icons, images, videos and more.

🚀 What is new in Appwrite 0.13

The Appwrite 0.13 release offers a much more powerful Storage service! You can now group your files into Storage Buckets for better organization, as well as better control over allowed size and extension. On each bucket, you can also specify a different set of permissions, and toggle additional features such as encryption and compression.

Additionally, you can now upload files with no size limitation. In this release, chunked upload is supported and you can split your file into 5MB chunks to gradually upload a file as large as your bucket settings allow. Don’t worry, chunk upload logic is part of our SDKs and if it sees a file larger than 5MB, chunk upload will automatically kick in. One more secret! Our SDKs now accept an onProgress callback that will be triggered each time a new chunk is successfully processed. Implementing progress bars have never been easier 💪

Finally, Appwrite Storage is no longer limited by the size of your hard drive! With Appwrite 0.13, you can now connect the Storage service with cloud storage providers such as DigitalOcean Spaces or Amazon S3. With the introduction of these adapters, you no longer need to worry about running out of space, or hitting bandwidth limits due to Appwrite Storage. More providers are coming soon, so stay tuned 😎 In this guide, we’ll take a look at setting up Appwrite Storage using DigitalOcean Spaces as the storage adapter.

🌊 DigitalOcean Spaces setup

Before we jump into Appwrite, let’s prepare your DigitalOcean Space. After logging into DigitalOcean:

1. Click the green Create button in the upper right corner and select Spaces from the dropdown.
2. You will be redirected to the Create Space page, where we need to configure your file storage. Region and CDN configuration are up to you, but in the File listing section, you need to pick Restrict File Listing. This keeps our files secured from the internet, and only communication between servers will be allowed.
3. Before we finish the setup, provide your space with a unique name. Quick tip, this name will only be stored in the .env file of your Appwrite instance, and users will never see it. That means, the name can be as simple or as complex as you want.

After creating the space, you will be presented with a space endpoint. Make sure to note this URL down, you will need it later when connecting Appwrite to DigitalOcean.

Last but not least, you need to get a set of access keys to allow Appwrite to read and write from your newly created space. To do that, visit the API page from the navigation on the left, and under the Spaces access keys section we click on Generate New Key. Give the key a name (no worries, this name is only visible to you), and click on the blue tick icon to finish the key creation process. You will be presented with two keys. The one that is on the same line as your key name is called Access key, and the one below is Secret key. Please note both of them down, but be aware, the secret key is a really sensitive piece of information and DigitalOcean won’t show it to you in future.

That’s it! You have successfully set up our DigitalOcean Space, and have all the required credentials in your hands. Let’s look at how easy it is to connect Appwrite to our newly created space.

🧰 Connecting Appwrite to DigitalOcean Spaces

Before you start, make sure that you have the Appwrite instance up and running. Installation of Appwrite is as simple as running one 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:latest

To learn more about the installation process, you can check out our installation guide.

Once our Appwrite instance is up and running, we can configure the storage adapter. To do that, let’s enter the .env file and locate _APP_STORAGE_DEVICE. Currently, it’s set to Local, but since we want to use DigitalOcean Spaces, we change it to DOSpaces. With the new storage provider, we are now required to add new variables:

_APP_STORAGE_DEVICE=DOSpaces
_APP_STORAGE_DO_SPACES_BUCKET=YOUT_BUCKET
_APP_STORAGE_DO_SPACES_REGION=YOUR_REGION
_APP_STORAGE_DO_SPACES_SECRET=YOUR_ACCESS_SECRET
_APP_STORAGE_DO_SPACES_ACCESS_KEY=YOUR_ACCESS_KEY

Where do you get this information from? 😨 I have a neat trick for you! First of all, you can already fill in access and secret keys, these are the ones you got from earlier steps when creating API key on DigitalOcean. To get the bucket and region, you need to take a look at the space endpoint that we got after creating the DigitalOcean Space. For instance, my endpoint was:

https://project-x-bucket.fra1.digitaloceanspaces.com

There is a simple trick that is pretty easy to follow to get our bucket name and region. From my URL, the bucket name is project-x-bucket, and the region is fra1. Follow the same logic to extract information from your endpoint.

Once you have all of these environment variables configured, save the file and restart appwrite using docker-compose up -d. Did you notice that Docker is smart enough to only restart containers that use variables you just changed? 🤯

Once the Appwrite instance is restarted, create a new account and a new project. In the left menu, select ‘Storage’ and create a new bucket. Finally, upload a file into our bucket.

You can see the file was successfully uploaded, and can start using Appwrite just like usual! To confirm you are actually talking to DigitalOcean Spaces, visit your storage and you'll see the file in there.

Congrats! You successfully connected Appwrite to DigitalOcean Spaces 🥳 If you plan to use files directly from your Space, there are a few things to keep in mind:

1. Every file is compressed using GZIP compression before storing it in your Space. You will need to decompress the file after download if you plan to use it.
2. By default, encryption is enabled on newly created buckets in Appwrite Storage. This means you won’t be able to view the file without decrypting it first. I recommend you disable encryption if you plan on downloading the files from your Space.
3. All compression, encryption and antivirus are skipped for files above 20MB. These files are stored in your Space as plain files.

👨‍🎓 Conclusion

The worst nightmare for every project is bad scalability of their application. Thanks to the newly released provider system for Appwrite Storage service, you can now connect Appwrite with external storage providers instead of storing the files on your system. This prevents hitting a hard drive and bandwidth limits, as well as lets you use your favorite provider alongside Appwrite. And as you have seen in the tutorial above, you can easily connect Appwrite with DigitalOcean Spaces in just a few steps!

If you have a project to share, need help or simply want to become a part of the Appwrite community, I would love for you to join our official Appwrite Discord server. I can’t wait to see what you build!

📚 Learn more

You can use the following resources to learn more and get help:

• 🚀 Appwrite Github
• 📜 Appwrite Docs
• 💬 Discord Community

One of the core functionalities of Appwrite is Appwrite Storage. It allows you to upload, view, download, and query your project files. Appwrite Storage not only takes care of encryption, compression and antivirus scans, it’s also built on top of Appwrite’s flexible, yet simple permission system. Appwrite lets you store any files such as text documents, icons, images, videos and more.

🚀 What is new in Appwrite 0.13

The Appwrite 0.13 release offers a much more powerful Storage service! You can now group your files into Storage Buckets for better organization, as well as better control over allowed size and extension. On each bucket, you can also specify a different set of permissions, and toggle additional features such as encryption and compression.

Additionally, you can now upload files with no size limitation. In this release, chunked upload is supported and you can split your file into 5MB chunks to gradually upload a file as large as your bucket settings allow. Don’t worry, chunk upload logic is part of our SDKs and if it sees a file larger than 5MB, chunk upload will automatically kick in. One more secret! Our SDKs now accept an onProgress callback that will be triggered each time a new chunk is successfully processed. Implementing progress bars have never been easier 💪

Finally, Appwrite Storage is no longer limited by the size of your hard drive! With Appwrite 0.13, you can now connect the Storage service with cloud storage providers such as Amazon S3 or DigitalOcean Spaces. With the introduction of these adapters, you no longer need to worry about running out of space, or hitting bandwidth limits due to Appwrite Storage. More providers are coming soon, so stay tuned 😎In this guide, we’ll take a look at setting up Appwrite Storage using AWS S3 as the storage adapter.

🌊 Amazon S3 setup

Before we jump into Appwrite, let’s prepare your Amazon S3 bucket. After logging into the AWS Console:

1. Use the search bar to find the S3 service with a bucket icon on a green background and click the orange button saying Create bucket, you will be redirected to the Create bucket page.
2. Next, configure the Appwrite file storage. Most of the options are up to you, but make sure you keep the Block all public access toggle enabled - you do want to block all public access. (NOTE: I would not recommend enabling server-side encryption, as this feature is supported by Appwrite and you can control it from there.)
3. Finally, make sure to name your bucket with a unique name. Quick tip, this name will only be stored in the .env file of your Appwrite instance, and users will never see it. That means, the name can be as simple or as complex as you want.

Make sure to note down the Bucket name and AWS Region, we will need them later when connecting Appwrite to Amazon S3. In my case, they were appwrite-project-x-bucket and eu-central-1, as seen in the screenshot above.

Last but not least, you need to get a set of access keys to allow Appwrite to read and write from our newly created bucket. To do that, click on the username in the upper right corner, and then select Security credentials. Open the Access keys section and click on a blue button Create New Access Key. In the modal, click on Show Access Key, and you will be presented with two keys. The first one is called Access Key, and the one below is Secret Key. Please note both of them down, but be aware, the secret key is a really sensitive piece of information and AWS won’t show it to you in future.

That’s it! We have successfully set up our Amazon S3, and we have all the required credentials in our hands. Let’s look at how easy it is to connect Appwrite to your newly created bucket.

🧰 Connecting Appwrite to Amazon S3

Before you start, make sure you have the Appwrite instance up and running. Installation of Appwrite is as simple as running one 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:latest

To learn more about the installation process, you can check out our installation guide.

Once our Appwrite instance is up and running, we can configure the storage adapter. To do that, let’s enter the .env file and locate _APP_STORAGE_DEVICE. Currently, it’s set to Local, but since we want to use Amazon S3, we change it to S3. With the new storage provider, we are now required to add new variables:

_APP_STORAGE_DEVICE=S3
_APP_STORAGE_S3_BUCKET=YOUT_BUCKET
_APP_STORAGE_S3_REGION=YOUR_REGION
_APP_STORAGE_S3_SECRET=YOUR_ACCESS_SECRET
_APP_STORAGE_S3_ACCESS_KEY=YOUR_ACCESS_KEY

Where do we get this information from? 😨 First of all, you can already fill in access and secret keys, these are the ones we got from earlier steps when creating security credentials in Amazon AWS Console. You should also have a bucket name and region from the bucket creation process.

Once you have all of these environment variables configured, we can save the file and restart appwrite using docker-compose up -d. Did you notice that Docker is smart enough to only restart containers that use variables you just changed? 🤯

Once the Appwrite instance is restarted, create a new account and a new project. In the left menu, select ‘Storage’ and create a new bucket. Finally, upload a file into your bucket.

You can see the file was successfully uploaded, and can start using Appwrite just like usual! To confirm you are actually talking to Amazon S3, visit your storage and you'll see the file in there.

Congrats! You have successfully connected Appwrite to Amazon S3 🥳 If you plan to use files directly from your amazon bucket, there are a few things to keep in mind:

1. Every file is compressed using GZIP compression before storing it in Amazon S3. You will need to decompress the file after download if you plan to use it.
2. By default, encryption is enabled on newly created buckets in Appwrite Storage. This means you won’t be able to view the file without decrypting it first. I recommend you disable encryption if you plan on downloading the files from your Amazon S3.
3. All compression, encryption and antivirus are skipped for files above 20MB. These files are stored in your Amazon S3 as plain files.

👨‍🎓 Conclusion

The worst nightmare for every project is bad scalability of their application. Thanks to the newly released provider system for Appwrite Storage service, you can now connect Appwrite with external storage providers instead of storing the files on your system. This prevents hitting a hard drive and bandwidth limits, as well as lets you use your favorite provider alongside Appwrite. And as you have seen in the tutorial above, you can easily connect Appwrite with Amazon S3 in just a few steps!

If you have a project to share, need help or simply want to become a part of the Appwrite community, I would love for you to join our official Appwrite Discord server. I can’t wait to see what you build!

📚 Learn more

You can use the following resources to learn more and get help:

• 🚀 Appwrite Github
• 📜 Appwrite Docs
• 💬 Discord Community

Every website is a unique project with unique requirements. Appwrite understands the need for backend customization and provides Appwrite Functions to allow you to do exactly that. Thanks to 7 supported programming languages and more coming soon, Appwrite lets you use the language you are the most familiar with for your backend needs.

🚀 What Is New in Appwrite 0.13

Appwrite 0.13 introduced new features regarding storage, CLI, and functions. With a fully rewritten execution model, Appwrite now allows you to run functions as quick as 1 millisecond! 🤯 With such a performance, Appwrite now also ships with synchronous execution, allowing you to execute a function and get a response within one HTTP request.

Thanks to the new execution model, Appwrite 0.13 also allows the creation of global variables to share cache between multiple executions of a function. This drastically improves the performance of real-world applications, as they only need to load dependencies, initiate 3rd party communication, and pre-load resources in the first execution.

Last but not least, Appwrite got a new build process that is capable of downloading your project dependencies on the server side, so you no longer need to deploy your function with dependencies. This makes the flow much simpler, deployments smaller, and developers happier 😍

💸 Online Payments with Stripe

Stripe is a huge set of payments products that allows you to do business online. Stripe allows you to receive payments online, set up and manage subscriptions, automatically include taxes into payments, manage the online receipt, generate a checkout page, and much more. Stripe proudly supports multiple payment methods and countries, which makes it one of the best options for any online product.

Stripe is loved by developers too! Online payments are hard… Stripe managed to create a fast, secure and easy to understand environment that lets developers set up online payments within a few minutes.

From a technical point of view, Stripe payments are initiated using REST API, and payment status updates are sent through webhooks. Let’s look at how you can use Appwrite Functions to securely communicate with Stripe to implement online payments into an application.

🙋 What Is a Webhook?

Webhook is an HTTP request sent from one server to another, to inform it about some change. Webhooks are a smarter alternative to pulling data through an API server if you need to quickly adapt to an external change.

Stripe uses webhooks to inform applications about changes to the status of a payment. For a second let’s imagine webhooks were not implemented in Stripe, how would you know a payment was successful? For each ongoing payment, you would need to have a loop to send API requests to get payment status every few seconds and don’t stop until you have a status change. As you can imagine, this would be a resource-consuming solution that wouldn’t scale well with many payments pending at the same time, hitting API limits in the worst scenarios. Thanks to webhooks, you can give Stripe an URL, and the Stripe server will hit the URL with an HTTP request, providing a bunch of data about what has changed.

Similarly to Stripe, Appwrite also supports webhooks and can trigger HTTP requests when a change occurs inside Appwrite, such as a new user registered, or a database change. That means Appwrite can send out webhooks, but can it receive one? 🤔

🪝 Appwrite Webhook Proxy

Appwrite can receive webhook requests by default, thanks to Appwrite Functions. There is an endpoint in Appwirte HTTP API that can create a function execution. This method allows passing data in, and also providing request headers. That’s all you need for such a webhook listener, but there is one small hiccup.

Looking at Appwrite documentation, it expects a JSON body where all data is stringified under the data key. On the other hand, looking at Stripe documentation, it sends a webhook with all data in the root level as a JSON object.

Alongside this schema miss-match, Appwrite also expects some custom headers (such as API key), which Stripe cannot send. This problem can be solved by a simple proxy server that can properly map between these two schemas, and apply authentication headers.

You can expect official implementation from Appwrite itself, but as of right now, you can use Meldiron’s Appwrite webhook proxy. This project adds a configuration into your Appwrite setup that defined a new /v1/webhook-proxy endpoint in Appwrite API to solve the problem from earlier. Later in the article, we will take a look at how to set up this webhook proxy, and how to connect it to Stripe.

🛒 Let’s Code a Store

To present Stripe integration in Appwrite, I decided to create a simple application cookie store, where a customer can buy one of two cookie packs. After payment, users can look at their order history and see a payment status. This is a minimal implementation that does not include invoicing, fulfillment, or any eCommerce logic. The project was made with simplicity in mind to serve as a learning resource for anyone integrating Stripe into their Appwrite projects.

The application was made using NuxtJS framework with TypeScript, and Tailwind CSS for designing utility classes. You can follow along, or download the source code from the GitHub repository.

Stripe Setup

Let’s start by properly setting up our Stripe account, to make sure we have all secrets we might need in the future. For this example, we will be using test mode, but the same steps could be followed in production mode.

You start by visiting the Stripe website and signing up. Once in the dashboard, you can switch to the Developers page and enter the API keys tab. In there, you click the Reval key button and copy this key. It will be used later when setting up createPayment function in Appwrite.

Next, let’s switch to the Webhooks tab, and set up a new endpoint. When adding an endpoint, make sure to use URL http://YOR_ENDPOINT/v1/webhook-proxy, and provide any description you want. Last but not least, you select events to listen to, in the case of simple online payment, you only need events payment_intent.succeeded and payment_intent.canceled.

After adding the endpoint, copy your Signing secret, as you will need this in updatePayment Appwrite Function later.

Appwrite Project Setup

Before diving into frontend development, you first set up the Appwrite project. After following installation instructions and signing up, you can create a project with a custom project ID cookieShop.

Once the project is created, let’s hop into the Services tab on the Settings page. Here you can easily disable services that you won’t be using in our project. In your application, you will only be using account, database and function services. Make sure to keep this enabled, and disable the rest.

Last but not least, let’s open the Settings tab on the Users page. Here you can disable all authentication methods except anonymous session, as this will be the only one your application will use.

With all of these configurations in place, your Appwrite project is ready! 🎉

Now, you need to apply programmatic setup from the cookie store GitHub repository that sets up database structure and prepares Appwrite Functions. After cloning the repository and setting up Appwrite CLI, all you need to do is to run appwrite deploy –all to apply all of the programmatic setups. If you are interested in understanding the underlying code of these Appwrite Functions, you can check them out in respective folders:

• createPayment (NodeJS)
• updatePayment (NodeJS)

Once these functions are deployed, you need to set their environment variables. You visit Functions in your Appwrite Console and open up the Settings tab of your createPayment function. In there, near the end of the settings, you need to add a variable called STRIPE_KEY with your secret key from the Stripe dashboard. Next, you switch to settings of updatePayment and set up a few environments variables there:

• STRIPE_SIGNATURE - Webhook signature key from Stripe dashboard.
• APPWRITE_FUNCTION_ENDPOINT - Endpoint of your Appwrite instance, found in Settings.
• APPWRITE_FUNCTION_API_KEY - Appwrite project API key. You can generate one in the left menu.

With that configured, let’s see how our Appwrite Functions actually work! 💻

Appwrite Functions

To better understand our Appwrite Functions logic, let’s look at their source code. Both functions are written in Node.JS

1. Create Payment

First of all, you add Stripe library to our code, as you will be creating a payment in this function:

const stripe = require('stripe')

Next, you set up a variable holding all possible packs (products), and their basic information:

const packages = [
  {
    id: 'pack1',
    title: 'Medium Cookie Pack',
    description: 'Package incluces 1 cookie',
    price: 1.99,
    preview: '/pack1.jpg',
  },
  {
    id: 'pack2',
    title: 'Large Cookie Pack',
    description: 'Package incluces 6 cookies',
    price: 4.99,
    preview: '/pack2.jpg',
  },
]

You continue by setting up a function that will get executed when an execution is created:

module.exports = async function (req, res) {
  // Future code goes in here
}

Inside your function, let’s make sure function as properly configured in Appwrite, and provides required environment variables:

  // Setup
  if (!req.env.STRIPE_KEY) {
    throw new Error('Environment variables are not set.')
  }

Next, let’s validate user input - payload:

  // Prepate data
  const payload = JSON.parse(req.payload)
  const stripeClient = stripe(req.env.STRIPE_KEY)

  const package = packages.find((pack) => pack.id === payload.packId)

  if (!package) {
    throw new Error('Could not find the pack.')
  }

You continue by creating a Stripe payment session:

  // Create Stripe payment
  const session = await stripeClient.checkout.sessions.create({
    line_items: [
      {
        price_data: {
          currency: 'eur',
          product_data: {
            name: package.title,
            description: package.description,
          },
          unit_amount: package.price * 100,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    success_url: payload.redirectSuccess,
    cancel_url: payload.redirectFailed,
    payment_intent_data: {
      metadata: {
        userId: req.env.APPWRITE_FUNCTION_USER_ID,
        packageId: package.id,
      },
    },
  })

Last but not least, let’s return stripe payment session URL, so client can be redirected to the payment:

  // Return redirect URL
  res.json({
    paymentUrl: session.url,
  })

2. Update Payment

Similar to our first function, you require libraries and set up a main function:

const stripe = require('stripe')
const sdk = require('node-appwrite')

module.exports = async function (req, res) {
  // Future code goes in here
}

Did you notice you imported Appwrite this time? That’s right! This function is executed by Stripe webhook when a payment session status changes. This means, you will need to update the Appwrite document with a new status, so you need a proper connection with the API.

Anyway, you continue by validating environment variables, but this time you also initialize Appwrite SDK:

  // Setup Appwrite SDK
  const client = new sdk.Client()
  const database = new sdk.Database(client)

  if (
    !req.env.APPWRITE_FUNCTION_ENDPOINT ||
    !req.env.APPWRITE_FUNCTION_API_KEY ||
    !req.env.STRIPE_SIGNATURE
  ) {
    throw new Error('Environment variables are not set.')
  }

  client
    .setEndpoint(req.env.APPWRITE_FUNCTION_ENDPOINT)
    .setProject(req.env.APPWRITE_FUNCTION_PROJECT_ID)
    .setKey(req.env.APPWRITE_FUNCTION_API_KEY)

Next, let’s parse the function input (payload), and validate it using Stripe:

  // Prepate data
  const stripeSignature = req.env.STRIPE_SIGNATURE
  const payload = JSON.parse(req.payload)

  // Validate request + authentication check
  let event = stripe.webhooks.constructEvent(
    payload.body,
    payload.headers['stripe-signature'],
    stripeSignature
  )

Furthermore, you can parse data from Stripe event and pick information relevant to your usage:

  // Prepare results
  const status =
    event.type === 'payment_intent.succeeded'
      ? 'success'
      : event.type === 'payment_intent.canceled'
      ? 'failed'
      : 'unknown'

  const userId = event.data.object.charges.data[0].metadata.userId
  const packId = event.data.object.charges.data[0].metadata.packageId
  const paymentId = event.data.object.id

  const document = {
    status,
    userId,
    packId,
    paymentId,
    createdAt: Date.now(),
  }

To finish it off, let’s add a logic to update or create a document, depending on if it already exists or not:

  // Check if document already exists
  const existingDocuments = await database.listDocuments(
    'orders',
    [`paymentId.equal('${paymentId}')`],
    1
  )

  let outcome

  if (existingDocuments.documents.length > 0) {
    // Document already exists, update it
    outcome = 'updateDocument'
    await database.updateDocument(
      'orders',
      existingDocuments.documents[0].$id,
      document,
      [`user:${userId}`],
      []
    )
  } else {
    // Document doesnt exist, create one
    outcome = 'createDocument'
    await database.createDocument(
      'orders',
      'unique()',
      document,
      [`user:${userId}`],
      []
    )
  }

Finally, let’s return what you just did as a response, so you can inspect execution response in Appwrite Console when you need to double-check what happened in some specific payment:

  res.json({
    outcome,
    document,
  })

Appwrite Webhook Proxy

As mentioned earlier, you will need to use Meldiron’s webhook proxy to translate Stripe’s schema to a schema that Appwrite API supports. To do that, you will add a new container into the Appwrite Docker containers stack, which will add a new endpoint to Appwrite API.

Let’s start by adding a new container definition inside the docker-compose.yml file in an appwrite folder:

version: "3"

services:
  appwrite-webhook-proxy:
    image: meldiron/appwrite-webhook-proxy:v0.0.4
    container_name: appwrite-webhook-proxy
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.constraint-label-stack=appwrite"
      - "traefik.docker.network=appwrite"
      - "traefik.http.services.appwrite_webhook_proxy.loadbalancer.server.port=4444"
      # http
      - traefik.http.routers.appwrite_webhook_proxy_http.entrypoints=appwrite_web
      - traefik.http.routers.appwrite_webhook_proxy_http.rule=PathPrefix(`/v1/webhook-proxy`)
      - traefik.http.routers.appwrite_webhook_proxy_http.service=appwrite_webhook_proxy
      # https
      - traefik.http.routers.appwrite_webhook_proxy_https.entrypoints=appwrite_websecure
      - traefik.http.routers.appwrite_webhook_proxy_https.rule=PathPrefix(`/v1/webhook-proxy`)
      - traefik.http.routers.appwrite_webhook_proxy_https.service=appwrite_webhook_proxy
      - traefik.http.routers.appwrite_webhook_proxy_https.tls=true
      - traefik.http.routers.appwrite_webhook_proxy_https.tls.certresolver=dns
    networks:
      - appwrite
    depends_on:
      - appwrite
    environment:
      - WEBHOOK_PROXY_APPWRITE_ENDPOINT
      - WEBHOOK_PROXY_APPWRITE_PROJECT_ID
      - WEBHOOK_PROXY_APPWRITE_API_KEY
      - WEBHOOK_PROXY_APPWRITE_FUNCTION_ID
  # ...
# ...

With this in place, a new proxy server will be listening on /v1/webhook-proxy endpoint.

Now let’s update the .env file in the same appwrite folder to add authentication variables this container needs for proper secure communication:

WEBHOOK_PROXY_APPWRITE_ENDPOINT=https://YOUR_ENDPOINT/v1
WEBHOOK_PROXY_APPWRITE_PROJECT_ID=YOUR_PROJECT_ID
WEBHOOK_PROXY_APPWRITE_API_KEY=YOUR_API_KEY
WEBHOOK_PROXY_APPWRITE_FUNCTION_ID=updatePayment

Finally, let’s spin up the container by running docker-compose up -d. With all of that in place, you can now point Stripe to https://YOR_ENDPOINT/v1/webhook-proxy , and Stripe will start executing your updatePayment function while providing all data in a proper schema.

Frontend Website Setup

A process of designing frontend is not the focus of this article, so if you are interested in details of implementation, make sure to check out the GitHub repository of this project.

With that out of the way, let’s look at communication between the frontend and Appwrite project. All of this communication is implemented in a separated appwrite.ts file that holds functions for:

• Authentication
• Payment
• Order History

Before coding functions for these services, let’s set up our service file and do all of the initial setups:

import { Appwrite, Models } from "appwrite";

if (!process.env.appwriteEndpoint || !process.env.appwriteProjectId) {
    throw new Error("Appwrite environment variables not properly set!");
}

const sdk = new Appwrite();
sdk
    .setEndpoint(process.env.appwriteEndpoint)
    .setProject(process.env.appwriteProjectId);

const appUrl = process.env.baseUrl;

export type Order = {
    status: string,
    userId: string,
    packId: string,
    paymentId: string,
    createdAt: number
} & Models.Document;

Let’s start by creating trio of the most important authentication functions. You will need one to login, one to log out, and one to check if visitor is logged in. All of this can be done within a few lines of code when using AppwriteSDK:

export const AppwriteService = {
    async logout(): Promise<boolean> {
        try {
            await sdk.account.deleteSession("current");
            return true;
        } catch (err) {
            console.error(err);
            alert("Something went wrong. Please try again later.");
            return false;
        }
    },

    async login(): Promise<void> {
        await sdk.account.createAnonymousSession();
    },

    async getAuthStatus(): Promise<boolean> {
        try {
            await sdk.account.get();
            return true;
        } catch (err) {
            console.error(err);
            return false;
        }
    },

    // Future code goes in here
};

Next, you create a function that will trigger our previously coded createPayment Appwrite Function, and use url from the response to redirect user to Stripe, where they can pay they order:

    async buyPack(packId: string): Promise<boolean> {
        try {
            const executionResponse: any = await sdk.functions.createExecution("createPayment", JSON.stringify({
                redirectSuccess: `${appUrl}/cart-success`,
                redirectFailed: `${appUrl}/cart-error`,
                packId
            }), false);

            if (executionResponse.status === 'completed') {
            } else {
                throw new Error(executionResponse.stdout + "," + executionResponse.err);
            }

            const url = JSON.parse(executionResponse.stdout).paymentUrl;
            window.location.replace(url);

            return true;
        } catch (err) {
            console.error(err);
            alert("Something went wrong. Please try again later.");
            return false;
        }
    },

Last but not least, let's implement a method to get user’s order history that supports offset pagination:

    async getOrders(page = 1): Promise<Models.DocumentList<Order> | null> {
        try {
            const offset = (page - 1) * 10;
            const ordersResponse = await sdk.database.listDocuments<Order>("orders", undefined, 10, offset, undefined, undefined, ['createdAt'], ['DESC']);

            return ordersResponse;
        } catch (err) {
            console.error(err);
            alert("Something went wrong. Please try again later.");
            return null;
        }
    }

With all of this login in place, all you need to do is to finish off the rest of the frontend application by creating pages, components, and hooking into our AppwriteService to talk to the Appwrite backend.

You have just successfully created your very own store using Appwrite and Stripe! 👏 If there are any concerns about skipped parts of the frontend code, and I can’t stress this enough, make sure to check out the whole GitHub repository of this project, that holds a fully working demo application. There are some screenshots too! 👀

👨‍🎓 Conclusion

The ability to integrate your application with 3rd party tools and APIs can become critical for any scalable application. Thanks to Appwrite 0.13, as you just experienced, Appwrite Functions can now communicate both ways, allowing you to prepare your projects without any limitations. This not only means you can implement pretty much any payment gateway into your Appwrite project, but it also means all of you can enjoy preparing your Appwrite-based applications without any limitations!

If you have a project to share, need help or simply want to become a part of the Appwrite community, I would love for you to join our official Appwrite Discord server. I can’t wait to see what you build!

📚 Learn More

You can use the following resources to learn more and get help:

• 🚀 Appwrite Github
• 📜 Appwrite Docs
• 💬 Discord Community

I prepared a small quiz for you at the end of the article, so keep reading! 👀 Do you know all of the answers? 😈

Since I became active in Appwrite's Discord server, I noticed so many people getting excited about Appwrite that I decided to dedicate one article to all features people ❤️ about Appwrite.

Sure, I could write about everything that Appwrite can do, but that is not the focus of this article. If you are interested in that, check out Appwrite's articles. This article will show you practical reasons to use Appwrite for your next side project!

1. 💸 Free now, free forever!

Thanks to Appwrite being open-sourced, we can expect all future updates to be free for everyone. This doesn't seem like a huge deal, but companies such as Google (Firebase) or Amazon (AWS) have their pricing set, so it looks promising at first but gets really expensive once your business grows. With Appwrite, you can choose your own server provider and scale without spending half of your budget. I can happily confirm that Appwrite will stay open-sourced and keep all updates for free even after it gets released (1.0.0). Appwrite plans to provide cloud hosting and other juicy features for companies, but they don't intend to have any cloud-exclusive features!

2. 🤩 Wonderful community

I have joined many developer communities to learn about technology... Heck, I even hit the 100 server limit on Discord that made me upgrade to Discord nitro!

Without the slightest hesitation, I can tell you that Appwrite has the most friendly, active and helpful Discord community I have ever seen. It doesn't matter if you are a student learning to build your first project or a senior with ten years of experience; there is always someone to answer your questions on your level. Alongside the Appwrite core team and moderators, there are always at least 200 online members on the server ready to chat with you about anything. Yep, anything! A few days ago, we talked about API to check if a number is even 🧠

3. 🔥 1 production, 100 projects

Most open-source platforms are not built to handle multiple projects, and some are even unable to scale! That becomes a nightmare once your business grows, and you may be forced to switch to something else...

Great news for you! Appwrite can do both. You can host multiple projects on one Appwrite instance AND you can set up a Docker swarm to scale it across multiple servers.

{% post https://dev.to/appwrite/30daysofappwrite-docker-swarm-integration-2io9 %}

I personally find this really useful because only the Appwrite itself uses hardware resources, not the project. You can prepare a website for small local businesses and host it pretty much for free since your server hardware will barely notice their tiny traffic.

4. 📈 Usage statistics

This is pretty related to the previous point...

Let's say you used Appwrite on 30 projects for your clients. Do you know how much to invoice the client for when talking about server expenses? Thanks to usage statistics, you can easily see which projects take the most space, have the most requests, or use the most CPU time for function executions. You can also see how many errors happened to functions in the past, so we could say you have a tiny alerting system in your hands. Last but not least, you can see bandwidth usage on each project separately and debug most of "it's slow" problems quickly.

Oh man, at this point, I was already impressed by what Appwrite is capable of, and it is only the middle of this article! 🔥

5. 🧰 API for everything

Appwrite tries to provide as many APIs as possible, so you can build the application without having to bundle 10 API servers together. Appwrite can help you to get:

• List of countries and their flags, continents, currencies, languages, phone codes, browser icons, credit card icons...
• Image preview (resize, rotate, ...)
• Placeholder photo of a user (their initials)
• QR code from a text
• Favicon from website URL

Can you see it? 😮 With Appwrite, you can focus on preparing the application instead of searching for the best API to do tiny tasks for your applications.

6. 📃 Task manager

We have all been there... We have... We have all created CRONS on a Linux server, tested it for half of the week to make sure it works properly and then it stopped working anyway because the server got restarted...

I personally have been looking for a good cron alternative and fell in love with Appwrite's task manager. Actually, if someone would use Appwrite only to host functions and run tasks, I would not be surprised.

Using Appwrite, you can schedule an automatic function execution using cron syntax. This function can do anything from sending newsletter emails to buying you a pizza. No limitations at all.

7. 💪 Continuous improvement

Appwrite is still in active development, so we can expect awesome new features with every update! From the Discord community, I found about these features:

• Database refactor to speed up the database and introduce new possibilities
• Realtime to easily keep frontend and backend in sync
• Synchronous functions that makes using Appwrite functions as a custom API server possible
• Static hosting to deploy your web application directly into Appwrite
• Webhooks improvement so we can not only send webhook requests but also receive them
• Storage buckets to increase the security of file storage
• Locale API improvements so you can translate your whole application using Appwrite

8. 🦄 Over 10 SDKs

Appwrite has done an amazing job getting as close to developers as possible. No matter what coding language you use, you can easily start using Appwrite thanks to their client and server-side SDK libraries. Instead of the developer adapting to a platform, the platform adapted to the developer.

As far as I am concerned, Appwrite is actively improving Flutter SDK and is working on Unity SDK to deliver the platform to even more developers.

There is a whole repository for Appwrite SDK generator that helps any developer prepare SDK for any programming language. This tool helps keep all SDKs up to date with Appwrite features and easily fixable if there is some new error introduced by a new language version.

Let's play a game 🎲 Can you figure out the coding language from a tiny snippet of Appwrite code?

// #1
let executionPromise = sdk.functions.createExecution("[FUNCTION_ID]", { 
  paymentType: "onetime"
});

{% spoiler Answer #1: %} Javascript? Node? Deno? All of them! {% endspoiler %}

// #2
Future result = account.create(
  email: 'email@example.com',
  password: 'password',
);

{% spoiler Answer #2: %} Dart, Flutter! {% endspoiler %}

// #3
val avatars = Avatars(client)
GlobalScope.launch {
  val result = avatars.getQR(
    text = "https://appwrite.io/",
  )
   println(result); // Resource URL        
}

{% spoiler Answer #3: %} Java, Kotlin! {% endspoiler %}

// #4
$health = new Health($client);
$result = $health->getTime();

{% spoiler Answer #4: %} PHP! {% endspoiler %}

# #5
from appwrite.client import Client
from appwrite.services.locale import Locale

client = Client()
locale = Locale(client)
result = locale.get()

{% spoiler Answer #5: %} Python {% endspoiler %}

# #6
functions = Appwrite::Functions.new(client);

response = functions.get_tag(function_id: '[FUNCTION_ID]', tag_id: '[TAG_ID]');

{% spoiler Answer #6: %} Ruby {% endspoiler %}

appwrite functions listTags --functionId="[FUNCTION_ID]" --search="[SEARCH]" --limit="0" --offset="0" --orderType="ASC"

{% spoiler Answer #7: %} CLI {% endspoiler %}

Did you answer them all correctly? Maybe you didn't? It's fine! We are learning something new every day. Everyone is. Either way, I've got a joke for you as a reward! {% spoiler Do you know why this article only has eight points and not ten? %} Because it's a matter of time when Appwrite trips and it will become: ♾ reasons to fall in ❤️ with Appwrite 🤯

{% endspoiler %}

That's it! I hope this article helped you understand why I fell in ❤️ with Appwrite. Fun fact, you just read the word Appwrite over 40 times. Appwrite! If you have any questions, feel free to join Appwrite's Discord server and chat with their amazing community: https://appwrite.io/discord

Thanks to @Caryntjen from Discord for bringing this problem up

Table Of Contents

• Introduction
• Setup Angular project with Appwrite
• Add Angular Universal to our project
• Connect Appwrite to Angular Universal

Introduction

Server-side rendering can help your website speed up the initial load and let bots access your dynamic data to improve SEO. This article will show you how to quickly solve a problem with Appwrite data not being load before rendering a page server-side.

To solve our problem, we will use the library angular-zen. This library will create a zone.js task under the hood, and that helps Angular Universal understand your async code. To learn more about this, you can visit their docs: Angular zen docs

In SSR, the server doesn't wait for the async code to complete. The result is scrapers and search engines receiving a page without resolved data, which is bad in case you need them to read some resolved metadata tags for example. Use resolveInMacroTask() to have your server block and wait for resolves before rendering.

Setup Angular project with Appwrite

Before solving the problem, let's see the problem! We start by creating an empty angular project:

ng new appwrite-ssr
cd appwrite-ssr

? Do you want to enforce stricter type checking and stricter bundle budgets in the workspace?
  This setting helps improve maintainability and catch bugs ahead of time.
  For more information, see https://angular.io/strict Yes
? Would you like to add Angular routing? Yes
? Which stylesheet format would you like to use? CSS

Make sure to pick the same options to have the same results

Now, let's write some Appwrite code. To use Appwrite in our frontend project, we need to install its client-side SDK:

npm i appwrite

This is a simple javascript/typescript library with no connection to Angular, so we don't need to worry about importing modules or injecting services. For simplicity, we will do everything in our app.component. Still, it is strongly recommended to put all Appwrite logic into a separate appwrite.service to share data across multiple components in an actual project easily.

Our app.component.ts should look like this:

import { Component, OnInit } from '@angular/core';
import { Appwrite } from 'appwrite';
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent implements OnInit {
  title = 'appwrite-ssr';
  currencies: any; // Do not use any in real project

  async ngOnInit() {
    let sdk = new Appwrite();

    sdk
      .setEndpoint('https://server.matejbaco.eu/v1') // Your API Endpoint
      .setProject('60f2fb6e92712'); // Your project ID

    // Load currencies from appwrite
    const appwriteCurrencies = await sdk.locale.getCurrencies();

    // Store the result into component variable for use in HTML code
    this.currencies = appwriteCurrencies;
  }
}

First, we imported Appwrite SDK using import { Appwrite } from 'appwrite';. Then, inside ngOnInit we initialized a new instance of the SDK that is connected to our Appwrite server. Finally, we load a list of currencies from Appwrite and store it into a variable to use in HTML code.

Let's switch to app.component.html. This is our code:

<h1>Total currencies:</h1>

<!-- We don't have data yet, loading... -->
<p *ngIf="!currencies">...</p>

<!-- Data loaded, let's count them -->
<p *ngIf="currencies">Total: {{ currencies.sum }}</p>

We simply write two blocks of code - one for when data is not loaded yet, one after the loading is finished. Now, if we run ng serve and visit http://localhost:4200/, we can see the currencies being loaded successfully:

What about server-side rendering? Let's see... If we look at the source code of our application, we can this:

No useful data for bots! Let's fix that.

Add Angular Universal to our project

To prepare our project for server-side rendering, we need to add a new Angular library. Let's stop our Angular development server and run ng add @nguniversal/express-engine. Then, we can run npm run dev:ssr to have the same development server running, but this time with server-side rendering. Let's see what our website looks like to bots now:

This is awesome, one step at a time! Our Angular code is being rendered properly because we can see our title Total currencies:. We are not done yet, because this pre-rendered HTML does not include our Appwrite data. Instead, we can see ....

Connect Appwrite to Angular Universal

As mentioned initially, we will use a library that will help us run the task server-side. To do this, we stop our development server and run npm i @bespunky/angular-zen. Once the library is installed, let's start the development server with npm run dev:ssr.

Angular zen is an Angular library, so we need to add it into imports of our module for it to work properly. To do this, we go into app.module.ts and add add RouterXModule as an import. The module should look like this:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterXModule } from '@bespunky/angular-zen/router-x';
import { AppRoutingModule } from './app-routing.module';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule.withServerTransition({ appId: 'serverApp' }),
    AppRoutingModule,
    RouterXModule.forRoot(),
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

My IDE noticed the error Appears in the NgModule.imports of AppServerModule, but itself has errors, but I ignored it, and it got resolved by Angular re-building the app. If you can see this error, simply restart the development server, and you should be good to go.

We need to use RouteAware class in our app.component.ts because we need to access its resolveInMacroTask() method. To do that, we can make our component extend RouteAware. Then we wrap our async code in ngOnInit into resolveInMacroTask and await its result as a promise. Our code will look like this:

import { Component, OnInit } from '@angular/core';
import { RouteAware } from '@bespunky/angular-zen/router-x';
import { Appwrite } from 'appwrite';
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent extends RouteAware implements OnInit {
  title = 'appwrite-ssr';
  currencies: any; // Do not use any in real project

  async ngOnInit() {
    let sdk = new Appwrite();

    sdk
      .setEndpoint('https://server.matejbaco.eu/v1') // Your API Endpoint
      .setProject('60f2fb6e92712'); // Your project ID

    await this.resolveInMacroTask(async () => {
      // Load currencies from appwrite
      const appwriteCurrencies = await sdk.locale.getCurrencies();

      // Store the result into component variable for use in HTML code
      this.currencies = appwriteCurrencies;
    }).toPromise();
  }
}

We are good to go! Let's see it in action. If I visit our page, I can see the data:

If I look at the source code of pre-render, I can see the data too!

That's it! I hope this article helped you to use Appwrite with Angular Universal. If you have any questions, feel free to join Appwrite's Discord server and chat with their amazing community: https://appwrite.io/discord

• Introduction
• Getting Backblaze secrets
• B2 CLI basics
• Appwrite MariaDB 👉 Backblaze
• Appwrite Docker Volumes 👉 Backblaze

Introduction

Recently, Appwrite has released an article on how to backup and restore all data on your production server. You can read it here: {% post https://dev.to/appwrite/appwrite-in-production-backups-and-restores-4beg %}

This article got me thinking 🤔 Sure, you can backup most MySQL databases into a simple backup.sql file, but what if you have multiple massive projects inside Appwrite? Your disk storage may or may not be able to hold a backup of all Appwrite volumes. Additionally, you most likely need to backup periodically and need multiple versions of the backup. So, what are your options?

• Write a complex bash script to keep last three versions
• Throw all backups to a storage provider and let them take care of it

You should go with storage providers not only because they have a retention system already in place, also due to their experience in the field as they most likely care about security a lot and use raids to ensure your data won't get lost.

I wrote this article as I was implementing this on my own production server, and I will show you everything you need to know about backing up Appwrite into Backblaze.

Getting Backblaze secrets

First things first, what is Backblaze? Backblaze is one of the most, if not most, used commercial platform to backup your data for the lowest price possible. They provide solutions to backup your personal computer or your business data. The service we will be using is B2 Cloud Storage as this gives our flexibility just like an actual hard drive. You don't have to worry about pricing yet because their free plan gives you 10GB of free space. To learn more about this product and its pricing, you can take a look at: https://www.backblaze.com/b2/cloud-storage.html

"Over one exabyte of data storage under management, and counting." - Backblaze website

After creating an account and logging in (make sure to confirm your email), Backblaze may ask you to set up 2FA using your phone number for additional security.

To use Backblaze from our server, we will need:

• BUCKET_NAME
• ACCESS_KEY_ID
• APPLICATION_KEY

Backblaze uses buckets to store your data. In our case, we will only need one bucket as we will only back up two or three files at most (MySQL database and Appwrite Docker volumes). To create a bucket, navigate to Bucket and press Create a Bucket. Give it some name such as appwrite and click Create a Bucket again. You should see a newly created bucket on your list. Make sure to mark your Bucket Name as we will need this later.

If you enter App Keys, you can Add a New Application Key. For simplicity, we will ignore that, and we will use our master key to have all permissions. Simply click Generate a New Master Application Key, and this should give you keyID and applicationKey.

Wohoo 🎉 we have all secrets we need; let's continue!

B2 CLI basics

To make sure everything is working, let's try some simple action on B2:

• List files in a bucket
• Upload a file
• List files again

We need to have B2 CLI installed on our machine, but this can be easily avoided thanks to a Docker image mtronix/b2-cli:0.0.1. This is the only image I could find that was actually working.

To list all files in our bucket, we run:

docker run \
  --rm \
  mtronix/b2-cli:0.0.1 \
  bash -c \
  "b2 authorize-account <ACCESS_KEY_ID> <ACCESS_KEY_ID> && b2 list-file-names <BUCKET_NAME>"

The output should be an empty list of files:

{
  "files": [],
  "nextFileName": null
}

Let's upload a file 😎 We need to have a file... I downloaded a cute cat image and saved it as cat.png. To upload the file, I run:

docker run \
  --rm \
  -v $PWD:/b2 \
  mtronix/b2-cli:0.0.1 \
  bash -c \
  "b2 authorize-account <ACCESS_KEY_ID> <ACCESS_KEY_ID> && b2 upload-file <BUCKET_NAME> cat.png cat.png"

The successful result should look something like:

{
  "action": "upload",
  "fileId": "4_z78da5cd2a05db73574a90515_f11841831f8e91ca6_d20210717_m092603_c002_v0001140_t0056",
  "fileName": "cat.png",
  "size": 136021,
  "uploadTimestamp": 1626513963000
}

Finally, run the list-file-names command from above again, and you should see your file in the array of files:

{
  "files": [
    {
      "accountId": "8ac20d754955",
      "action": "upload",
      "bucketId": "78da5cd2a05db73574a90515",
      "contentLength": 136021,
...

Backblaze let you do all of this function manually on their website. Exercise for you 😲 Remove our test file from the bucket. Do it however you want - you can remove it using B2 CLI or manually on the website.

Appwrite MariaDB 👉 Backblaze

To create an Appwrite MariaDB backup, you run this command:

docker-compose exec mariadb sh -c 'exec mysqldump --all-databases --add-drop-database -u "$MYSQL_USER" -p "$MYSQL_ROOT_PASSWORD"' > ./dump.sql

(Source: Appwrite article mentioned earlier)

To backup this export into Backblaze, I created a script that:

1. Export MariaDB data to dump.sql
2. Upload dump.sql to Backblaze
3. Remove dump.sql to free up the space on the machine

This is what the script looks like:

docker-compose exec \
  mariadb \
  sh -c \
  'exec mysqldump --all-databases --add-drop-database -u"$MYSQL_USER" -p"$MYSQL_ROOT_PASSWORD"' > ./dump.sql ; \
  docker run \
  --rm \
  -v $PWD:/b2 \
  mtronix/b2-cli:0.0.1 \
  bash -c \
  "b2 authorize-account <ACCESS_KEY_ID> <ACCESS_KEY_ID> && b2 upload-file <BUCKET_NAME> dump.sql dump.sql" ; \
  rm dump.sql

Each time you run this script, it will backup your MariaDB database into Backblaze. Backblaze can store multiple versions of a single file; just make sure to configure retention on a bucket, for example, 7 days.

Appwrite Docker Volumes 👉 Backblaze

Once again, let's get our base command from Appwrite's article:

Before running these commands is it highly recommended to shut down your Appwrite instance to ensure you get a complete backup.

mkdir -p backup && docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/backup ubuntu bash -c "cd /storage/uploads && tar cvf /backup/uploads.tar ."

mkdir -p backup && docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/backup ubuntu bash -c "cd /storage/functions && tar cvf /backup/functions.tar ."

These two commands will backup two different volumes. The first one back up all files in Appwrite storage while the second one backup your function tags. Let's start with backing up uploads.

Just like with MariaDB, we will:

1. Create a backup in backup/uploads.tar
2. Send the file to Backblaze
3. Remove the backup file

The full command to do this is:

mkdir -p backup && docker run \
  --rm \
  --volumes-from "$(docker-compose ps -q appwrite)" \
  -v $PWD/backup:/backup \
  ubuntu \
  bash -c \
  "cd /storage/uploads && tar cvf /backup/uploads.tar ."  ; \
  docker run \
  --rm \
  -v $PWD:/b2 \
  mtronix/b2-cli:0.0.1 \
  bash -c \
  "b2 authorize-account <ACCESS_KEY_ID> <ACCESS_KEY_ID> && b2 upload-file <BUCKET_NAME> backup/uploads.tar upload_backup.tar" ; \
  rm backup/uploads.tar

This should create a file called upload_backup.tar in your Backblaze bucket.

Exercise time 💪 You will need to backup Appwrite functions too! Using all knowledge from this article, you should be able to prepare a command that will do it. If you are here only to copy&paste commands, here is the command: {% spoiler Command to backup Appwrite function to Backblaze %}

mkdir -p backup && docker run \
  --rm \
  --volumes-from "$(docker-compose ps -q appwrite)" \
  -v $PWD/backup:/backup \
  ubuntu \
  bash -c \
  "cd /storage/functions && tar cvf /backup/functions.tar ."  ; \
  docker run \
  --rm \
  -v $PWD:/b2 \
  mtronix/b2-cli:0.0.1 \
  bash -c \
  "b2 authorize-account <ACCESS_KEY_ID> <ACCESS_KEY_ID> && b2 upload-file <BUCKET_NAME> backup/functions.tar upload_functions.tar" ; \
  rm backup/functions.tar

{% endspoiler %}

That's it! I hope this article helped you backing up your Appwrite server. If you have any questions, feel free to join Appwrite's Discord server and chat with their amazing community: https://appwrite.io/discord