DEV Community: Matej Bačo

Announcing Appwrite Sites: The open source Vercel alternative

Matej Bačo — Mon, 19 May 2025 08:24:26 +0000

You love using Appwrite to power your backend, but when it’s time to actually ship your website, you’re bouncing between tools, platforms, and extra accounts. That ends today.

Introducing Appwrite Sites.

A new Appwrite product that lets you deploy and host your websites and web apps right inside Appwrite. No more juggling services. No more gluing things together. No more multiple subscriptions. Just build, deploy, and go live. All in one place, and it's 100% open source, the kind that lets you (really) self-host and (really) own your data.

The all-in-one cloud platform

Appwrite has always been about giving you the tools you need to build fast, secure, and modern apps. However, while Appwrite has always worked hard to deliver a great backend experience, one big piece was missing: web hosting.

Until now, you had to rely on external platforms like Vercel or Netlify to get your web app live. That meant extra configs, more integrations, and one more invoice to worry about. With Sites, that gap is gone.

The best part: Appwrite is a fully open-source platform to offer both frontend hosting and your entire backend. All under one roof. From static sites and SSR apps to databases, authentication, storage, messaging and serverless functions, you can now build, deploy, and scale your entire app stack using just Appwrite.

Important Sites features

Building Sites as part of the Appwrite ecosystem was a deliberate choice to deliver a seamless experience from crafting your backend to deploying your web apps and websites. To ensure your usage of the platform feels consistent and robust, we set out to match the high standards of other Appwrite products when developing Sites over the past year.

We’ve introduced several critical features to elevate the hosting experience. Helping you scale efficiently, keep data secure, and deliver lightning-fast performance.

What’s part of Sites?

Static hosting: Ideal for single-page applications (SPAs), landing pages, documentation sites, and any project that compiles down to static files.
Server-side rendering (SSR): Full support for frameworks like Flutter, React, Next.js, Nuxt, SvelteKit, Astro, Remix, and more right out of the box.
Git integrations: Connect your GitHub repository to enable automatic deployments on every push.
Deployment previews: Get a unique preview URL for each pull request—review, test, and merge with confidence.
Global CDN: Distribute your content worldwide with a powerful content delivery network to ensure low-latency access from anywhere.
DDoS protection: Built-in protection mechanisms to help safeguard your apps from denial-of-service attacks.
The Appwrite Network: Take advantage of a growing number of cloud regions, Points of Presence (PoPs), and edge network capabilities, reducing latency and enhancing performance globally.
The Appwrite DNS: Appwrite provides a dedicated DNS (Domain Name System) service through its appwrite.zone nameservers to help you manage domain records for your applications.

All this is managed from your Appwrite Console or CLI, and deployable in both **Cloud and self-hosted environments.

Sites templates: One-Click websites

To make building your website even easier, we created ready-to-use customizable templates that you can deploy with one click, directly from Appwrite. Because not every project needs custom design, and not every team has the time to build from scratch.

We partnered with open-source maintainers like Docusaurus, ReactAdmin, and many more to bring you diverse templates. We will continue to add more templates to ensure we have everything you need.

From polished landing pages to waitlist forms and simple promo sites, Sites templates let you go live faster. Read more on how to get started with Sites templates in our docs.

How to get started with Sites

Cloud

Getting started with Sites Templates takes just a few clicks:

In the Appwrite Console's sidebar, click Sites.
Click on the Create site button.
After clicking on Connect Git repository, select your repository.
After connecting to GitHub, (optionally) add a name and site ID.
Verify that the correct framework is selected.
Confirm the install command, build command, and output directory in the build settings. To learn more, visit your preferred framework quick-start.
Add any environment variables required by the site.
The site will be created, and a build will begin. Once the build is completed, you'll have created your first site. You can use your site's domain to access the deployment.

We have added quick starts for popular frameworks to help you set up faster with your preferred framework, with more to come. As of today you can follow quick starts for Flutter, Nuxt, Next.js, Angular, SvelteKit, Remix, Astro, Vue.js, React, and Vanilla.JS.

Self-hosted

If you prefer to use Appwrite Sites open-source version, you can visit the self-hosting documentation and review the Appwrite repository.

Appwrite Sites pricing

Appwrite Sites is free to use until July 1st, 2025. We will inform you before introducing pricing so that you know well beforehand and have no surprises.

One platform to build, host, scale

Like many developer tools, we are here to make you more productive. By bringing hosting into Appwrite, you spend less time on setup and more time on what matters: building. Fewer moving parts means fewer things to break, and everything works seamlessly with your existing Appwrite services like Databases, Functions, Storage, and Auth. It’s Appwrite’s goal to improve your time to production. We make you move faster with Sites.

Sites will be available on both Appwrite Cloud and self-hosted deployments.

Spin up your first site from the Console or CLI and go live in minutes. No more stitching platforms together, no more waiting for deploys, just fast, integrated shipping.

I Found Perfect CMS after Years of Trial and Error

Matej Bačo — Thu, 03 Apr 2025 11:28:32 +0000

As a freelancer, I always looked for ways to create admin panels for my clients. It gives them control, and makes me money. It was impossible to find something simple, free, and privacy-friendly. After a fair share of experience with dozens of systems, I finally found one that aligns with my expectations.

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.

Own my data. Don't store my content, and don't become a dependency for my projects.
Extendable. Allow me to add custom components. Ideally open-sourced too, for ease of learning.
Framework agnostic. Don't tell me to use Angular. Integrate with any framework, and without a framework.
Free. Don't limit the amount of projects, clients, or features. Don't rely on paid users to keep the product alive.
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:

Fork GitHub repository
Deploy website to Cloud (Vercel, Netlify, or others)
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.

Biometric authentication with Passkeys

Matej Bačo — Sat, 09 Mar 2024 14:54:59 +0000

Password-based authentication is the most common form of authentication, but it is not the most secure. Ideally, everyone is using a password manager to have a unique and strong password on every website, and everyone protects their account with multi-factor authentication. That's not a reality, sadly. While the website can enforce some best practices for password security, password reusing - a leading problem of internet security - not all can be prevented by developers.

Introduction and benefits

Passkeys provide an authentication method that does not require users to remember a password. Instead, to authenticate, a combination of owning a device with a private key and authorizing yourself with fingerprint, face, or voice is needed. Passkeys use public key cryptography technology, which provides security that is incomparable to password-based authentication. If a server or a database is ever compromised, the user's passkeys remain secure since there is no secret stored on the server. This makes server breaches ineffective to passkey authentication. The nature of implementation also makes phishing attacks impossible since a passkey can only be used on the website on which registration happened. Your users will no longer be tricked into signing in to an attacker's website.

Using passkeys instead of password-based authentication can lead to faster and more secure sign-ins, reduce the cost of multi-factor authentication such as SMS or e-mail, and provide a faster sign-up process. Passkeys can also be used to safely access your account on a friend's device or in a public library, thanks to passkey QR codes. This gives convenience that other sign-in methods, such as MagicURL or OAuth2, do not have.

Step by step implementation

Implementing passkey involves multiple steps to keep the entire process secure and reliable. The following technologies will be used in this demo:

SimpleWebAuthn for passkey implementation
Alpine.js for reactive frontend
Node.js for custom backend endpoints
Appwrite for user management, databases, and serverless functions

The entire source code can be found on GitHub. I recommend checking it out if you are planning on implementing passkey in your project. Code snippets in the article are simplified to showcase the basics of the implementation, while source code on GitHub covers all edge cases. Such edge cases are, for example, input validation, challenge cleanup, or improved logging.

Registration with Passkey

The registration form consists of two very simple components, an e-mail and a submit button.



<form x-data="app" @submit.prevent="onSignUp()>
  <input x-model="email" type="email" required="true" />
  <button type="submit">Sign up</button>
</form>

Once the form is submitted, a client sends a request to start a registration challenge for a passkey.



const responseStart = await fetch('/v1/challenges', {
  method: 'POST',
  body: JSON.stringify({ email: this.email }),
  headers: {
    'Content-type': 'application/json'
  }
});

const body = await responseStart.json();

With a response from the server, a client can request a browser to register a new passkey. What happens next depends on the browser and operating system, and multiple modals can be shown to the user for them to decide which passkey manager they want to use.



const registration = await SimpleWebAuthnBrowser.startRegistration(body.options);

Earlier, a client sent a request to the /v1/challenges endpoint. This endpoint needs to generate a new challenge, store it in a database, and return challenge details back to the client.



const user = await appwrite.prepareUser(req.body.email);

const options = await SimpleWebAuthnServer.generateRegistrationOptions({
  rpName: 'Passkeys Demo (Appwrite)',
  rpID: process.env.ALLOWED_HOSTNAME,
  userID: user.$id,
  userName: req.body.email,
  userDisplayName: req.body.email,
  attestationType: 'none',
  authenticatorSelection: {
    residentKey: 'preferred',
    userVerification: 'preferred',
    authenticatorAttachment: 'platform',
  },
});

const challenge = await appwrite.createChallenge(user.$id, options.challenge);

return res.json({ challengeId: challenge.$id, options });

With that, the client can successfully generate a new passkey. Once the passkey is generated, the client needs to inform the server with a public key so it can be stored on the backend for future authentication.



const responseFinish = await fetch('/v1/challenges', {
  method: 'PUT',
  body: JSON.stringify({
    challengeId: body.challengeId,
    registration
  }),
  headers: {
    'Content-type': 'application/json'
  }
});

Backend implements a new method on /v1/challenges to verify that public key corresponds to the original challenge, and stores credentials in the database.



const { challengeId, registration } = req.body;

const challenge = await appwrite.getChallenge(challengeId);

const verification = await SimpleWebAuthnServer.verifyRegistrationResponse({
  response: registration,
  expectedChallenge: challenge.token,
  expectedOrigin: 'https://' + process.env.ALLOWED_HOSTNAME,
  expectedRPID: process.env.ALLOWED_HOSTNAME
});

const { verified, registrationInfo } = verification;

if(verified) {
  await appwrite.createCredentials(challenge.userId, {
    credentialID: SimpleWebAuthnServerHelpers.isoUint8Array.toHex(registrationInfo.credentialID),
    credentialPublicKey: SimpleWebAuthnServerHelpers.isoUint8Array.toHex(registrationInfo.credentialPublicKey),
    counter: registrationInfo.counter,
    credentialDeviceType: registrationInfo.credentialDeviceType,
    credentialBackedUp: registrationInfo.credentialBackedUp,
    transports: registration.response.transports
  });
}

This code snippet took a long time to figure out, as Unit8Array cannot be easily stored in a database, so it needs to be encoded to a hex value before being stored. Later, it can be decoded before authentication verification. Attempting to JSON stringify and parse Unit8Array managed to store some data, but didn't with properly.

With all of that in place, the registration flow using passkey is finished.

Login with Passkey

Similar to the sign-up process, it starts with a simple HTML form.



<form x-data="app" @submit.prevent="onSignIn()>
  <input x-model="email" type="email" required="true" />
  <button type="submit">Sign in</button>
</form>

Sign-in process also starts with a challenge. It's for the same public key cryptography secure reasons, but this time, the backend also takes advantage of having the public key in the database. When creating a challenge for the client, the server will also provide basic details about the allowed public key so the client device can suggest only relevant passkey.

First, a client sends a request to a new /v1/tokens endpoint, and starts the authentication process with challenge details from the server response:



const responseStart = await fetch('/v1/tokens', {
  method: 'POST',
  body: JSON.stringify({ email: this.email }),
  headers: {
    'Content-type': 'application/json'
  }
});

const body = await responseStart.json();

const authentication = await SimpleWebAuthnBrowser.startAuthentication(body.options);

Next, a challenge is created on the server. This time, it's not a registration challenge, but instead, an authentication challenge.



const user = await appwrite.prepareUser(req.body.email);
const credential = await appwrite.getCredential(user.$id);
const authenticator = JSON.parse(credential.credentials);

const options = await SimpleWebAuthnServer.generateAuthenticationOptions({
  rpID: process.env.ALLOWED_HOSTNAME,
  userVerification: 'preferred',
  allowCredentials: [{
    id: SimpleWebAuthnServerHelpers.isoUint8Array.fromHex(authenticator.credentialID),
    type: 'public-key',
    transports: authenticator.transports
  }]
});

const challenge = await appwrite.createChallenge(user.$id, options.challenge);

return res.json({
  challengeId: challenge.$id,
  options
});

With that implemented, the client is now prompted to select and authorize a passkey during the sign-in process. To finalize the authentication flow, the client sends one more request to the server with details about the selected passkey for final verification. Notice the server now responds with session details, which the client uses to authenticate into the Appwrite account.



const responseFinish = await fetch('/v1/tokens', {
  method: 'PUT',
  body: JSON.stringify({ challengeId: body.challengeId, authentication }),
  headers: {
    'Content-type': 'application/json'
  }
});

const token = await responseFinish.json();

await account.createSession(token.userId, token.secret);

Last but not least, we implement final authentication verification on the server and implement logic to generate an Appwrite session for the client.



const { challengeId, authentication } = req.body;
const challenge = await appwrite.getChallenge(challengeId);
const credential = await appwrite.getCredential(challenge.userId);

const authenticator = JSON.parse(credential.credentials);
authenticator.credentialID = SimpleWebAuthnServerHelpers.isoUint8Array.fromHex(authenticator.credentialID);
authenticator.credentialPublicKey = SimpleWebAuthnServerHelpers.isoUint8Array.fromHex(authenticator.credentialPublicKey);
let verification = await SimpleWebAuthnServer.verifyAuthenticationResponse({
  response: authentication,
  expectedChallenge: challenge.token,
  expectedOrigin: 'https://' + process.env.ALLOWED_HOSTNAME,
  expectedRPID: process.env.ALLOWED_HOSTNAME,
  authenticator
});

const { verified } = verification;
if (!verified) {
  return res.send('Incorrect passkey.', 400, corsHeaders);
}

const token = await appwrite.createSessionToken(challenge.userId);

return res.json({
  secret: token.secret,
  userId: challenge.userId
});

Authentication flow is now finished and users can sign into the application using passkey.

As mentioned earlier, code snippets in the article are simplified. Please refer to the source code on GitHub for a detailed implementation of the passkey authentication flow.

Additional resources

When first learning about passkey, passkeys.com can be a great starting point to understand the basics.

For implementing passkey on a website and in a Node.js server, SimpleWebAuthn docs has great descriptive examples.

If you prefer to have basics provided and plan to customize the flow yourself, I would recommend using the Appwrite Function template.

If you are looking for a Cloud solution that is easy to get up and running, you can use providers such as Hanko or Passkeys.io or Auth0.

Serverless your way: Unleashing Appwrite Function’s true potential

Matej Bačo — Thu, 07 Sep 2023 10:20:08 +0000

After countless months of research and never-ending feedback from our community, we are excited to announce that Appwrite Function received the biggest upgrade ever! Appwrite 1.4 introduces new Appwrite Functions that are truly unique and innovative, with a combination of features not found anywhere else. We achieved this by listening to real problems that developers are facing.

What problems, you might ask? One of the most common problems was using Functions as an endpoint, which was not really possible before. This was causing problems for incoming webhooks communication which is a common way to handle payments. Another regular issue was the customization of the build step, as private dependencies or TypeScript builds were not possible at all. Lastly, there were concerns about the speed of setting up a function and its environment variables.

Now let’s see how we overcame those barriers, and what new possibilities were unlocked.

About Appwrite functions

Appwrite Functions lets you extend Appwrite's capabilities by writing your own code that's deployed and managed by Appwrite. This means you can write your own custom backend solutions in Appwrite, without managing infrastructure. Build everything from custom REST endpoints, business logic, permission checks, or entirely new services on top of Appwrite. All with the ability to deploy from your GitHub repository, Appwrite Console, or through a custom CI/CD pipeline via our CLI.

We truly believe that every application is unique in its own way, and Appwrite Functions are a way to express that. We put extra effort into making sure Functions can do anything, but there is always room for improvement. Since Appwrite 1.3, we noticed a lot of community projects such as Appwrite Funcover or Appwrite Functions Proxy, and many GitHub feature requests like Global Environment Variables, Private Package in Functions, or Function with Typescript. All of that was a foundation for what we introduced in Appwrite 1.4.

Automatic deployments with GitHub

With any serverless functions, it’s important to simplify the deployment process. If you don’t, chances are that developers will prefer the good old way of managing a small Linux server. In Appwrite, we have support for manual upload in the Console, or using a terminal with a single command. We also have 0 downtime deployment support, to allow production apps to also take advantage of Functions.

With all of those cool features in place, we wanted to focus on empowering deployments. It becomes a nightmare for solo developers to manage a growing list of small functions that you have to redeploy, not to mention remembering which functions need to be deployed with specific changes you made. Our community also reported some unnecessary complexity when working on a Function in a team. The preferred way of deployment is using CLI, but there isn’t enough protection around who is allowed to deploy to production. That meant a longer onboarding process for teams to make sure developers were fully aware of how scary each command could be.

In Appwrite 1.4, we introduced a fully automated deployment using GitHub. You can now connect your GitHub repository to an Appwrite Function, and each change you push will trigger a deployment. You also get comments on your commits and pull requests, to inform you about the status of deployment. By configuring the production branch, you can decide which changes go directly into production. GitHub deployments also integrate well with your CI/CD, as Appwrite places checks on pull requests, to allow you to block merging changes that failed to build in Appwrite.

With GitHub deployment, your team is now protected from silly mistakes, and deployment is made even simpler. Alongside GitHub integration, we also added Function templates that let you get started with Functions within a few clicks!

HTTP functions and webhooks

Our mission has always been to meet developers exactly where they are in their comfort zone. By building Appwrite on top of your existing knowledge we ensure you can learn quickly and build fast.

When taking a deeper look into Functions, we noticed it wasn’t following those values. Some great examples are terms like Payload, Request variables, or Custom Data. They are easy to understand, but if we used terms like Request Body and Environment Variables, there would be nothing you would need to understand. Those would be common programming terms most of us already know, and there are numerous resources about them already written.

We also noticed Appwrite Functions had some limitations, as our community couldn’t find an easy way to integrate incoming webhooks with Appwrite. Incoming webhooks are a very common approach to integrating external services such as payment processing or chatbots. Due to that, our community made some tools such as Appwrite Funcover to overcome this problem.

Let me say a huge thank you to our community, which gave us the inspiration to redesign Appwrite Functions to follow HTTP standards.

In Appwrite 1.4, we assign unique domain to every function. You can use that, or add your own custom domain. Visiting this domain is yet another way of executing Appwrite Functions. Thanks to this small change, we are now able to provide much more information in the execution context such as request method, path, headers, or body. We can now also support many new response types such as image, PDF file, redirect, or rendered HTML. You could say that Appwrite 1.4 now lets you build your own mini web server as Appwrite Function, allowing you to do anything you could with a custom backend.

By following HTTP standards it’s now possible to handle payment processing, generate PDF invoices, run Discord or Slack bot, and even more. It’s now also possible to write a small HTTP framework inside the Appwrite Function and define your very own standalone service.

Global environment variables

With every Appwrite release, we introduce new services or improve existing ones. While it’s important to ship fast, we also focus on ensuring services work well together.

One of the most requested features since Appwrite 1.3 was an improvement to managing function environment variables. One common use-case for Appwrite Functions is to use Appwrite Server SDK and do administrative actions to documents, teams, or files. Since Appwrite doesn’t automatically provide an API key to every function (for security reasons), developers need to set it as an environment variable. This can get annoying very quickly, if you have to copy the same variables across dozens of functions you develop, not to mention there isn’t any easy way to do that either.

In the latest release, we overcame all of those problems with a few small features. Firstly, you can now set environment variables in project settings. Variables set here are provided for all the functions inside your project. No matter how many functions you have, you can now set the API key variable in one place, and get it distributed across all of them. We understand that customization of those might be necessary, which is why we decided to add automatic conflict resolution. If there is a variable defined in both project and function settings, the value from function settings takes precedence.

Secondly, in the Console, we designed a simple Variables Editor to let you edit all variables in a single action. This editor lets you import or export variables in ENV or JSON format, delete all variables, create them, copy, edit, read… All of which can be done in one text area without having to switch between modals.

Flexible build step

Customization is a must-have for any backend as a service. In the previous version, we wanted to find a good balance between customizability and simplicity. We tried to automatically detect what build step your function needs, but this check was simple and didn't account for custom build steps. We have seen our community face issues with TypeScript functions in Node, or issues with private dependencies in Python. We also noticed some CI/CD capabilities were missing for compiled languages, such as asset minification.

With Appwrite 1.4, we don't do any guessing anymore and rely on what you configure when creating a function or deployment. We still suggest reasonable defaults, but it's up to you to decide if that makes sense for your function, or not. As mentioned above, this allows custom commands such as tsc for TypeScript builds, private dependencies with token authorization export NPM_TOKEN="..."; npm install, or custom CI/CD tasks sh custom-build.sh.

You can now also keep a database or storage setup as part of your Appwrite Function. You can configure the build command to be npm install && node setup.js, and have the script to set up Appwrite Database and collection. You can see an example of that in our URL Shorter Template.

With the introduction of custom build commands, we decided to upgrade the build step even further and introduce real-time logs. You can now use build commands to minify, optimize, cache, test, and a lot more. Considering your build can now take minutes, we decided to improve the Console to show logs as they happen in real-time. This gives you much more info than the previous Building state with you sitting tight and hoping all goes well.

Closing notes

Appwrite Functions got the biggest upgrade in Appwrite 1.4, and are now capable of doing so much more.

We would love to hear your feedback! We invite you to join our Discord Server and share what you think about the new Appwrite Functions and 1.4 release in general. We are also here to chat, give support, and share memes.

Stay tuned for more information about Functions, as we will be publishing more in-depth technical article about how we built this technology, what challenges we faced, and how we managed to resolve them.

Join Celebrations! Appwrite 1.3 Ships Relationships

Matej Bačo — Wed, 12 Apr 2023 09:33:48 +0000

Our latest release Appwrite 1.3 includes the most requested feature, Database Relationships 🎉 While relationships deserve all the spotlight, we are bringing many more exciting features. Databases were the focus of this release and got some new and shiny query operators, such as Query.select() or Query.isNull(). Databases now allow give you more freedom with some of the index and page limits eliminated. Oh, and I can’t stress this enough, the new Console UI with configurable layout options and a multi-level menu is just beautiful 😍 Auth service got some thrilling new password policy configurations and Teams API now lets you set team preferences. Functions service got improvements to variables UI in Appwrite Console, and that’s not even everything! Grab your favorite snack and enjoy our announcement. 🍿

🤔 New to Appwrite?

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

🔗 Relationships in Database Service

Appwrite Databases lets you store your data and share it with all of your app users. Relationships allow you to create connections between your data to make them predictable, consistent, and easy to work with. With Relationships Beta added to Appwrite, you can now set up the four most common types of relationships directly in your Appwrite Console, and start querying your data together.

With one-to-one and many-to-one relations, you can now store similar data in separate collections to have separate permission rules. This lets you build secure apps but still keep reading data exceptionally simple.

One-to-many relations bring a powerful replacement to all of your array attributes. With a related collection, you can now store data of any complexity, and query it as you like. You can also get all the data in one request without any need to do mapping on the client side.

Many-to-many relationships are now much simpler. You no longer need to manage your own junction table as we do it for you.

As complex as relationships sound, with Appwrite, there is no need to write lengthy queries. After setting up a relationship, simply read your documents and get exactly what you expect:

const databases = new Databases(client);
const response = await databases.listDocuments('production', 'calendars');
console.log(response);

{
  "total": 1,
  "documents": [
    {
      "title": "Meetings",
      "events": [
        { "name": "Lunch Break", "date": "2023-04-03T16:30:00.000+00:00" },
        { "name": "Onboarding", "date": "2023-04-03T18:00:00.000+00:00" }
      ]
    }
  ]
}

It’s that easy! 🤩 If the response payload ever grows too big, with the new Query.select() operator you can ask for only attributes you are interested in. More on that in a later section 🤫

🤸 Databases Getting Flexier

Maximum page size and indexes make end-product faster but can create a lot of road bumps during development. These limits even created a blocker for some use cases. Not anymore!

The maximum page size for getting your documents was capped at 100. In Appwrite 1.3, this limit was eliminated. We noticed it felt limiting to many projects and implementing infinite cursor pagination wasn’t a cup of tea for everyone. While it is not recommended to query millions of documents in a single request, we made sure to provide you with tools, and yet you, a developer, make the decision.

Strict indexes for queries in Appwrite 1.3 are no longer necessary! If you ever used Appwrite Databases, chances are, you have seen the error ⚠️Index Not Found. Such strict indexes can get in the way during development and can be a blocker to some use cases with complex filtering possibilities. With Appwrite 1.3, you are no longer going to get errors telling you to set up an index.

Let’s get a little crazy and see what we can do now:

const databases = new Databases(client);

const response = await databases.listDocuments('production', 'events', [
    Query.limit(999999),
    Query.orderDesc('$id'),
    Query.orderAsc('name'),
    Query.orderDesc('date'),
    Query.greaterThan('duration', 60 * 60),
    Query.search('description', 'urgent')
]);

console.log(response);

As complex as this looks, Appwrite will accept this query and give you the results. As your app grows and this query gets slower, make sure to add indexes!😅

🔍 New Database Queries

Since we released the last database refactor in Appwrite 1.0, we noticed a huge increase in developers using Appwrite Databases. Databases became much quicker, more powerful, and more stable. With all the new feedback from our community, we noticed queries need some more attention, which is exactly what we did 😎

We are proud to announce the most requested query Query.isNull() alongside Query.isNotNull(). Null query lets you check if the value of an attribute in the document was provided, or was left empty during the creation of the document.

With relationships added to databases, we decided to also introduce Query.select() to allow developers to specify what attributes they are interested in, similarly to how it can be done with GraphQL. Specifying attributes with a select query not only decreases the size of the response, but also makes underlying queries faster and more efficient.

We also added Query.startsWith() and Query.endsWith() to bring some more searching possibilities to your string attributes. While this doesn’t sound like much, it is a great addition for many applications as workarounds for this feature were overcomplicated.

Last but not least, we added a Query.between() to improve the performance of your numeric and datetime queries when you are looking for a specific range. This was already possible with Query.greaterThan() and Query.lessThan(), but by using Query.between() we have seen improvements in performance. We are constantly working on adding new query capabilities and plan to keep introducing new ones in the future with each release.

Let’s bring all the queries together and see them in action!

const databases = new Databases(client);

const response = await databases.listDocuments('production', 'profiles', [
    Query.isNotNull('employerId'),
    Query.startsWith('phoneNumber', '+61'),
    Query.between('age', 15, 18),
    Query.select(['twitterUrl', 'linkedInUrl'])
]);

console.log(response);

We just filtered profiles to only see unemployed folks with a phone number from Canada, and a good age for student part-time job. We are only fetching their socials, so we can easily get in touch with them.

✨ Improved Passwords Security

To keep users of your application safe, Appwrite already had a minimum of 8 character limit for the password. Today we have improved password security with two new rules. 🔥

With Appwrite 1.3 you can now enable password history and configure its length. With password history enabled, your users won’t be allowed to use the exact same password that they used previously when changing their password. The length of password history lets you set how much into the past should Appwrite remember, a maximum of up to 20 passwords.

You can now also enable a rule for password dictionary. Appwrite knows what are the most common passwords, and with this rule enabled, it will not allow you users to set any of those passwords. It prevents your users from having passwords like password, 123456678, or qwertyui. Appwrite currently knows the 10,000 most commonly used passwords thanks to the same list used by other industry-leading auth providers. You can check out the dictionary list on GitHub.

🧑‍🤝‍🧑 Teams Get Preferences

Teams API got an upgrade and can now store preferences on teams. Similarly to user preferences, this feature is intended to help you store app configuration and apply it in a proper scope. You can, for example, use team preferences for business apps where the team owner (IT department in a company) does all the configuration and layout setup. Then all team members (all employees) read this setup from preferences and see the app in exactly the same way.

With this addition to the preferences family, you can now store preferences on all necessary levels. Let’s consider a scenario when we are storing if a dark theme is enabled or not. By writing to a local device, you are creating a preference on the session level. When you open the app on a new device, you will no longer have the dark theme. By using user preferences and storing them on the user level, the dark theme would be enabled as soon as you sign into your account. Finally, with team-level preferences, you can share the theme with multiple users such as students, employees, friends, or the community.

🔑 Importing Function Variables

Variables in Appwrite Functions lets you set secrets that you can securely access in your code. With Appwrite 1.3 we added a highly-requested button to Import .env file 🤯 With this new feature you can drag&drop the .env file from your function folder and Console will take care of adding all variables defined in there. Additionally, all existing variables get updated with values from your file. This is exciting for those of us who have many variables and don’t want to create them one by one.

⏩ What’s Next?

With Appwrite 1.3 out in the public, we are starting to actively work on features for Appwrite 1.4. Some of you may have already noticed GitHub activity around Functions, which we plan to be our focus for the next release. As always, we are looking forward to hearing feedback from you and prioritizing features YOU are anticipating.

📚 Learn More

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

Go Limitless with New Appwrite Queries

Matej Bačo — Wed, 14 Sep 2022 13:18:57 +0000

Appwrite is an open-source backend-as-a-service that abstracts all the complexity involved in building a modern application by providing you with a set of REST APIs for your core backend needs. Appwrite handles user authentication and authorization, real-time databases, cloud functions, webhooks, and much more!

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:

Appwrite Query	SQL Query
Query.equal("role", "Developer")	WHERE role = 'Developer'
Query.equal("role", [ "Developer", "Designer" ])	WHERE role = 'Developer' OR role = 'Designer'
Query.notEqual("category", "Flutter")	WHERE category != "Flutter"
Query.lessThan("age", 100)	WHERE age < 100
Query.lessThanEqual("age", 100)	WHERE age <= 100
Query.greaterThan("balance", 4.99)	WHERE balance > 4.99
Query.greaterThanEqual("balance", 4.99)	WHERE balance >= 4.99
Query.search("content", "phone number")	WHERE MATCH(content) AGAINST('phone number' IN BOOLEAN MODE)

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:

Appwrite Query	SQL Query
Query.orderAsc("price")	ORDER BY price ASC
Query.orderDesc("$createdAt")	ORDER BY createdAt DESC

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:

Appwrite Query	SQL Query
Query.limit(10)	LIMIT 10
Query.offset(30)	OFFSET 30
Query.cursorAfter("documentId15")	WHERE id > 15
Query.cursorBefore("documentId50")	WHERE id < 50

🧰 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 Loves Open Source: Why I Chose To Sponsor Offen

Matej Bačo — Mon, 12 Sep 2022 13:56:03 +0000

Open-source is at the ❤️ of everything we do at Appwrite, and we want to enable and foster the open-source community that helped us grow to thrilling 24,000 stars on GitHub. Open-source projects require a great deal of effort to maintain and grow. We use open-source tools every day to build Appwrite, and we want to help our community. To give back, each Appwrite engineer gets to pick an open-source project for Appwrite to sponsor for one year.

👁️ 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 Hand-In-Hand with Svelte Kit (SSR)

Matej Bačo — Sun, 05 Jun 2022 14:10:30 +0000

If you are here only to see how to make SSR work, you can jump into ⚡ Server Side Rendering and 🚀 Deployment sections. They explain it all. You can also check out the GitHub repository.

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](https://github.com/Meldiron/almost-casino)
- [Almost Casino: Live Demo](https://app.almost-casino.matejbaco.eu/)
- [Appwrite: Homepage](https://appwrite.io/)
- [Appwrite: Discord server (for any support)](https://appwrite.io/discord)
- [Svelte Kit: Docs](https://kit.svelte.dev/)

TMStats: Trackmania Tracker

Matej Bačo — Tue, 03 May 2022 16:23:19 +0000

Overview of My Submission

Live Version: www.tmstats.eu

Trackmania is a racing game loved by dozen of thousands of active players. The game is full of minute-long racing tracks where people compete against medal times, author time, or even against each other. It comes with 25 professionally made tracks every three months, alongside one community-made track every day. I like the game because it feels rewarding no matter your skill level 😌 While professional players try to have the best time on the map fighting for 0.001 second difference, you and your friends can try to get silver medals on all maps.

Trackmania has numerous apps for players that make the game even more enjoyable, such as Trackmania.io matchmaking ranks, Trackmania Exchange Leaderboards or Author Medal Tracker.

✨ With all of these community-made projects around Trackmania, I decided to make my own! ✨

Presenting... TMStats!

TMStats | Medal Tracker

Overview of all Trackmania medals you achieved. Share your campaign or daily maps medals with anyone!

tmstats.eu

TMStats is a medal tracker website that allows you to sync your Trackmania medals with a TMStats profile. Alongside the informative map detail modal, TMStats comes with a yearly medal view that really makes you appreciate the time you spent playing the game. Another cool feature I implemented is background map analytics that compares all available information to make an informed guess on the map difficulty, allowing you to focus on a difficulty that you enjoy the most 🔥 Last but not least, TMStats holds a private leaderboard of all profiles submitted to TMStats to allow you to compare against your friends, or world, easily.

TMStats is nowhere near done! Within the first week after publishing the project, thousands of accounts were created, and people started actively using the website. Based on the feedback I received, I will be adding many more features, such as achievements, daily quests, and profile decorations. Wish me good luck! 🤞

Project Repository: https://github.com/meldiron/tmstats

Submission Category:

🧙 Web2 Wizards

Link to Code

Meldiron / tmstats

A medal calendar that shows overview of all Trackmania medals an user achieved.

🥇 TMStats

👋 Introduction

TMStats is a medal tracker that shows overview of all Trackmania medals an user achieved. The website allows user to share campaign or daily maps medals with anyone.

Project focuses on multiple aspects and features:

Track of the day (TOTD) medals in yearly view
Campaign medals in season view
Custom map medals in list view
Gamified achievement & quests system

As of right now, project has no business model and is fully free and open-sourced. Project generates expenses, and business model might be added in the future.

🤖 Tech Stack

TMStats uses multiple frontend and backend technologies with focus of simplifying the development. Main focus of tech stack in this project is to make development fast and fun, instead of making it scalable and reliable.

TailwindCSS, a CSS library to rapidly design components using HTML classes
Svelte, a JS library to build reactive frontend…

View on GitHub

Additional Resources / Info

I enjoyed Hackathon A LOT, but I am an Appwrite maintainer, and it would not be fair if I competed for winnings. So I will not 😇 I submitted a project to share the project I am proud of, get participation rewards (shiny Dev badge), and show the community what Appwrite can be used for! 💪

Tech Stack:

🔥 Appwrite 🔥
Svelte & Svelte Kit
TailwindCSS
Deno (in Appwrite Functions)
Svelte Heatmap (Svelte plugin)

Collaborators:

Benko; Huge help with API discovery statistic formulas and testing

Screenshots:

User Profile
Map Details
Homepage

Why Discord Is a Must-Have for OSS

Matej Bačo — Tue, 03 May 2022 10:46:17 +0000

Appwrite is an OSS company, and we share as much as possible with our community. Since transparency is both a value and a mindset for us, we share articles like these to provide knowledge that might help developers all around the world.

Today we will focus on the topic of handling community around your open-source project outside of GitHub.

Don’t get me wrong, the GitHub issue and discussion section is a great place for keeping track of topics, but we noticed people consider these too “official”. From our experience, we see questions about failing installations more often on Discord than on GitHub. The reason behind that is that people think they must have done something wrong, and don't want to “spam” GitHub with issues that will be resolved with 1 comment. Instead, they visit Discord and freely chat about the problem they encountered.

Before looking at the advantages of the Discord community for an open-source project, let’s quickly talk about Discord!

🤖 What Is Discord?

Discord is a place for any kind of community to chat or talk. Many different communities use Discord nowadays, such as school classes, gaming communities, companies, or even your group of close friends. You can be a member of one or many communities, and set up a different profile for each of them.

Open-source projects love Discord, because of its nature of being interactive. With Discord live chat, people tend to expect answers within a few hours or minutes, which gives them a great opportunity to ask questions about a bug, specific feature, or approach to a problem using your project. Without Discord, many developers might leave your project frustrated from a mistake they made instead of asking for help on GitHub.

With a clear picture of what Discord is, let’s jump into the reasons why developers and maintainers tend to use the Discord server.

💭 Collect Feedback

Feedback is an important, if not the most important tool for an open-source project. This comes down to the reason you decided to make a project open-source! OSS allows others to not only use it but also help you improve the quality of the project by requesting or adding features they are interested in.

As mentioned earlier, GitHub discussions would be the best place for keeping track of feedback about a project, but developers find these channels too formal for pitching a feature they need for their project. With Discord, the maintainer can set up a dedicated room called #ideas and let developers freely chat about any idea they have. Some will be already implemented, and some will be out of the scope of your project... There will also be some ideas that don’t receive a lot of attention, meaning the rest of the community doesn't find them too useful. On the other hand, if an idea receives dozens of reactions, you can easily assume this feature would be appreciated by many developers. A lot of the tiny features in Appwrite come from our Discord ideas channel, and they make the project way more interesting.

🙌 Provide Support

With every new attempt to use your tool, developers can face a new issue, an undocumented edge case, or even an issue with their specific hardware. All of these are close to impossible for developers to debug on their own, as they are not familiar with your source code.

What happens next? Developer hops into your Discord server, look for a #support room and ask the question. You can get an enormous amount of positive feedback (and GitHub stars 😈) if you provide quick support to a developer. You also prevent a new developer from losing interest in your project without actually trying it, because some bug didn't let them. Last but not least, reading “Thank you” or “You are great” from time to time feels amazing!

As your community grows, you will notice that some community members that were asking questions a few weeks ago are now answering the questions of newcomers. These are usually people that really enjoyed using your project, and want to stick with it. There are so many reasons why people do this, and why you should value those, it deserves its own article! The most common reason to provide such support is to improve their own skill with your project, as providing support forces you to think about problems you likely never encountered before. On Appwrite Discord, we have a few of these, and if I see them having any questions, I instantly jump in to help them. In the end, that is the least I can do to show appreciation for their hard work.

👨‍💻 Hire New Maintainers

People who actively chat on your Discord should already be considered contributors! They know (and use) your project, they see many use-cases, they hear a bunch of feedback, and they perhaps even created a PR or two for you. If at any point your budget allows you to hire a maintainer, your active community members should be the first developers you consider. They not only share the same passion for the project as you, but they are also more likely to quickly get familiar with the source code. Fun fact, all of the early Appwrite hires were active contributors 🤯

📃 Share Development Updates

Again, going back to the roots of the mindset behind an open-source project, you want to be as transparent as possible, to get feedback for features you are working on. With no interest shown by the community in the feature you are developing, you might as well consider delaying it for another release.

Discord is a great channel for sharing those updates, as it automatically sends a notification to members. These development notes show that you actively work on a project, allow you to get feedback even before a feature is implemented, and help with building interest in your next release. At Appwrite, we started doing weekly community updates some time ago, and we already received a lot of positive feedback for doing it.

🧪 Find Alpha Testers

Developers love new features! By preparing an alpha build and sharing it with your community, you can easily get testers for your next release. This helps you prevent bugs before releasing a big feature and keep your application stable for production use. It also helps you fine-tune the feature, while still having the option to do breaking changes. We at Appwrite hosted many alpha tests for big features, such as Database refactor and Cloud Functions Gen-2.

📈 New KPIs

In an open-source project that wants to get funds for growth, the main strategy is to find an investor. Having a Discord community can provide a lot of insightful metrics to share with a potential investor for evaluation of your project. Of course, it’s not as simple as showing cool numbers, but having a gradually increasing amount of new members, active members or messages can all be key performance indicators for the investor to make a decision. Having an active Discord community can also help you fill in a slide or two with some heart-warming feedback messages to show proper validation of your project in the real world.

👨‍🎓 Conclusion

A Discord server can be a really powerful communication channel for any open-source project if used wisely. Discord server can help with collecting feedback, providing quick support, building new contributor relationships, getting releases tested, and building a community in general. With all advantages, the Discord server can provide, keep in mind that some new problems can arise. For us, the biggest challenge was to actively engage with our GitHub issues alongside Discord. We had to start requesting people to open GitHub issues for problems they report on Discord, otherwise, we would forget about them.

📚 Learn More

Appwrite is an open-source Backend-as-a-Service (BaaS), packaged as a set of Docker microservices, to give developers of any background the tools necessary to build modern apps quickly and securely. Chat with us on Discord, or learn more about Appwrite:

Start Selling Online Using Appwrite and Stripe

Matej Bačo — Thu, 17 Mar 2022 22:14:47 +0000

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

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:

Scale Appwrite Storage with DigitalOcean Spaces

Matej Bačo — Wed, 16 Mar 2022 04:14:00 +0000

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 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:

Click the green Create button in the upper right corner and select Spaces from the dropdown.
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.
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:

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.
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.
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 limit, 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!

📚 Learn more

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