|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: Self-hosting Appwrite with MongoDB as the underlying database |
| 4 | +description: Learn how to self-host Appwrite with MongoDB as the database backend using the new installation wizard. |
| 5 | +date: 2026-04-01 |
| 6 | +cover: /images/blog/self-hosting-appwrite-with-mongodb/cover.png |
| 7 | +timeToRead: 6 |
| 8 | +author: atharva |
| 9 | +category: tutorial |
| 10 | +--- |
| 11 | + |
| 12 | +Appwrite is built on self-hosting, but until now, MariaDB was the only database option. With Appwrite 1.9.0, you can now choose MongoDB as your database backend. This is a big deal if you prefer a document-based database or already have MongoDB expertise on your team. |
| 13 | + |
| 14 | +In this article, you will learn how to self-host Appwrite with MongoDB from scratch using the new web-based installation wizard. |
| 15 | + |
| 16 | +# Prerequisites |
| 17 | + |
| 18 | +Before you begin, make sure you have the following ready: |
| 19 | + |
| 20 | +- A server or local machine with at least **2 CPU cores**, **4GB of RAM**, and **2GB of swap memory** |
| 21 | +- [Docker CLI](https://www.docker.com/products/docker-desktop) installed |
| 22 | +- If you're installing on a remote server, port **20080** must be open in your firewall (the installation wizard runs on this port). You can close it after installation is complete. |
| 23 | + |
| 24 | +# Running the installer |
| 25 | + |
| 26 | +The installer is a single Docker command that launches a web-based setup wizard. Open your terminal and run: |
| 27 | + |
| 28 | +{% tabs %} |
| 29 | +{% tabsitem #unix title="macOS and Linux" %} |
| 30 | +```bash |
| 31 | +docker run -it --rm \ |
| 32 | + --publish 20080:20080 \ |
| 33 | + --volume /var/run/docker.sock:/var/run/docker.sock \ |
| 34 | + --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ |
| 35 | + --entrypoint="install" \ |
| 36 | + appwrite/appwrite:1.9.0 |
| 37 | +``` |
| 38 | +{% /tabsitem %} |
| 39 | + |
| 40 | +{% tabsitem #cmd title="Windows (CMD)" %} |
| 41 | +```cmd |
| 42 | +docker run -it --rm ^ |
| 43 | + --publish 20080:20080 ^ |
| 44 | + --volume //var/run/docker.sock:/var/run/docker.sock ^ |
| 45 | + --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ |
| 46 | + --entrypoint="install" ^ |
| 47 | + appwrite/appwrite:1.9.0 |
| 48 | +``` |
| 49 | +{% /tabsitem %} |
| 50 | + |
| 51 | +{% tabsitem #powershell title="Windows (PowerShell)" %} |
| 52 | +```powershell |
| 53 | +docker run -it --rm ` |
| 54 | + --publish 20080:20080 ` |
| 55 | + --volume /var/run/docker.sock:/var/run/docker.sock ` |
| 56 | + --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ` |
| 57 | + --entrypoint="install" ` |
| 58 | + appwrite/appwrite:1.9.0 |
| 59 | +``` |
| 60 | +{% /tabsitem %} |
| 61 | +{% /tabs %} |
| 62 | + |
| 63 | +Once the command is running, open your browser and go to `http://localhost:20080` (or your server's IP address on port 20080). |
| 64 | + |
| 65 | +# Step 1: Setup your app |
| 66 | + |
| 67 | +The first screen asks you to configure the basics of your Appwrite instance. |
| 68 | + |
| 69 | + |
| 70 | + |
| 71 | +- **Hostname:** Enter the domain or IP address where your Appwrite instance will be accessible. If you're just testing locally, `localhost` works fine. |
| 72 | +- **Database:** This is the important part. Select **MongoDB**. It's already selected by default, but make sure it's the one highlighted. |
| 73 | +- **Advanced settings:** Expand this if you want to change the HTTP/HTTPS ports, set an SSL certificate email, or add an OpenAI key for the [Appwrite Assistant](/docs/tooling/assistant). For most setups, the defaults are fine. |
| 74 | + |
| 75 | +One thing to note here: the database choice is permanent. You cannot switch from MongoDB to MariaDB (or vice versa) after installation without starting fresh. So make sure you're happy with your choice before proceeding. |
| 76 | + |
| 77 | +# Step 2: Secure your app |
| 78 | + |
| 79 | +Next, the wizard generates a secret API key for your instance. This key is used to encrypt sensitive data on your server. |
| 80 | + |
| 81 | + |
| 82 | + |
| 83 | +Copy this key and store it somewhere safe. You won't be able to see it again after this step. If you lose it, you won't be able to decrypt your data. Use the copy button to grab it, or click regenerate if you want a new one. |
| 84 | + |
| 85 | +# Step 3: Create your account |
| 86 | + |
| 87 | +Set up the email and password for your Appwrite account. You can use these credentials to sign in to the Appwrite Console later, but you'll be automatically signed in when the installer completes. |
| 88 | + |
| 89 | + |
| 90 | + |
| 91 | +Make sure you use a strong password (minimum 8 characters). This is the account that will have full access to your Appwrite instance. |
| 92 | + |
| 93 | +# Step 4: Review and install |
| 94 | + |
| 95 | +The final step shows a summary of everything you've configured. Double-check the settings, especially the database selection showing **MongoDB**. |
| 96 | + |
| 97 | + |
| 98 | + |
| 99 | +If everything looks good, hit **Install**. The wizard will pull the necessary Docker images and set up your Appwrite instance with MongoDB. This might take a few minutes depending on your internet speed. |
| 100 | + |
| 101 | +# What happens under the hood |
| 102 | + |
| 103 | +Your Appwrite API stays exactly the same regardless of which database you pick. You still work with tables, columns, and rows through the Appwrite Console and SDKs. The database choice only affects the underlying storage engine. |
| 104 | + |
| 105 | +Here are the environment variables that get configured for MongoDB: |
| 106 | + |
| 107 | +| Variable | Value | |
| 108 | +|---|---| |
| 109 | +| `_APP_DB_ADAPTER` | `mongodb` | |
| 110 | +| `_APP_DB_HOST` | `mongodb` | |
| 111 | +| `_APP_DB_PORT` | `27017` | |
| 112 | +| `_APP_DB_SCHEMA` | `appwrite` | |
| 113 | + |
| 114 | +You can find these in the `.env` file inside your `appwrite` directory after installation. |
| 115 | + |
| 116 | +# Backing up your MongoDB data |
| 117 | + |
| 118 | +Once your instance is running, you'll want to set up backups. Here's the command to create a backup of your MongoDB data: |
| 119 | + |
| 120 | +```bash |
| 121 | +docker compose exec mongodb sh -c 'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' > ./dump.archive |
| 122 | +``` |
| 123 | + |
| 124 | +And to restore from a backup on a fresh installation: |
| 125 | + |
| 126 | +```bash |
| 127 | +docker compose exec -T mongodb sh -c 'exec mongorestore --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' < dump.archive |
| 128 | +``` |
| 129 | + |
| 130 | +Only restore to a fresh Appwrite installation to avoid data corruption. |
| 131 | + |
| 132 | +# Accessing the Console |
| 133 | + |
| 134 | +After installation completes, you'll be automatically signed in to the Appwrite Console. From here, create your first project. |
| 135 | + |
| 136 | +From here, you can start building with Appwrite's full suite of features: Authentication, Databases, Storage, Functions, Messaging, and Sites. All powered by MongoDB under the hood. |
| 137 | + |
| 138 | +# Wrapping up |
| 139 | + |
| 140 | +Self-hosting Appwrite with MongoDB is straightforward with the new installation wizard. The entire process takes a few minutes, and you get a production-ready setup with a database backend you're comfortable with. |
| 141 | + |
| 142 | +If you have any questions, join our [Discord server](https://appwrite.io/discord) to connect with the team. |
| 143 | + |
| 144 | +- [Self-hosting installation guide](/docs/advanced/self-hosting/installation) |
| 145 | +- [Database configuration](/docs/advanced/self-hosting/configuration/databases) |
| 146 | +- [Backup guide](/docs/advanced/self-hosting/production/backups) |
| 147 | +- [Production readiness](/docs/advanced/self-hosting/production) |
| 148 | +- [MongoDB integration guide](/integrations/self-hosted-mongodb) |
0 commit comments