Appwrite - macOS Installation and Debugging Guide

Kritika Sharma — Mon, 25 Oct 2021 03:28:50 +0000

Introduction to Appwrite

Appwrite is an end-to-end backend solution for Web, Mobile, Native, or Backend Apps. It abstracts the complexity and repetitiveness required to build a modern backend API from scratch and allows you to build secure apps faster.

Appwrite is a great choice for backend solutions as it provides the following benefits:

Easy integration with user authentication and a choice of multiple sign-in methods
Tracking and managing user's sessions, security logs
Secure and encrypted storage of files
Tracking user's location and managing app's locale-based data
Managing user's avatars, countries' flags, browser icons, credit card symbols and generating QR codes

Also, it provides a wide variety of server-side as well as client-side SDKs to integrate with. To set up and experiment with Appwrite on macOS, you can follow the steps mentioned below. For more details or installation on other systems, you can visit their installation guide.

Setting up Appwrite on macOS

Installing docker

In order to install appwrite, you need to install docker first.

Download docker desktop for mac here: https://docs.docker.com/desktop/mac/install/
Once downloaded, open the file and drag the docker icon to applications folder as shown below
Run the app. It will ask for permission to install tools (including docker cli which is needed for running appwrite)
You can verify docker cli installation by typing the following in your terminal:

docker version

Installing Appwrite

Appwrite offers easy and simple installation by directly running their docker installer tool from the terminal. Now that docker cli is set up and verified by following steps mentioned above, run the following command in your terminal to install appwrite:

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

It will ask you to define the following parameters:

HTTP port
HTTPS port
API key
Hostname
Custom domain

You can either customize or choose defaults for above parameters.

After you have specified these details, it will take a few moments. If everything went fine, you will get a message saying Appwrite installed successfully

You can now access your appwrite dashboard by visiting http://<hostname or custom domain>:<HTTP port>
It will look like this:

You can now start creating your first project and explore appwrite docs for more features and functionalities.

Debugging common installation issues

Pull rate limit exceeded

While installing appwrite through docker, you can get the following error:

toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

This error occurs because, due to recent changes in its company policy, docker now has a limit of 100 downloads every six hours from a single IP address.
To avoid this error, you need to authenticate to your DockerHub account. If you don’t have an account on DockerHub, you can sign up for a free account. Follow the instructions below:

Make sure that docker is running
Click on the whale icon present in top right on the mac toolbar
Click on the option “Sign in / Create Docker ID”
A dialog box will appear asking you to enter docker ID and password
It will also suggest creating a new account if you don’t have one. Click on the link and follow the steps to sign up

HTTP 500 error and other container related issues

Sometimes, even after the appwrite installation is complete and you get the successful installation message, your dashboard might not work.
When accessing localhost, you might get HTTP 500 error as shown below.

One of the reasons for this might be that not all of your containers are working fine.
To verify if all your containers are up, open your terminal and type:

docker ps

You should see the following containers:

appwrite (main appwrite container)
appwrite-traefik (reverse-proxy and load balancer)
appwrite-worker-deletes (performs deletions in appwrite database)
appwrite-worker-certificates (creates and renews SSL certificates)
appwrite-worker-usage (sends usage related stats to telegraf)
appwrite-worker-tasks (create repeating tasks using CRON schedule)
appwrite-worker-webhooks (triggers registered webhooks based on events)
appwrite-worker-audits (audits and logs system events)
appwrite-worker-functions (handles tasks related to cloud functions)
appwrite-realtime (listens to server-side events in realtime)
appwrite-schedule (handles scheduling of CRON jobs)
appwrite-worker-mails (sends emails)
appwrite-maintenance (housekeeping tasks and cleaning up logs)
appwrite-redis (used for caching, messaging and scheduling)
appwrite-telegraf (collects and sends metrics and events)
appwrite-mariadb (default db for project collections)
appwrite-influxdb (stores API usage metrics and stats)

If all of the containers are working fine, their status will be of the sort: Up xx minutes/seconds

If some containers are not working fine, their status will be of the sort: Restarting (x) xx seconds ago

Using Appwrite’s doctor CLI

To specifically check for storage and connectivity issues first, we can use the doctor CLI provided by Appwrite.

For versions 0.7 and above, Appwrite provides the doctor CLI. The doctor CLI helps you validate your server health and best practices. Using the Doctor CLI, you can verify your server configuration for best practices, validate your Appwrite stack connectivity and storage read and write access, and available storage space.

To run the doctor check, simply run the following command from your terminal:

docker exec <container-name> doctor

container-name is the name of container that is failing or not working fine.

Checking for storage/connectivity issues

To check for issues with main appwrite container, use appwrite as the container-name for doctor CLI.
If everything works fine, the command output will look like this:

In case of storage issues, the command output will look like this:

In order to fix this issue, you can remove unused docker volumes by running the following command:

docker volume prune

After this, you can re-install appwrite as per steps given below.

Re-installing Appwrite

You will need to re-install appwrite in case of any corrupt files persisting. In order to re-install appwrite, you need to remove the current running containers first

To stop all running containers, run the following command:

docker kill $(docker ps -q)

To remove all the stopped containers, run the following command:

docker rm -f $(docker ps -a -q)

After that, you can remove all previous appwrite docker volumes by running:

docker volume prune

Now, you can follow the appwrite setup guide to install it again.

You are now ready to create your first project with an error-free setup.
Appwrite is a rapidly growing open-source community. To learn more about Appwrite, you can visit the following links:

DEV Community: Kritika Sharma