Skip to content

Revise Directus deployment guide for Azure Web Apps #508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexchopin merged 1 commit into from
Nov 24, 2025
Merged

Revise Directus deployment guide for Azure Web Apps #508

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 78 additions & 46 deletions content/tutorials/6.self-hosting/deploy-directus-to-azure-web-apps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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` | <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> |

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.

Expand All @@ -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_<LOCATION>_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
Expand Down