diff --git a/.optimize-cache.json b/.optimize-cache.json index 162c4a82c6..8ca33186a3 100644 --- a/.optimize-cache.json +++ b/.optimize-cache.json @@ -235,6 +235,7 @@ "images/blog/appwrite-homepage-redesign/old-homepage.png": "78e71a9a71f59c9f872afbfca91eca73dcc932e25cd83ef22505d314d636a26c", "images/blog/appwrite-homepage-redesign/summary-vs-deepdive1.png": "fbfed43d56afacb1eb3bbaffa26c002e4bd27a072d25783ae823de123b7d71f2", "images/blog/appwrite-homepage-redesign/summary-vs-deepdive2.png": "9f18d02a03cfe1f5646e6b585bbeafde584d89cd8a55bef72f1137df73c47b73", + "images/blog/appwrite-mongodb-partnership-self-hosted/cover.png": "3914377a9d50bb3d604fd88e1d5537a97b03f128847d7bd827e5aa3e009fbad1", "images/blog/appwrite-pricing-update/add-ons.png": "7f7cf75b41114b5f14bda99087e6d9a6d3b39667fb4fc4479389ae3b1a666fb7", "images/blog/appwrite-pricing-update/bandwidth-project.png": "a34a4914fc6eff580267159cabc3110869c89c64bfd9a9ecb93fb3a6335060fd", "images/blog/appwrite-pricing-update/combined.png": "e0bdc6025ca29acc57423acfa028a3324a3478937226a5e06cf2ef501a320e4a", @@ -880,6 +881,7 @@ "images/blog/self-hosting-appwrite-with-coolify/cover.png": "ef2ee53a0dffacc4a25d5012267a124718dc6664d15457d7ec56bec9526360aa", "images/blog/self-hosting-appwrite-with-coolify/create-droplet.png": "33382b0e16e5ad34a6df88db61677d617bbc7fbbb0dcd7e0197ac2675f302ce5", "images/blog/self-hosting-appwrite-with-coolify/generate-ssh-key.png": "9c4ac49fdcae8d1004aec5246e95182026aa62677881de1984578671ca56fd22", + "images/blog/self-hosting-appwrite-with-mongodb/cover.png": "76c2df27f2a364ac71ae0935cd77539ee576235617703a97a0a806111905040f", "images/blog/serverless-functions/1.png": "65f0b27672db8ef96297826faac64462a94ec242742d970e9ec31165d4cbbdda", "images/blog/serverless-functions/2.png": "cc910cbce07637d514f2af3144be469be5d50ef4f03c30cb09d8071edd317a70", "images/blog/serverless-functions/3.png": "500f8b99aa7dd677fe44d61ffb2fb864b04fbeea1e554c5eb9e90dca8c756375", @@ -1167,6 +1169,14 @@ "images/docs/advanced/security/dpa.png": "5bfbf7c5654a27d23eeefe49ff70c79861d2734f454c62758978b1a600f1c85d", "images/docs/advanced/security/mfa-modal.png": "f56b55bcb1ca889597bf8cb803fcabe8b66deaf2f06fd4f49a100d9a507cabef", "images/docs/advanced/security/mfa.png": "903def2fe311e439851c1ed0b730bb6c88f8b8b32a8ad53152d244fb48b141e5", + "images/docs/advanced/self-hosting/installation/dark/wizard-account.png": "b7082787919afe0cb0d7975361356438d798927efda8a47c7471f08b4dd8816a", + "images/docs/advanced/self-hosting/installation/dark/wizard-review.png": "7d4cebea557f02e9e519390b5c16b2d552f641e8dff2c7c89db9851c8887edfa", + "images/docs/advanced/self-hosting/installation/dark/wizard-secure.png": "e558268592865d2ce464e37188b92ff4e1bd54d3c59fd643ad4acac2bcb117ce", + "images/docs/advanced/self-hosting/installation/dark/wizard-setup.png": "f16722e8e54da3117350d229ab2c31e955c49a54fa3439353a7c9524a3053bd4", + "images/docs/advanced/self-hosting/installation/wizard-account.png": "b3020afb2bb33c7e5258ae94fe8ba70db0446d5818eb859602bef94ca4e02e6e", + "images/docs/advanced/self-hosting/installation/wizard-review.png": "669d3b94cddbdc7dd4e4a784512726d83e74aed9a472f43d37812bd34bda8750", + "images/docs/advanced/self-hosting/installation/wizard-secure.png": "7730499fae6d0f7eb14d85f4978c2e0a84d2362c507d5cfe474ccc920f8cc1cd", + "images/docs/advanced/self-hosting/installation/wizard-setup.png": "a591eb264af97db479c2e34085e8f2bb901ec8dace8de36b089ee4ab623e9606", "images/docs/ai/audio-processing-dark.png": "90852c361d73240474a316ca089edbc18e33b4665adb7d714dac9a7daea8945f", "images/docs/ai/audio-processing-light.png": "29a92249b7f2706307321d5bb96d4d20a7ac41b6b55e61e374608e9941e9a6b9", "images/docs/ai/computer-vision-dark.png": "9802337f7e7464e987c963a4dac750dbf3971765161049c7470e3ba976f15412", diff --git a/src/routes/blog/post/appwrite-mongodb-partnership-self-hosted/+page.markdoc b/src/routes/blog/post/appwrite-mongodb-partnership-self-hosted/+page.markdoc new file mode 100644 index 0000000000..4cf51e7132 --- /dev/null +++ b/src/routes/blog/post/appwrite-mongodb-partnership-self-hosted/+page.markdoc @@ -0,0 +1,61 @@ +--- +layout: post +title: Appwrite and MongoDB are partnering to build the future of open-source development +description: Appwrite and MongoDB are joining forces around a shared vision, giving developers a fully open-source, database-flexible backend platform they can own, grow with, and trust at every stage. +date: 2026-03-31 +cover: /images/blog/appwrite-mongodb-partnership-self-hosted/cover.png +timeToRead: 6 +author: + - eldad-fux + - jake-barnby +category: announcement +featured: true +--- + +Today, we're announcing a partnership between Appwrite and MongoDB. + +More than just a technical integration, this is a long-term, strategic collaboration between two companies that share the same belief: developers deserve open-source tools that actually work together, don't lock them in, and grow with them over time. + +# Why this partnership exists + +Appwrite and MongoDB were both built for developers who want control. MongoDB gave the world a flexible, powerful data layer. Appwrite gave developers a complete open-source backend they could own end-to-end. Both companies grew by betting on the open-source community and investing in it heavily. + +What we're formalizing now is the natural next step: two open-source-first companies aligning around a shared vision, combining strengths, and committing to building something together that neither could build as well alone. + +The goal is a backend platform that doesn't force tradeoffs. One where you can choose your database, own your infrastructure, and still get the developer experience you'd expect from a managed service. + +# How we're starting: MongoDB on self-hosted Appwrite + +The first concrete result of this partnership is that **MongoDB is now officially supported in Appwrite's self-hosted, open-source edition** and Appwrite is now listed in the [MongoDB Partner Ecosystem](https://cloud.mongodb.com/ecosystem/appwrite). + +When you select MongoDB during setup, Appwrite spins up a MongoDB Community Edition container and manages everything alongside your other services. Your app talks to Appwrite through the same APIs and SDKs as always. Appwrite handles schema management, connections, and the full lifecycle. + +**Ready to get started?** Our [self-hosting tutorial](/blog/post/self-hosting-appwrite-with-mongodb) walks you through everything you need to spin up an Appwrite instance powered by MongoDB. + +# How both communities benefit + +For the **Appwrite community**, this partnership means your backend is no longer tied to a single data engine. As Appwrite expands database support, you gain real flexibility in how you architect and operate your infrastructure, without giving up the unified API, SDKs, and backend services you already rely on. + +For the **MongoDB community**, this partnership opens a new door. Appwrite is a full-featured developer platform offering authentication, storage, serverless functions, databases, web hosting, and more. With MongoDB now supported as Appwrite's underlying data engine, MongoDB developers can adopt Appwrite as a complete backend layer that speaks their language, runs in their environments, and fits inside their existing operations. + +Both communities benefit from something the open-source ecosystem rarely gets: two major platforms actively investing in making each other work better. + +# The larger vision + +The end goal is a developer cloud where the database is never a constraint. One where you choose the data layer that fits your team, your stack, and your scale, and Appwrite works seamlessly on top of it. + +Moving beyond a single database engine means giving developers a truly schema-flexible, cloud-native backend that doesn't force tradeoffs between ownership, flexibility, and experience. And it means building that future alongside the companies whose technology already powers the way developers work. + +Here's what's on the roadmap: + +- **MongoDB on Appwrite Cloud.** MongoDB will be available in a fully managed environment. The console will adapt dynamically when running on MongoDB, and the experience will feel first-class from day one. +- **A more idiomatic NoSQL experience.** We're working on an API that removes the need for rigid attribute definitions, giving developers a schema-flexible workflow that matches how people actually build with document databases. +- **Broader database flexibility across the platform.** Alongside the recent introduction of TablesDB, this partnership signals the direction Appwrite is heading: a platform where you bring the database that fits your team, and Appwrite works seamlessly on top of it. + +# What comes next + +This partnership is a beginning, not a destination. The work ahead is about making database flexibility a first-class part of what Appwrite means; not a feature, but a foundation. + +We see a future where developers never have to choose between the tools they want and the platform that ties them together. Where open-source isn't a constraint but an advantage. Where the backend layer disappears into the background and teams spend their time building products, not plumbing. + +Appwrite and MongoDB are building toward that future together. We'll share more as it takes shape; stay tuned for the announcements to come. diff --git a/src/routes/blog/post/introducing-imagine/+page.markdoc b/src/routes/blog/post/introducing-imagine/+page.markdoc index 9893442e3b..2dcf7688a6 100644 --- a/src/routes/blog/post/introducing-imagine/+page.markdoc +++ b/src/routes/blog/post/introducing-imagine/+page.markdoc @@ -9,7 +9,6 @@ author: - eldad-fux - ariel-weinberger category: announcement -featured: true --- When we started Appwrite, our mission was clear: reduce the operational and infrastructural burden of building software so developers could focus on what actually matters - product, logic, and user experience. We set out to remove unnecessary complexity, give teams real control over their backend, and make production-grade infrastructure accessible without forcing developers to fight it. That principle has guided every major decision we have made. diff --git a/src/routes/blog/post/self-hosting-appwrite-with-mongodb/+page.markdoc b/src/routes/blog/post/self-hosting-appwrite-with-mongodb/+page.markdoc new file mode 100644 index 0000000000..d3925cf178 --- /dev/null +++ b/src/routes/blog/post/self-hosting-appwrite-with-mongodb/+page.markdoc @@ -0,0 +1,148 @@ +--- +layout: post +title: Self-hosting Appwrite with MongoDB as the underlying database +description: Learn how to self-host Appwrite with MongoDB as the database backend using the new installation wizard. +date: 2026-03-31 +cover: /images/blog/self-hosting-appwrite-with-mongodb/cover.png +timeToRead: 6 +author: atharva +category: tutorial +--- + +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. + +In this article, you will learn how to self-host Appwrite with MongoDB from scratch using the new web-based installation wizard. + +# Prerequisites + +Before you begin, make sure you have the following ready: + +- A server or local machine with at least **2 CPU cores**, **4GB of RAM**, and **2GB of swap memory** +- [Docker CLI](https://www.docker.com/products/docker-desktop) installed +- 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. + +# Running the installer + +The installer is a single Docker command that launches a web-based setup wizard. Open your terminal and run: + +{% tabs %} +{% tabsitem #unix title="macOS and Linux" %} +```bash +docker run -it --rm \ + --publish 20080:20080 \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ + --entrypoint="install" \ + appwrite/appwrite:1.9.0 +``` +{% /tabsitem %} + +{% tabsitem #windows title="Windows" %} +## CMD +```cmd +docker run -it --rm ^ + --publish 20080:20080 ^ + --volume //var/run/docker.sock:/var/run/docker.sock ^ + --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ + --entrypoint="install" ^ + appwrite/appwrite:1.9.0 +``` + +## PowerShell +```powershell +docker run -it --rm ` + --publish 20080:20080 ` + --volume /var/run/docker.sock:/var/run/docker.sock ` + --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ` + --entrypoint="install" ` + appwrite/appwrite:1.9.0 +``` +{% /tabsitem %} +{% /tabs %} + +Once the command is running, open your browser and go to `http://localhost:20080` (or your server's IP address on port 20080). + +# Step 1: Setup your app + +The first screen asks you to configure the basics of your Appwrite instance. + +![Setup your app](/images/docs/advanced/self-hosting/installation/dark/wizard-setup.png) + +- **Hostname:** Enter the domain or IP address where your Appwrite instance will be accessible. If you're just testing locally, `localhost` works fine. +- **Database:** This is the important part. Select **MongoDB**. It's already selected by default, but make sure it's the one highlighted. +- **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. + +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. + +# Step 2: Secure your app + +Next, the wizard generates a secret API key for your instance. This key is used to encrypt sensitive data on your server. + +![Secure your app](/images/docs/advanced/self-hosting/installation/dark/wizard-secure.png) + +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. + +# Step 3: Create your account + +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. + +![Create your account](/images/docs/advanced/self-hosting/installation/dark/wizard-account.png) + +Make sure you use a strong password (minimum 8 characters). This is the account that will have full access to your Appwrite instance. + +# Step 4: Review and install + +The final step shows a summary of everything you've configured. Double-check the settings, especially the database selection showing **MongoDB**. + +![Review your setup](/images/docs/advanced/self-hosting/installation/dark/wizard-review.png) + +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. + +# What happens under the hood + +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. + +Here are the environment variables that get configured for MongoDB: + +| Variable | Value | +|---|---| +| `_APP_DB_ADAPTER` | `mongodb` | +| `_APP_DB_HOST` | `mongodb` | +| `_APP_DB_PORT` | `27017` | +| `_APP_DB_SCHEMA` | `appwrite` | + +You can find these in the `.env` file inside your `appwrite` directory after installation. + +# Backing up your MongoDB data + +Once your instance is running, you'll want to set up backups. Here's the command to create a backup of your MongoDB data: + +```bash +docker compose exec mongodb sh -c 'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' > ./dump.archive +``` + +And to restore from a backup on a fresh installation: + +```bash +docker compose exec -T mongodb sh -c 'exec mongorestore --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' < dump.archive +``` + +Only restore to a fresh Appwrite installation to avoid data corruption. + +# Accessing the Console + +After installation completes, you'll be automatically signed in to the Appwrite Console. From here, create your first project. + +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. + +# Wrapping up + +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. + +If you have any questions, join our [Discord server](https://appwrite.io/discord) to connect with the team. + +- [Self-hosting installation guide](/docs/advanced/self-hosting/installation) +- [Database configuration](/docs/advanced/self-hosting/configuration/databases) +- [Backup guide](/docs/advanced/self-hosting/production/backups) +- [Production readiness](/docs/advanced/self-hosting/production) +- [MongoDB integration guide](/integrations/self-hosted-mongodb) diff --git a/src/routes/changelog/(entries)/2026-03-24.markdoc b/src/routes/changelog/(entries)/2026-03-24.markdoc new file mode 100644 index 0000000000..b5ac903d4e --- /dev/null +++ b/src/routes/changelog/(entries)/2026-03-24.markdoc @@ -0,0 +1,14 @@ +--- +layout: changelog +title: "MongoDB support for self-hosted Appwrite" +date: 2026-03-24 +cover: /images/blog/appwrite-mongodb-partnership-self-hosted/cover.png +--- + +Appwrite now supports MongoDB as a database backend for self-hosted installations. Starting with Appwrite 1.9.0, you can choose between MongoDB and MariaDB when setting up your instance. MongoDB is the new default. + +The new web-based installation wizard walks you through the setup, including database selection, in just a few steps. Your Appwrite API stays the same regardless of which database you pick - only the underlying storage engine changes. + +{% arrow_link href="/blog/post/appwrite-mongodb-partnership-self-hosted" %} +Read the announcement +{% /arrow_link %} diff --git a/src/routes/docs/advanced/self-hosting/+layout.svelte b/src/routes/docs/advanced/self-hosting/+layout.svelte index 88adce526e..5e5302b7a4 100644 --- a/src/routes/docs/advanced/self-hosting/+layout.svelte +++ b/src/routes/docs/advanced/self-hosting/+layout.svelte @@ -49,6 +49,10 @@ { label: 'Configuration', items: [ + { + label: 'Databases', + href: '/docs/advanced/self-hosting/configuration/databases' + }, { label: 'Environment variables', href: '/docs/advanced/self-hosting/configuration/environment-variables' diff --git a/src/routes/docs/advanced/self-hosting/configuration/databases/+page.markdoc b/src/routes/docs/advanced/self-hosting/configuration/databases/+page.markdoc new file mode 100644 index 0000000000..068d5fd62b --- /dev/null +++ b/src/routes/docs/advanced/self-hosting/configuration/databases/+page.markdoc @@ -0,0 +1,99 @@ +--- +layout: article +title: Databases +description: Configure the database backend for your self-hosted Appwrite instance. Learn about the supported database options and their configuration. +--- + +Appwrite supports MongoDB and MariaDB as database backends. The database is selected during [installation](/docs/advanced/self-hosting/installation) via the setup wizard and **cannot be changed after installation**. + +Regardless of which database you choose, the Appwrite API remains the same. Only the underlying storage engine differs. + +{% info title="Default database" %} +MongoDB is the default database as of Appwrite 1.9.0. +{% /info %} + +# CLI installation {% #cli-installation %} + +If you prefer to skip the setup wizard, you can set the database directly using the `--database` flag: + +{% tabs %} +{% tabsitem #unix title="macOS and Linux" %} +```bash +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:1.9.0 \ + --database=mongodb +``` +{% /tabsitem %} + +{% tabsitem #windows title="Windows" %} +## CMD +```cmd +docker run -it --rm ^ + --volume //var/run/docker.sock:/var/run/docker.sock ^ + --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ + --entrypoint="install" ^ + appwrite/appwrite:1.9.0 ^ + --database=mongodb +``` + +## PowerShell +```powershell +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:1.9.0 ` + --database=mongodb +``` +{% /tabsitem %} +{% /tabs %} + +Accepted values are `mongodb` and `mariadb`. + +# Supported databases {% #supported-databases %} + +## MongoDB {% #mongodb %} + +MongoDB is a document-based database and the default option for new Appwrite installations. It is configured as a replica set (`rs0`) automatically during installation. + +- **Docker image:** `mongo:8.2.5` +- **Container name:** `appwrite-mongodb` +- **Default port:** `27017` + +## MariaDB {% #mariadb %} + +MariaDB is a relational SQL database. It was the default database in Appwrite versions prior to 1.9.0. + +- **Docker image:** `mariadb:10.11` +- **Container name:** `appwrite-mariadb` +- **Default port:** `3306` + +# Environment variables {% #environment-variables %} + +Both database backends use the same environment variables. The values differ depending on which database was selected during installation. + +| Variable | Description | MongoDB default | MariaDB default | +|---|---|---|---| +| `_APP_DB_ADAPTER` | Database adapter type | `mongodb` | `mariadb` | +| `_APP_DB_HOST` | Database server hostname | `mongodb` | `mariadb` | +| `_APP_DB_PORT` | Database server port | `27017` | `3306` | +| `_APP_DB_SCHEMA` | Database name | `appwrite` | `appwrite` | +| `_APP_DB_USER` | Database user | `user` | `user` | +| `_APP_DB_PASS` | Database user password | `password` | `password` | +| `_APP_DB_ROOT_PASS` | Database root password | `rootsecretpassword` | `rootsecretpassword` | + +The Docker Compose profile controls which database container runs. This is set automatically by the installer: + +- `COMPOSE_PROFILES=mongodb` for MongoDB installations +- `COMPOSE_PROFILES=mariadb` for MariaDB installations + +{% info title="Change default passwords" %} +Always change the default database passwords before deploying to production. Update both the environment variables and the database credentials. +{% /info %} + +# Backups {% #backups %} + +For database backup procedures, see the [Backups](/docs/advanced/self-hosting/production/backups) guide, which covers both MongoDB and MariaDB backup and restore commands. diff --git a/src/routes/docs/advanced/self-hosting/configuration/environment-variables/+page.markdoc b/src/routes/docs/advanced/self-hosting/configuration/environment-variables/+page.markdoc index 0978ec3d40..af1b5644c0 100644 --- a/src/routes/docs/advanced/self-hosting/configuration/environment-variables/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/configuration/environment-variables/+page.markdoc @@ -60,16 +60,17 @@ Appwrite uses a Redis server for managing cache, queues and scheduled tasks. The | `_APP_REDIS_PASS` | Redis server password. This is an optional variable. Default value is an empty string.| # Database {% #database %} -Appwrite uses MariaDB to persist database data. The DB env vars are used to allow Appwrite server to connect to MariaDB. +Appwrite supports MariaDB and MongoDB as database backends. The database is selected during [installation](/docs/advanced/self-hosting/installation). See [Databases](/docs/advanced/self-hosting/configuration/databases) for more details. | Name | Description | |------------------------|--------------------------------------------------------------------------------------------------| -| `_APP_DB_HOST` | MariaDB server host name address. Default value is: `mariadb`. | -| `_APP_DB_PORT` | MariaDB server TCP port. Default value is: `3306`. | -| `_APP_DB_SCHEMA` | MariaDB server database schema. Default value is: `appwrite`. | -| `_APP_DB_USER` | MariaDB server user name. Default value is: `user`. | -| `_APP_DB_PASS` | MariaDB server user password. Default value is: `password`. | -| `_APP_DB_ROOT_PASS` | MariaDB server root password. Default value is: `rootsecretpassword`. | | +| `_APP_DB_ADAPTER` | Database adapter type. Default value is: `mongodb`. Possible values: `mongodb`, `mariadb`. | +| `_APP_DB_HOST` | Database server host name address. Default value is: `mongodb` (or `mariadb` for MariaDB). | +| `_APP_DB_PORT` | Database server TCP port. Default value is: `27017` (or `3306` for MariaDB). | +| `_APP_DB_SCHEMA` | Database name. Default value is: `appwrite`. | +| `_APP_DB_USER` | Database server user name. Default value is: `user`. | +| `_APP_DB_PASS` | Database server user password. Default value is: `password`. | +| `_APP_DB_ROOT_PASS` | Database server root password. Default value is: `rootsecretpassword`. | # SMTP {% #smtp %} diff --git a/src/routes/docs/advanced/self-hosting/installation/+page.markdoc b/src/routes/docs/advanced/self-hosting/installation/+page.markdoc index d01f717b46..732c1879b5 100644 --- a/src/routes/docs/advanced/self-hosting/installation/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/installation/+page.markdoc @@ -18,18 +18,13 @@ Before installing Appwrite, ensure your system meets these minimum requirements: # Install with Docker {% #install-with-docker %} -The easiest way to install Appwrite is using our Docker installer tool. This automated installer will guide you through the setup process. +The easiest way to install Appwrite is using our Docker installer. The installer launches a web-based setup wizard that guides you through the entire process. Before running the installation command, ensure you have [Docker CLI](https://www.docker.com/products/docker-desktop) installed on your host machine. -## Installation prompts {% #installation-prompts %} - -During setup, you'll be prompted to configure: - -1. **HTTP and HTTPS ports** - Your Appwrite instance's HTTP and HTTPS ports. -2. **Secret key** - Your Appwrite instance's secret key used to encrypt sensitive data. -3. **Main hostname** - Your Appwrite instance's main hostname. Appwrite will generate a certificate using this hostname. -4. **DNS A record hostname** - Usually the same as your main hostname. +{% info title="Firewall configuration" %} +The installation wizard runs on port **20080**. If you are installing on a remote server, ensure that port 20080 is open in your firewall or security group settings before proceeding. You can close this port after installation is complete. +{% /info %} ## Installation commands {% #installation-commands %} @@ -39,10 +34,11 @@ Run the following command in your terminal: ```bash docker run -it --rm \ + --publish 20080:20080 \ --volume /var/run/docker.sock:/var/run/docker.sock \ --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ --entrypoint="install" \ - appwrite/appwrite:1.8.1 + appwrite/appwrite:1.9.0 ``` {% /tabsitem %} @@ -50,23 +46,85 @@ docker run -it --rm \ ## CMD ```cmd docker run -it --rm ^ + --publish 20080:20080 ^ --volume //var/run/docker.sock:/var/run/docker.sock ^ --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ --entrypoint="install" ^ - appwrite/appwrite:1.8.1 + appwrite/appwrite:1.9.0 ``` ## PowerShell ```powershell docker run -it --rm ` + --publish 20080:20080 ` --volume /var/run/docker.sock:/var/run/docker.sock ` --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ` --entrypoint="install" ` - appwrite/appwrite:1.8.1 + appwrite/appwrite:1.9.0 ``` {% /tabsitem %} {% /tabs %} +Once the command is running, open your browser and navigate to `http://localhost:20080` to access the setup wizard. + +# Setup wizard {% #setup-wizard %} + +The setup wizard walks you through four steps to configure your Appwrite instance. + +## Step 1: Setup your app {% #wizard-setup %} + +Configure your Appwrite instance's basic settings. + +{% only_dark %} +![Setup your app](/images/docs/advanced/self-hosting/installation/dark/wizard-setup.png) +{% /only_dark %} +{% only_light %} +![Setup your app](/images/docs/advanced/self-hosting/installation/wizard-setup.png) +{% /only_light %} + +- **Hostname** - The domain or IP address where your Appwrite instance will be accessible. +- **Database** - Choose between [MongoDB or MariaDB](/docs/advanced/self-hosting/configuration/databases) as your database backend. MongoDB is selected by default. +- **Advanced settings** - Optionally configure HTTP and HTTPS ports, SSL certificate email, and an OpenAI API key for the [Appwrite Assistant](/docs/tooling/assistant). + +## Step 2: Secure your app {% #wizard-secure %} + +A secret API key is automatically generated for your instance. This key is used to encrypt sensitive data. + +{% only_dark %} +![Secure your app](/images/docs/advanced/self-hosting/installation/dark/wizard-secure.png) +{% /only_dark %} +{% only_light %} +![Secure your app](/images/docs/advanced/self-hosting/installation/wizard-secure.png) +{% /only_light %} + +{% info title="Save your key" %} +You won't be able to see this key again after proceeding. Copy it somewhere safe before continuing. +{% /info %} + +You can use the **Copy** button to copy the key or **Regenerate** to create a new one. + +## Step 3: Create your account {% #wizard-account %} + +Set up the email and password for your Appwrite account. You'll use these credentials to sign in to the Appwrite Console after installation. + +{% only_dark %} +![Create your account](/images/docs/advanced/self-hosting/installation/dark/wizard-account.png) +{% /only_dark %} +{% only_light %} +![Create your account](/images/docs/advanced/self-hosting/installation/wizard-account.png) +{% /only_light %} + +## Step 4: Review your setup {% #wizard-review %} + +Review all your configuration settings. If anything looks wrong, use the **Back** button to make changes. When you're ready, click **Install** to begin the installation. + +{% only_dark %} +![Review your setup](/images/docs/advanced/self-hosting/installation/dark/wizard-review.png) +{% /only_dark %} +{% only_light %} +![Review your setup](/images/docs/advanced/self-hosting/installation/wizard-review.png) +{% /only_light %} + # Manual installation {% #manual-installation %} For advanced users who prefer manual setup, you can install Appwrite using Docker Compose directly. @@ -100,8 +158,7 @@ docker compose up -d --remove-orphans After installation completes: 1. **Access the Console** - Navigate to your machine's hostname or IP address in your browser -2. **Create an account** - Sign up for your Appwrite account -3. **Create your first project** - Set up your development environment +2. **Create your first project** - Set up your development environment {% info title="Startup time" %} On non-Linux hosts, the server might take a few minutes to start after installation completes. This is normal behavior. @@ -145,6 +202,8 @@ After successfully installing Appwrite, you can: [Configure services](/docs/advanced/self-hosting/configuration/email) - Set up email, SMS, storage, and other services +[Configure databases](/docs/advanced/self-hosting/configuration/databases) - Learn more about MongoDB and MariaDB configuration + [Production setup](/docs/advanced/self-hosting/production) - Prepare your installation for production use -[Update Appwrite](/docs/advanced/self-hosting/production/updates) - Keep your installation up to date \ No newline at end of file +[Update Appwrite](/docs/advanced/self-hosting/production/updates) - Keep your installation up to date diff --git a/src/routes/docs/advanced/self-hosting/production/backups/+page.markdoc b/src/routes/docs/advanced/self-hosting/production/backups/+page.markdoc index da4d434765..34237bc60e 100644 --- a/src/routes/docs/advanced/self-hosting/production/backups/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/production/backups/+page.markdoc @@ -23,7 +23,11 @@ Your Appwrite installation has several components that need backing up: # Database backups {% #database-backup %} -Appwrite uses MariaDB. Use `mysqldump` for most installations: +Appwrite supports MariaDB and MongoDB as database backends. Use the backup method that matches your installation. + +## MariaDB backups {% #mariadb-backup %} + +Use `mysqldump` for MariaDB installations: ```bash # Create database backup (all databases) @@ -33,12 +37,24 @@ docker compose exec mariadb sh -c 'exec mysqldump --all-databases --add-drop-dat docker compose exec -T mariadb sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < dump.sql ``` +For large databases, consider `mariabackup` for physical backups. + +## MongoDB backups {% #mongodb-backup %} + +Use `mongodump` for MongoDB installations: + +```bash +# Create database backup +docker compose exec mongodb sh -c 'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' > ./dump.archive + +# Restore (fresh installation only) +docker compose exec -T mongodb sh -c 'exec mongorestore --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' < dump.archive +``` + {% info title="Fresh installation only" %} Only restore to fresh Appwrite installations to avoid data corruption. {% /info %} -For large databases, consider `mariabackup` for physical backups. - # Storage volume backups {% #storage-backup %} Shut down Appwrite before backing up volumes to avoid data inconsistency. @@ -52,7 +68,8 @@ Appwrite uses these Docker volumes: - `appwrite-certificates` - SSL certificates - `appwrite-config` - Configuration - `appwrite-cache` and `appwrite-redis` - Cache data -- `appwrite-mariadb` - Database files +- `appwrite-mariadb` - Database files (MariaDB installations) +- `appwrite-mongodb` - Database files (MongoDB installations) ## Backup methods diff --git a/src/routes/docs/advanced/self-hosting/production/scaling/+page.markdoc b/src/routes/docs/advanced/self-hosting/production/scaling/+page.markdoc index 42a18a27e2..217fbf7223 100644 --- a/src/routes/docs/advanced/self-hosting/production/scaling/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/production/scaling/+page.markdoc @@ -10,7 +10,7 @@ Each Appwrite instance is composed of many containers, each with its unique job. If you decide to set up a load balancer to scale a container, make sure **all** communication are routed through the load balancer and not directly to the replicated containers. You can configure communicating between Appwrite containers using Docker environment variables. -Two Appwrite containers are stateful. The MariaDB and Redis containers are used for storing data, cache and pub/sub messaging, and usage stats, respectively. To scale these containers, set up a standard cluster (same as you would with any other app using these technologies) according to your needs and performance. +Two Appwrite containers are stateful. The database (MariaDB or MongoDB, depending on your installation) and Redis containers are used for storing data, cache and pub/sub messaging, and usage stats, respectively. To scale these containers, set up a standard cluster (same as you would with any other app using these technologies) according to your needs and performance. # Performance considerations {% #performance-considerations %} diff --git a/src/routes/docs/advanced/self-hosting/production/updates/+page.markdoc b/src/routes/docs/advanced/self-hosting/production/updates/+page.markdoc index 1c7fea5354..2f7d3c2d1c 100644 --- a/src/routes/docs/advanced/self-hosting/production/updates/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/production/updates/+page.markdoc @@ -44,6 +44,7 @@ Replace `` below with the specific Appwrite image tag you inte ```sh docker run -it --rm \ + --publish 20080:20080 \ --volume /var/run/docker.sock:/var/run/docker.sock \ --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ --entrypoint="upgrade" \ @@ -54,6 +55,7 @@ docker run -it --rm \ ```cmd docker run -it --rm ^ + --publish 20080:20080 ^ --volume //var/run/docker.sock:/var/run/docker.sock ^ --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ --entrypoint="upgrade" ^ @@ -64,6 +66,7 @@ docker run -it --rm ^ ```powershell docker run -it --rm ` + --publish 20080:20080 ` --volume /var/run/docker.sock:/var/run/docker.sock ` --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ` --entrypoint="upgrade" ` diff --git a/src/routes/integrations/self-hosted-mongodb/+page.markdoc b/src/routes/integrations/self-hosted-mongodb/+page.markdoc new file mode 100644 index 0000000000..5b34f58fef --- /dev/null +++ b/src/routes/integrations/self-hosted-mongodb/+page.markdoc @@ -0,0 +1,123 @@ +--- +layout: integration +title: Self-host Appwrite with MongoDB +description: Use MongoDB as the underlying database for your self-hosted Appwrite instance. +date: 2026-03-24 +featured: true +isPartner: true +isNew: true +cover: /images/integrations/self-hosted-mongodb/cover.jpg +category: databases +product: + avatar: '/images/integrations/avatars/mongodb.png' + vendor: MongoDB + description: 'MongoDB is a popular NoSQL database known for its flexibility and scalability.' +platform: + - 'Self-hosted' +images: + - /images/integrations/self-hosted-mongodb/cover.jpg + - /images/docs/advanced/self-hosting/installation/dark/wizard-setup.png + - /images/docs/advanced/self-hosting/installation/dark/wizard-secure.png + - /images/docs/advanced/self-hosting/installation/dark/wizard-account.png + - /images/docs/advanced/self-hosting/installation/dark/wizard-review.png +--- + +[MongoDB](https://www.mongodb.com/) is a popular NoSQL database known for its flexibility and scalability. It allows developers to store and manage large amounts of data with ease. + +# How does the integration work? + +Traditionally, Appwrite has utilized MariaDB as its primary database under the hood. Appwrite now supports **MongoDB** as an alternative database option in its self-hosted setup, allowing developers to access the same Appwrite features and experience while offering greater flexibility in platform deployment. + +From the developer's point of view, nothing changes in how you use Appwrite: + +- You still create databases, tables, and rows from the Appwrite Console (or via SDKs). +- Appwrite stores that data in **MongoDB Community Edition** under the hood, along with other Appwrite metadata it needs to operate. +- You can use **MongoDB Compass** to confirm that the data Appwrite wrote is present in MongoDB. + +# How to implement + +To set up the **Appwrite + MongoDB (self-hosted)** integration, there are several steps you must complete: + +## Step 1: Self-host Appwrite + +Self-host Appwrite using the following Docker command: + +{% tabs %} +{% tabsitem #unix title="macOS and Linux" %} +```bash +docker run -it --rm \ + --publish 20080:20080 \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ + --entrypoint="install" \ + appwrite/appwrite:1.9.0 +``` +{% /tabsitem %} + +{% tabsitem #windows-cmd title="Windows (Command Prompt)" %} + +```cmd +docker run -it --rm ^ + --publish 20080:20080 ^ + --volume //var/run/docker.sock:/var/run/docker.sock ^ + --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ + --entrypoint="install" ^ + appwrite/appwrite:1.9.0 +``` +{% /tabsitem %} + +{% tabsitem #windows-pwsh title="Windows (Powershell)" %} + +```powershell +docker run -it --rm ` + --publish 20080:20080 ` + --volume /var/run/docker.sock:/var/run/docker.sock ` + --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ` + --entrypoint="install" ` + appwrite/appwrite:1.9.0 +``` +{% /tabsitem %} + +{% /tabs %} + +Once the command is running, open your browser and go to `http://localhost:20080` (or your server's IP address on port 20080). + +## Step 2: Configure your setup + +On visiting the aforementioned URL, Appwrite's self-hosting installation wizard will ask you to configure certain necessary fields: + +![Setup your app](/images/docs/advanced/self-hosting/installation/dark/wizard-setup.png) + +- **Hostname:** Enter the domain or IP address where your Appwrite instance will be accessible. If you're just testing locally, `localhost` works fine. +- **Database:** Select `MongoDB`. It should already be selected by default, but ensure it is the one highlighted. +- **Advanced settings:** Expand this if you want to change the HTTP/HTTPS ports, set an SSL certificate email address, or add an OpenAI key for the Appwrite Assistant. Unless you are an advanced Appwrite user configuring your instance for production, the default configuration should be fine. + +## Step 3: Secure your app + +Once your instance is set up, the wizard will generate a secret key to encrypt sensitive data on your server. + +![Secure your app](/images/docs/advanced/self-hosting/installation/dark/wizard-secure.png) + +Copy this key and store it somewhere safe. You will not be able to see it again after this step. + +## Step 4: Create your account + +Create the email and password for your Appwrite account. These credentials will allow you to sign in to the Appwrite Console on your instance after installation. + +![Create your account](/images/docs/advanced/self-hosting/installation/dark/wizard-account.png) + +## Step 5: Review your setup + +Before concluding, the installation wizard will show you a summary of your configuration. Double-check all the settings and verify that the database selection shows MongoDB. + +![Review your setup](/images/docs/advanced/self-hosting/installation/dark/wizard-review.png) + +Once everything looks good, hit the **Install** button. The wizard will pull the necessary Docker images and set up your Appwrite instance with MongoDB configured as the underlying database. + +# Read more about MongoDB and Appwrite + +If you would like to learn more about MongoDB and Appwrite, we have some resources that you should visit: + +- [Announcement blog: Self-hosting Appwrite with MongoDB](/blog/post/appwrite-mongodb-partnership-self-hosted) +- [MongoDB Partner Ecosystem Catalog: Appwrite](https://cloud.mongodb.com/ecosystem/appwrite) +- [Appwrite's databases configuration docs](/docs/advanced/self-hosting/configuration/databases) diff --git a/src/routes/integrations/sms-twilio/+page.markdoc b/src/routes/integrations/sms-twilio/+page.markdoc index 5c210864b6..9a7d8784fd 100644 --- a/src/routes/integrations/sms-twilio/+page.markdoc +++ b/src/routes/integrations/sms-twilio/+page.markdoc @@ -3,7 +3,7 @@ layout: integration title: SMS with Twilio description: Send customized SMS messages to your users date: 2024-07-30 -featured: true +featured: false isPartner: true isNew: false cover: /images/integrations/sms-twilio/cover.png diff --git a/static/images/blog/appwrite-mongodb-partnership-self-hosted/cover.png b/static/images/blog/appwrite-mongodb-partnership-self-hosted/cover.png new file mode 100644 index 0000000000..1c6062d256 Binary files /dev/null and b/static/images/blog/appwrite-mongodb-partnership-self-hosted/cover.png differ diff --git a/static/images/blog/self-hosting-appwrite-with-mongodb/cover.png b/static/images/blog/self-hosting-appwrite-with-mongodb/cover.png new file mode 100644 index 0000000000..df1bf480c7 Binary files /dev/null and b/static/images/blog/self-hosting-appwrite-with-mongodb/cover.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/dark/wizard-account.png b/static/images/docs/advanced/self-hosting/installation/dark/wizard-account.png new file mode 100644 index 0000000000..3609922f4a Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/dark/wizard-account.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/dark/wizard-review.png b/static/images/docs/advanced/self-hosting/installation/dark/wizard-review.png new file mode 100644 index 0000000000..d489dd4670 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/dark/wizard-review.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/dark/wizard-secure.png b/static/images/docs/advanced/self-hosting/installation/dark/wizard-secure.png new file mode 100644 index 0000000000..8417d12e67 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/dark/wizard-secure.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/dark/wizard-setup.png b/static/images/docs/advanced/self-hosting/installation/dark/wizard-setup.png new file mode 100644 index 0000000000..f86a56aac6 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/dark/wizard-setup.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/wizard-account.png b/static/images/docs/advanced/self-hosting/installation/wizard-account.png new file mode 100644 index 0000000000..9c0e3d44b9 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/wizard-account.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/wizard-review.png b/static/images/docs/advanced/self-hosting/installation/wizard-review.png new file mode 100644 index 0000000000..026342d957 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/wizard-review.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/wizard-secure.png b/static/images/docs/advanced/self-hosting/installation/wizard-secure.png new file mode 100644 index 0000000000..aab7b1c498 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/wizard-secure.png differ diff --git a/static/images/docs/advanced/self-hosting/installation/wizard-setup.png b/static/images/docs/advanced/self-hosting/installation/wizard-setup.png new file mode 100644 index 0000000000..4bcdc6afa8 Binary files /dev/null and b/static/images/docs/advanced/self-hosting/installation/wizard-setup.png differ diff --git a/static/images/integrations/self-hosted-mongodb/cover.jpg b/static/images/integrations/self-hosted-mongodb/cover.jpg new file mode 100644 index 0000000000..7027ce9485 Binary files /dev/null and b/static/images/integrations/self-hosted-mongodb/cover.jpg differ