Django App Structure

This documentation is for Dash Enterprise.
Dash Enterprise is the fastest way to write & deploy Dash apps and
Jupyter notebooks.
10% of the Fortune 500 uses Dash Enterprise to productionize AI and
data science apps. Find out if your company is using Dash Enterprise.

This page outlines how to configure a Django app for deployment to Dash Enterprise. For running and previewing a Django app in a Dash Enterprise workspace, see the Development App page.

A few key files are required for your Django app to successfully build and deploy on Dash Enterprise. In addition to your Django project code, you’ll need a requirements.txt file to describe your app’s dependencies and a Procfile to declare what commands and processes should be run for the app.

The project structure for a Django app containing only these required files would look something like this. In this example, we have an app called polls within our Django project mysite.

|-- mysite
    |-- __init__.py
    |-- asgi.py
    |-- settings.py
    |-- urls.py
    |-- wsgi.py
|-- polls
    |-- migrations
    |-- admin.py
    |-- apps.py
    |-- tests.py
    |-- views.py
|-- manage.py
|-- Procfile
|-- requirements.txt

Note, the above structure is based on a Django project created using django-admin startproject. We used the command django-admin startproject mysite . (with a . at the end) to create the Django project within the existing directory in a workspace, meaning the Django app’s manage.py file is at the root of the project. We then added the app with python manage.py startapp polls, and added a Procfile and requirements.txt file.

You may also include optional files to further configure your app deployment, such as a project.toml file if you want to specify your Python version or run scripts when deploying changes, or an Aptfile if your app requires additional system-level packages like database drivers or extra tools in Workspaces.

A more complex project structure might look like:

|-- mysite
    |-- __init__.py
    |-- asgi.py
    |-- settings.py
    |-- urls.py
    |-- wsgi.py
|-- polls
    |-- migrations
    |-- admin.py
    |-- apps.py
    |-- tests.py
    |-- views.py
|-- manage.py
|-- Procfile
|-- requirements.txt
|-- project.toml
|-- Aptfile

A few key files are required for your Django app to successfully build and deploy on Dash Enterprise. In addition to your app’s code, you’ll need an environment.yml file to describe your app’s dependencies and a Procfile to declare what commands and processes should be run for the app.

The project structure for a Django app containing only these required files would look something like this. In this example, we have an app called polls within our Django project mysite.

|-- mysite
    |-- __init__.py
    |-- asgi.py
    |-- settings.py
    |-- urls.py
    |-- wsgi.py
|-- polls
    |-- migrations
    |-- admin.py
    |-- apps.py
    |-- tests.py
    |-- views.py
|-- manage.py
|-- Procfile
|-- environment.yml

Note, the above structure is based on a Django project created using django-admin startproject. We used the command django-admin startproject mysite . (with a . at the end) to create the Django project within the existing directory in a workspace, meaning the Django app’s manage.py file is at the root of the project. We then added the app with python manage.py startapp polls, and added a Procfile and environment.yml file.

You may also include optional files to further configure your app deployment, such as a project.toml file if you want to run scripts when deploying changes, or an Aptfile if your app requires additional system-level packages like database drivers or extra tools in Workspaces.

A more complex project structure might look like:

|-- mysite
    |-- __init__.py
    |-- asgi.py
    |-- settings.py
    |-- urls.py
    |-- wsgi.py
|-- polls
    |-- migrations
    |-- admin.py
    |-- apps.py
    |-- tests.py
    |-- views.py
|-- manage.py
|-- Procfile
|-- environment.yml
|-- project.toml
|-- Aptfile

If your project includes an environment.yml file, Dash Enterprise automatically uses the Conda buildpack,
unless your project also contains a requirements.txt file.
If your project has a requirements.txt file, Dash Enterprise always uses the pip buildpack, even if your
project also has an environment.yml file.

Required Files

Django App Code

Your Django app’s manage.py file should be in your project’s root directory. To deploy a Django app to Dash Enterprise, you’ll also need to configure your Django project’s urls.py and settings.py files.

urls.py

The Django Admin site is not currently supported for Django apps on Dash Enterprise. To avoid possible issues, remove admin URLs from your project’s main urls.py file.

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("", include("polls.urls")),
    # path('admin/', admin.site.urls),
]

You’ll also need to add the name of the app initialized on Dash Enterprise as part of the URL in urlpatterns.
See the initializing an app page for more details.

For example, here we initialize an app called my-django-app:

<img>

And we then add it to paths in our project’s main urls.py file:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("my-django-app/", include("polls.urls")),
    # path('admin/', admin.site.urls),
]

Ensure you have a path in your app that serves content at the root URL (what a user sees when they visit the app at
https://<your-dash-enterprise-server>/<your-app-name>/)

Viewer Analytics

In order to track viewer analytics of a Django app in Dash Enterprise a health route must be added.
To add a health route:

Create the health route in urls.py, where BASE_ROUTE is the base route for the app.

from django.http import HttpResponse

def health_check(request):
    return HttpResponse(b'ok')

urlpatterns = [
    path(BASE_ROUTE+'_django/health/', health_check, name='health'),
]

If your app is called my-demo-app, this health route would look like this in urlpatterns:

urlpatterns = [
    path('my-demo-app/'+'_django/health/', health_check, name='health'),
]

In the client side code, create a GET request to the new endpoint. Best practice to capture accurate viewer analytics is to add this to the root Django view. For example, using JavaScript and the Fetch API.

&lt;script&gt;
    document.addEventListener("DOMContentLoaded", function () {
        fetch("_django/health/").then((response) => response);
    });
&lt;script&gt;

Known Issue: When users visit a Django app URL without a trailing /, views are not added.

settings.py

To configure the settings.py file:

Add your Dash Enterprise hostname to ALLOWED_HOSTS. If you access the Dash Enterprise portal at https://example-dash-enterprise-5-hostname.com/portal, the hostname would be example-dash-enterprise-5-hostname.com.

python ALLOWED_HOSTS = [ <dash-enterprise-hostname> ]

Remove django.contrib.admin, django.contrib.auth, and django.contrib.sessions from INSTALLED_APPS. These are currently unsupported on Dash Enterprise.

python INSTALLED_APPS = [ # 'django.contrib.admin', <-- This line should be removed or commented out # 'django.contrib.auth', <-- This line should be removed or commented out 'django.contrib.contenttypes', # 'django.contrib.sessions', <-- This line should be removed or commented out 'django.contrib.messages', 'django.contrib.staticfiles', ]

Remove django.contrib.auth.middleware.AuthenticationMiddleware from MIDDLEWARE. This is currently unsupported on Dash Enterprise.

python MIDDLEWARE = [ 'django.middleware.security.SecurityMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.csrf.CsrfViewMiddleware', # 'django.contrib.auth.middleware.AuthenticationMiddleware', <-- This line should be removed or commented out 'django.contrib.messages.middleware.MessageMiddleware', 'django.middleware.clickjacking.XFrameOptionsMiddleware', ]

For a production app, set DEBUG = False

For more details on settings.py, see the Django documentation.

requirements.txt or environment.yml

Describe your app’s Python dependencies in a requirements.txt file if you want Dash Enterprise to use the pip buildpack, or describe them in an environment.yml file if you want Dash Enterprise to use the Conda buildpack.

Note that adding both requirements.txt and environment.yml to your app currently causes Dash Enterprise to detect only the pip buildpack, so it is not possible to use both sets of features from these files in the same app.

The requirements.txt file describes your app’s Python dependencies. Dash Enterprise uses pip to install the packages listed in your requirements.txt file.

A basic requirements.txt file looks like this:

Django==4.2.5
gunicorn==20.0.4

You’ll be declaring gunicorn as your Django app’s web server in your Procfile, so don’t forget to include gunicorn in your app’s dependencies.

We recommend including all the Python packages that your app requires, as well as their version numbers, in your requirements.txt.

You can inspect the packages and version numbers that are currently in your development environment
by running pip freeze in your terminal.
This includes all subdependencies of the packages that your app relies on.

If you don’t include the subdependencies in your requirements.txt file, then
Dash Enterprise installs the latest versions of these subdependencies when you
deploy your app for the first time. This could mean that your deployed app
uses different versions of packages than your development environment, which could
cause unpredictable errors.

If you’re developing your app locally, remember that certain versions of packages that you install on
Windows may not be available on the Linux containers that Dash Enterprise uses. The best way to avoid cross-operating system package
issues is to develop your app using Dash Enterprise Workspaces.

We recommend generating and populating your requirements.txt with:

pip freeze > requirements.txt

Adding private packages

You can supply additional options at the top of the file. See the
Adding Private Packages chapter and the
official pip requirements.txt docs
for more details.

Requirements.txt with redeploys

Redeploying your app does not reinstall dependencies unless you have changed
the requirements.txt file.

If you are including tarball files of Python packages, the filenames need to change
for Dash Enterprise to reinstall the packages. If you are developing and testing your own Python
packages, we recommend using increasing pre-release version numbers (e.g. rc-1) when you deploy
changes to your package.

Dash Enterprise uses Conda to install the packages listed under dependencies in environment.yml. The Conda buildpack uses Miniconda to create a Conda environment and install these dependencies.
This dependencies list supports a nested list of dependencies to be installed with pip.

The channels section of the environment.yml file is where you add Conda channels to search for packages.
The following example has conda-forge, which is a Conda community-led collection of packages.

In the following environment.yml file, we install pandas with Conda and Django with pip.

name: django-app
channels:
  - conda-forge
dependencies:
  - pip==21.2.4
  - pip:
      - Django==4.2.5
      - gunicorn==20.0.4

If you’re developing your app locally, remember that certain versions of packages that you install on Windows may not be available on the Linux containers that Dash Enterprise uses. We recommend only including the packages that your app imports in environment.yml and letting Conda handle subdependencies.
For example, adding pandas to your environment.yml lets Conda install the appropriate versions of Pandas subdependencies, which may differ per operating system.

The best way to avoid cross-operating system package issues is to develop your app using Dash Enterprise Workspaces.

If you’re developing your app in Workspaces, we recommend including all Python packages, their subdependencies, and their version numbers in your environment.yml file. To quickly get this complete package information, export your Conda environment to an environment.yml file by running the following command in the workspace IDE:

conda env export > environment.yml

Configuring the Python version

By default, Miniconda uses Python 3.13. You can use a different version of Python in your deployed app by adding it to your environment.yml dependencies. For example, to use Python 3.10:

name: django-app
channels:
  - conda-forge
dependencies:
  - python==3.10
  - pip==21.2.4
  - Django==4.2.5
  - pip:
      - gunicorn==20.0.4

environment.yml with redeploys

Redeploying your app does not reinstall dependencies unless you have changed
the environment.yml file.

Additional pip options

You can supply additional pip options in the pip section of the environment.yml file.

For example, you can:

Add extra-index-urls.
Install pip requirements from another file.
Install a local package.

Here is an example of setting advanced pip options within an environment.yml file.

Procfile

A Procfile is a required text file that tells Dash Enterprise which processes to run on
startup, like starting your app’s web server, scheduling jobs, and running background processes.

This file is always named Procfile—with no file extension. It must be placed in your app’s root directory and uses the following format:

&lt;process&gt;: &lt;command&gt;

Django app Procfile example

A basic Procfile for a Django app looks like this.

web: gunicorn &lt;your-django-app&gt;.wsgi

For the Django app above called mysite, this would look like this:

web: gunicorn mysite.wsgi

For more details on Django with Gunicorn see How to use Django with Gunicorn.

Optional Files

project.toml

project.toml is an optional file. To use it, place it in your app’s root directory. project.toml allows you to:

Set environment variables that are used by your app at build time. For example:
Specify a pip version for Dash Enterprise to use when building your apps. The default pip version used if you don’t specify another one in a project.toml file is 26.0.1.

Note: If you specify a pip version using environment variables in your app Settings as well as in a project.toml file, the value in the Settings takes precedence.

Note: In earlier versions of Dash Enterprise, overriding the default Python was also done with project.toml. It is now done in the Dash Enterprise App settings.
- Run predeploy and postdeploy scripts.

Pip Version

To change the pip version, specify the version you want to use in a project.toml.

A project.toml file to use pip 23.1 looks like this:

[build]
  [[build.env]]
    name = 'BP_PIP_VERSION'
    value = '23.1.*'

Dash Enterprise supports the following pip versions for deployed apps:

pip 26.2.1
pip 26.2.0
pip 26.0.1 (default)
pip 26.0.0
pip 23.3.2
pip 23.3.1
pip 23.3.0
pip 23.1.2
pip 23.1.1
pip 21.2.4
pip 21.2.3

Predeploy and Postdeploy Scripts

Add predeploy and postdeploy scripts you want to run in your app’s environment to your project.toml file.

Use predeploy scripts to install additional system dependencies, or download
files in your app or worker if that needs be done as part of app
startup or restart. This can be better than doing it in your app or as part
of your Procfile command as it is only run a single time rather than once per
container.

Use postdeploy scripts to signal that the deployment has finished.
Note that the containers are started after the postdeploy script is run, so
if your app and workers are not immediately available, they probably need the postdeploy script to complete.

If the postdeploy scripts creates files, those files aren’t accessible when
the containers are run. So, we don’t recommend using postdeploy scripts to download, cache,
or process data files in your app or worker.

Example of adding predeploy and postdeploy scripts:

[scripts]
predeploy = "predeploy.sh"
postdeploy = "postdeploy.sh"

Dash Enterprise executes files referenced under predeploy and postdeploy in the project.toml file as Bash scripts.
If you want to run a Python script, add a Bash script to your project that runs the Python script.

predeploy.sh

python predeploy.py

And then add the Bash script name in the project.toml file:

[scripts]
predeploy = "predeploy.sh"

The above example runs predeploy.sh, which then runs python predeploy.py.

Learn more in the Deployed App Environment chapter.

project.toml is an optional file that allows you to run predeploy and postdeploy scripts.

The project.toml file must be in your app’s root directory.

Example of adding predeploy and postdeploy scripts:

[scripts]
predeploy = "predeploy.sh"
postdeploy = "postdeploy.sh"

predeploy.sh

python predeploy.py

And then add the Bash script name in the project.toml file:

[scripts]
predeploy = "predeploy.sh"

The above example runs predeploy.sh, which then runs python predeploy.py.

Learn more in the Deployed App Environment chapter.

.gitignore

.gitignore is a text file that determines which files and folders are ignored by Git.
Files listed in the .gitignore are not copied to the server when you deploy your app.

venv
*.pyc
.DS_Store
.env

Aptfile

An Aptfile can be used to install system-level packages via the APT package manager. It supports:

Listing packages to download from the standard Ubuntu APT repositories.
Including links to specific .deb files.
Specifying custom APT repositories.

If an Aptfile is included in your project, an apt-get update is triggered before installing the packages.

Packages from standard APT repositories

Packages from APT repositories might include database drivers that your app requires.
In the following example we are installing unixodbc and unixodbc-dev:

unixodbc
unixodbc-dev

Specific .deb files

You can also add links to specific .deb files to be installed:

<a href="https://downloads.example.com/example.deb">https://downloads.example.com/example.deb</a>

Custom APT repositories

Your Aptfile can also contain additional APT
repositories:

:repo:deb <a href="https://apt.example.com/">https://apt.example.com/</a> example-distro main

Important: Dash Enterprise requires that custom APT repositories have a TLS/SSL certificate from a globally trusted certificate authority (CA).

To use APT packages in your apps when Dash Enterprise is internet-restricted, you need to specify a custom APT repository that Dash Enterprise has network access to. See an example in
Developing Apps when Dash Enterprise Is Internet-Restricted.

Additional Resources

See the deployment lifecycle page for details on how Dash Enterprise uses your app files to build and deploy your app.