Skip to content
On this page

Horizontal Scaling

After you've decentralized your Database and Storage, you can go into horizontal scaling. If you haven't done so make sure to that first.

Horizontal scaling is adding more Client instances and balances the input using a load balancer. Horizontal means that the scaling is going to expand from one side to another, which means that instead of N instance you are going to expand to N + H instances.

Here's a diagram that illustrates the infrastructure, notice the far right dashed line represents a newly added server.


Duplicate client instances

In the previous chapter you have created the main and client servers, When you have these two servers, scaling is very easy, just follow these steps.

  1. Turn of the client server.
  2. Create a snapshot of that server.
  3. Turn the client server back on.
  4. Create as many as needed servers and make them use the client snapshot you've just created.
  5. Assign the client tag/label (depends on the IaaS provider) to all of the client instances.

Now, every time you'll access any of the newly created servers IP, you'll get the same Appwrite instance.

Tag-based load-balancer

That part alone won't give you horizontal-scaled Appwrite, to complete that process you'll need to utilize a load-balancer and make balance between all your client instances.

Most IaaS load-balancers let you balance the traffic by tag.

Then all you need to do is point your domain to the load-balancer IP, doing so will make sure any request made to your Appwrite domain will be balanced between your client instances.

More DB connection

In case you're scaling up and up it's necessary to let your MariaDB have more than the 151 default connections limit.

To do so, edit your main server docker-compose.yml file and add this line

    image: mariadb:10.7
    container_name: appwrite-mariadb
      - "3306:3306"
    restart: unless-stopped
      - gateway
      - appwrite-mariadb:/var/lib/mysql:rw
      - /root/databases/my.cnf:/etc/mysql/my.cnf:rw 
      - MYSQL_USER
    command: 'mysqld --innodb-flush-method=fsync'

This line will make MariaDB load is settings from the local /root/databases/my.cnf file. Create this file

nano /root/databases/my.cnf

And paste the following content in it to change the max connection up to 1000.

socket = /run/mysqld/mysqld.sock
!includedir /etc/mysql/mariadb.conf.d/
!includedir /etc/mysql/conf.d/
max_connections = 1000

You can change the 1000 of max_connection to any other higher number, just make sure your main server can handle it.

Then, reload the Docker compose by running:

docker compose down && docker compose up -d


Upgrading an HA cluster of Appwrite must be done manually following these steps, make sure to choose the most-quite time in your server.

  1. Create a strong replication of your client server. You want to create a strong one, so the inside process will be as fast as possible
  2. Don't give the new server the load-balancer tag
  3. Edit the docker-compose.yml file change the Appwrite image version to new one
  4. Run docker compose up -d that will download the new image and update the infrastructure to the latest version
  5. In case there's a need of migrate run docker exec appwrite migrate
  6. Turn off the new server
  7. Take a snapshot of the new server
  8. Delete the new server
  9. Create N servers using the new snapshot, where N equeal to the number of client servers you're using right now.
  10. Add the load-balancer tag to newly created servers.
  11. Remove the load-balancer tag from the old version servers.
  12. Check that everything is in order.
  13. Delete the old servers.

You can automate most of the process from step 6-13 by using your IaaS API. For now, this part is outside the scope of this book.


Go to Benchmarks to see how Appwrite is handling request when scaling it horizontally.


In the book repo in the horizontal folder, you'll find ansible file for automating the whole installation process.

You'll need to set just the servers IP and run

ansible-playbook appwrite.yml --ask-vault-pass

It's amazing!

Pocket size instructions
# Step-by-step summary, checklist style.

1. Create a decentralized **server** contains databases & storage drivers.
2. Create **server**
    1. Create swap file
    2. Install docker
    3. Mount the decentralized server `share` folder
    4. Create a folder in the `root` folder name it `appwrite`
    5. Create `docker-compose.yml` using the service `docker-compose.yml` file
    6. Create `.env` file using the service `.env` file
    7. Update, set and backup the `.env` environment variables
    8. Run `docker compose up -d`
    9. Create a *snapshot* and name it `high-availability-1.3.8`
    10. Add the `high-availability` tag to the server.
3. Create another 2 **servers** using the `high-availability-1.3.8` snapshot.
    1. Run `cd /root/appwrite`
    2. Run `docker compose up -d`
4. Create a **Load-balancer** and make balanced through all the `high-availability` tagged-servers.

# 🚀 You decentralized infrastructure has been deployed!