diff --git a/content/tutorials/6.self-hosting/deploy-directus-to-azure-web-apps.md b/content/tutorials/6.self-hosting/deploy-directus-to-azure-web-apps.md index 4d347be8..a329e199 100644 --- a/content/tutorials/6.self-hosting/deploy-directus-to-azure-web-apps.md +++ b/content/tutorials/6.self-hosting/deploy-directus-to-azure-web-apps.md @@ -7,6 +7,8 @@ technologies: authors: - name: Durojaye Olusegun title: Guest Author + - name: Paul Boudewijn + title: Guest Author description: Learn how to deploy Directus on a Docker container on Azure. --- This guide outlines the steps to deploy Directus on Azure using Docker, with a focus on utilizing PostgreSQL as a database. @@ -38,57 +40,89 @@ Save the server's name, username, and password for later use when configuring Di Finally, click on **Review + Create** and then **Create** to create your new PostgreSQL Database deployment. -## Preparing a Docker Configuration File - -Create a `docker-compose.yml` file on your local computer and open it in your text editor. Copy and paste the following before saving: - -```yml -version: "3" -services: - directus: - image: directus/directus:10.9.3 - ports: - - 8055:8055 - volumes: - - ${WEBAPP_STORAGE_HOME}/database:/directus/database:rw - - ${WEBAPP_STORAGE_HOME}/uploads:/directus/uploads:rw - environment: - KEY: "replace-with-random-value" - SECRET: "replace-with-random-value" - ADMIN_EMAIL: "admin@example.com" - ADMIN_PASSWORD: "d1r3ctu5" - DB_CLIENT: "pg" - DB_HOST: "YOUR_PDS_DB_URL" - DB_PORT: 5432 - DB_DATABASE: "postgres" - DB_USER: "YOUR_DB_USER" - DB_PASSWORD: "YOUR_DB_PASSWORD" - WEBSOCKETS_ENABLED: true -``` - -Let’s go through some of the key parameters in this configuration file above: - -- Update the `image` tag to the [latest version](https://github.com/directus/directus/releases) of Directus. At the time of writing, it is 10.9.3. -- Set the `DB_HOST` value to the your Azure Database for PostgreSQL's server name. You can find it in the resource's overview section. -- Also set `DB_USER and DB_PASSWORD` to the credentials you set up during the creation of your Azure Database for PostgreSQL. -- `${WEBAPP_STORAGE_HOME}` is automatically populated by the Azure App Service that is mapped to persistent storage for your Directus project. - ## Deploying Directus on a Web App Service Within the Azure Marketplace, select the Web App resource. When creating a Web App, you will step through multiple configuration pages. ### Basics -- Subscription/Resource Group: select the same resource group we created and used earlier. -- Publish: Select "Docker Container". +- **Subscription/Resource Group:** select the same resource group we created and used earlier. +- **Publish:** Container +- **Operation System:** Linux + +### Container + +- **Image source:** Other container registries +- **Access Type:** Public +- **Registry server URL:** https://index.docker.io +- **Image and tag:** directus/directus:11.13.2 +- **Port:** 8055 + + +::callout{icon="material-symbols:info-outline"} + +In this section, we will specify the version of Directus as `11.13.2` as the latest at the time of writing. Please refer to the [releases](https://github.com/directus/directus/releases) and replace this with the latest version. + +:: + +Finally, click on **Review + Create** and then **Create** to create your new Web App. + +### Environment variables + +Once the web app has been created, we will return to it to enter the required environment variables. Go to Settings -> Environment variables and add the following variables: + +| Name | Value | +|------|-------| +| `SECRET` | | +| `ADMIN_EMAIL` | admin@example.com | +| `ADMIN_PASSWORD` | d1r3ctu5 | +| `DB_CLIENT` | pg | +| `DB_HOST` | | +| `DB_PORT` | 5432 | +| `DB_DATABASE` | postgres | +| `DB_USER` | | +| `DB_PASSWORD` | | + +Let’s go through some of the key parameters in this configuration above: + +- Set the `DB_HOST` value to the your Azure Database for PostgreSQL's server name. You can find it in the resource's overview section. +- Also set `DB_USER and DB_PASSWORD` to the credentials you set up during the creation of your Azure Database for PostgreSQL. + + +::callout{icon="material-symbols:info-outline"} + +The `WEBSITES_ENABLE_APP_SERVICE_STORAGE` setting must remain at its default value of "off". Changing it to "on" will prevent Directus from starting. + +:: + +### Mounting volumes + +To enable persistence for Directus, you must use external persistent storage for your file uploads, as Docker containers are ephemeral by default. + +First we need to create a storage account. In the Azure Marketplace pane, search for and select Storage accounts. Click the **Create** button and create a new storage account with preferred storage type "Azure Files". Click on **Review + Create** and then **Create** to create your new storage account. +Return to the storage account we created and go to Data storage -> File shares. Add the following file shares: + +| Name | Access tier | +| ---- | ----------- | +| database | Hot | +| extensions | Hot | +| uploads | Hot | + +Then return to the Web App and head to Settings -> Configuration -> Path mappings. Add the following mappings: -![Azure Web App Basic Configuration](/img/35c156ce-4a44-408f-a698-7d6fe14c1015.webp) +| Name | Storage type | Protocol | Storage container | Mount path | +| ---- | ------------ | -------- | ----------------- | ---------- | +| Database | Azure Files | SMB | database | /directus/database | +| Extensions | Azure Files | SMB | extensions | /directus/extensions | +| Uploads | Azure Files | SMB | uploads | /directus/uploads | -### Docker +::callout{icon="material-symbols:info-outline"} -Select Docker Compose and Docker Hub as the source for your app's configuration. Set the Docker Hub Access Type to Public and upload your `docker-compose.yml` file prepared earlier. +Although Azure Web Apps provide an option to configure volume mounts in the container's configuration screen, this does not work with Directus. +To use the built-in App Service storage, the environment variable `WEBSITES_ENABLE_APP_SERVICE_STORAGE` must be set to true. +When this setting is enabled, Azure automatically mounts an Azure Files share over the container’s `/home` directory. Unfortunately, this mount hides critical files and directories that Directus expects to be present in `/home`, causing the application to fail during startup. -![Docker configuration settings](/img/100acd23-a234-48b0-8b08-b2dc1cc58ee1.webp) +:: Following the creation of the Web App Resource, Directus is now successfully deployed and can be visited via the default domain in the Azure Web App page. @@ -101,22 +135,20 @@ Here are few troubleshooting tips: If you encounter connectivity problems between Directus and your Azure Database for PostgreSQL, consider the following steps: - **Firewall Rules:** Ensure that the firewall rules for your Azure Database allow connections from the Azure Web App. You can configure this in the Azure Portal under the *Connection Security* section for your PostgreSQL server. -- **Connection String:** Double-check the values in your docker-compose.yml file for `DB_HOST`, `DB_USER`, `DB_PASSWORD`, and other related parameters. Any discrepancies here can result in connection failures. +- **Connection String:** Double-check the values of the environment variables for `DB_HOST`, `DB_USER`, `DB_PASSWORD`, and other related parameters. Any discrepancies here can result in connection failures. ### Azure Web App Deployment Failures In case your Azure Web App deployment fails, consider the following: -- **Docker Image Compatibility:** Ensure that the Directus Docker image version specified in your `docker-compose.yml` file is compatible with the Azure Web App environment. Check for updates or use a different version if needed. +- **Docker Image Compatibility:** Ensure that the Directus Docker image version specified is compatible with the Azure Web App environment. Check for updates or use a different version if needed. - **Resource Group Permissions:** Confirm that the Azure account used for deployment has the necessary permissions to create and manage resources within the specified resource group. -- **Docker Configuration Validation:** Validate your `docker-compose.yml` file for syntax errors or inconsistencies. Incorrect configurations can lead to deployment failures. -- **Docker permissions:** When using a remote database and a remote location, i.e., when having `DB_HOST` defined and `STORAGE__DRIVER` different than `local`, be sure to set `WEBSITES_ENABLE_APP_SERVICE_STORAGE` to `false` in Environment Variables as that may cause issues on startup. ### Directus Interface Login Issues If you experience problems logging into the Directus interface: -- **Admin Credentials:** Ensure that the `ADMIN_EMAIL` and `ADMIN_PASSWORD` values in your `docker-compose.yml` file match the credentials you are using to log in. +- **Admin Credentials:** Ensure that the values of the environment variables `ADMIN_EMAIL` and `ADMIN_PASSWORD` match the credentials you are using to log in. - **Environment Variable Changes:** If you make changes to environment variables after the initial deployment, restart the Directus container to apply the new configurations. ## Summary