You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Revise Directus deployment guide for Azure Web Apps (#508)
Updated tutorial for deploying Directus on Azure Web Apps (required due to Azure's deprecation of Docker Compose) with updated Docker configuration, environment variables, and troubleshooting tips.
Let’s go through some of the key parameters in this configuration file above:
70
-
71
-
- 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.
72
-
- 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.
73
-
- Also set `DB_USER and DB_PASSWORD` to the credentials you set up during the creation of your Azure Database for PostgreSQL.
74
-
- `${WEBAPP_STORAGE_HOME}`is automatically populated by the Azure App Service that is mapped to persistent storage for your Directus project.
75
-
76
43
## Deploying Directus on a Web App Service
77
44
78
45
Within the Azure Marketplace, select the Web App resource. When creating a Web App, you will step through multiple configuration pages.
79
46
80
47
### Basics
81
48
82
-
- Subscription/Resource Group: select the same resource group we created and used earlier.
83
-
- Publish: Select "Docker Container".
49
+
-**Subscription/Resource Group:** select the same resource group we created and used earlier.
50
+
-**Publish:** Container
51
+
-**Operation System:** Linux
52
+
53
+
### Container
54
+
55
+
-**Image source:** Other container registries
56
+
-**Access Type:** Public
57
+
-**Registry server URL:**https://index.docker.io
58
+
-**Image and tag:** directus/directus:11.13.2
59
+
-**Port:** 8055
60
+
61
+
62
+
::callout{icon="material-symbols:info-outline"}
63
+
64
+
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.
65
+
66
+
::
67
+
68
+
Finally, click on **Review + Create** and then **Create** to create your new Web App.
69
+
70
+
### Environment variables
71
+
72
+
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:
73
+
74
+
| Name | Value |
75
+
|------|-------|
76
+
|`SECRET`| <REPLACE_WITH_RANDOM_VALUE> |
77
+
|`ADMIN_EMAIL`|admin@example.com|
78
+
|`ADMIN_PASSWORD`| d1r3ctu5 |
79
+
|`DB_CLIENT`| pg |
80
+
|`DB_HOST`| <YOUR_PDS_DB_URL> |
81
+
|`DB_PORT`| 5432 |
82
+
|`DB_DATABASE`| postgres |
83
+
|`DB_USER`| <YOUR_DB_USER> |
84
+
|`DB_PASSWORD`| <YOUR_DB_PASSWORD> |
85
+
86
+
Let’s go through some of the key parameters in this configuration above:
87
+
88
+
- 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.
89
+
- Also set `DB_USER and DB_PASSWORD` to the credentials you set up during the creation of your Azure Database for PostgreSQL.
90
+
91
+
92
+
::callout{icon="material-symbols:info-outline"}
93
+
94
+
The `WEBSITES_ENABLE_APP_SERVICE_STORAGE` setting must remain at its default value of "off". Changing it to "on" will prevent Directus from starting.
95
+
96
+
::
97
+
98
+
### Mounting volumes
99
+
100
+
To enable persistence for Directus, you must use external persistent storage for your file uploads, as Docker containers are ephemeral by default.
101
+
102
+
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.
103
+
Return to the storage account we created and go to Data storage -> File shares. Add the following file shares:
104
+
105
+
| Name | Access tier |
106
+
| ---- | ----------- |
107
+
| database | Hot |
108
+
| extensions | Hot |
109
+
| uploads | Hot |
110
+
111
+
Then return to the Web App and head to Settings -> Configuration -> Path mappings. Add the following mappings:
84
112
85
-
113
+
| Name | Storage type | Protocol | Storage container | Mount path |
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.
121
+
Although Azure Web Apps provide an option to configure volume mounts in the container's configuration screen, this does not work with Directus.
122
+
To use the built-in App Service storage, the environment variable `WEBSITES_ENABLE_APP_SERVICE_STORAGE` must be set to true.
123
+
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.
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.
94
128
@@ -101,22 +135,20 @@ Here are few troubleshooting tips:
101
135
If you encounter connectivity problems between Directus and your Azure Database for PostgreSQL, consider the following steps:
102
136
103
137
-**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.
104
-
- **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.
138
+
-**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.
105
139
106
140
### Azure Web App Deployment Failures
107
141
108
142
In case your Azure Web App deployment fails, consider the following:
109
143
110
-
- **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.
144
+
-**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.
111
145
-**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.
112
-
- **Docker Configuration Validation:** Validate your `docker-compose.yml` file for syntax errors or inconsistencies. Incorrect configurations can lead to deployment failures.
113
-
- **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.
114
146
115
147
### Directus Interface Login Issues
116
148
117
149
If you experience problems logging into the Directus interface:
118
150
119
-
- **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.
151
+
-**Admin Credentials:** Ensure that the values of the environment variables `ADMIN_EMAIL` and `ADMIN_PASSWORD` match the credentials you are using to log in.
120
152
-**Environment Variable Changes:** If you make changes to environment variables after the initial deployment, restart the Directus container to apply the new configurations.
0 commit comments