The short answer

To deploy a Django app, stop using manage.py runserver. Run a WSGI or ASGI server on 0.0.0.0 and the port the platform gives you, with DEBUG = False, a stable SECRET_KEY, and ALLOWED_HOSTS set to the real hostname. Collect static files, put user uploads on durable storage, and run migrations once as a release step.

Django hosting on Unbroker is a Dockerfile service, and that path requires Pro. The product page is Deploy Django. The steps are Deploy a Django application.

runserver is not the production server

runserver starts a lightweight development server. By default it listens on port 8000 at 127.0.0.1. Django prints a warning that this is a development server and that a production setting needs a WSGI or ASGI server. The deployment checklist says the same thing: switch away from manage.py runserver. The command reference is runserver.

The development server reloads Python code as you edit, and it serves static files when django.contrib.staticfiles is enabled. Those are development conveniences. They are not a production process.

Development (runserver)Production server
ProcessDjango’s development server. Not for production.A WSGI server such as Gunicorn, or an ASGI server such as Uvicorn.
Address127.0.0.1:8000 unless you pass another address. Other machines cannot reach that default.0.0.0.0 and the supplied PORT. The Unbroker sample falls back to 8000 only when PORT is empty.
Static filesServed by runserver when staticfiles is enabled.collectstatic, then WhiteNoise or another host. Gunicorn alone does not serve them.
SettingsDEBUG is usually on.DEBUG = False, a secret SECRET_KEY, and ALLOWED_HOSTS for the real hostname.
MigrationsOften applied by hand on one machine.Once, as a release step, not when each copy of the app starts.

WSGI or ASGI

Django’s primary deployment platform is WSGI. startproject creates wsgi.py with an application callable, and runserver uses that WSGI app. It does not use asgi.py. The overview is How to deploy with WSGI.

Gunicorn is the WSGI server the Unbroker guide uses. Django’s getting-started command is gunicorn myproject.wsgi. That starts one process and one thread on 127.0.0.1:8000. The reference is How to use Django with Gunicorn.

Use ASGI when the project is deployed through asgi.py. Django’s Uvicorn command is python -m uvicorn myproject.asgi:application, which also listens on 127.0.0.1:8000 in that simplest form. For production, Django documents running Uvicorn under Gunicorn with -k uvicorn_worker.UvicornWorker. The reference is How to use Django with Uvicorn and How to deploy with ASGI.

The Unbroker guide assumes a WSGI application and shows Gunicorn. If you switch to the ASGI command, keep the same bind: every interface, and the port you are given.

Settings that have to change

Follow the Django deployment checklist and run python manage.py check --deploy with the production settings. The Unbroker guide asks for the same check.

Set DEBUG = False. Django says you must never enable debug in production. With debug on, error pages can expose source, local variables, and settings.

Read SECRET_KEY from the environment. The checklist shows os.environ["SECRET_KEY"] as one way. Keep the same value across deploys. The Unbroker guide says a different secret on every startup invalidates signed data and sessions. Do not commit it. How variables are scoped is Environment variables and secrets.

Set ALLOWED_HOSTS to the hostname the service actually answers on. When DEBUG is False, Django does not work without a suitable value. A request whose host is not allowed raises DisallowedHost. That exception is a SuspiciousOperation. If nothing else handles it, Django responds with the bad request view: a “Bad Request” message, status 400, and only when DEBUG is False. The exception list is SuspiciousOperation. The guide says a DisallowedHost error points at host configuration. Do not fix it by allowing every host.

Add the final HTTPS origins to CSRF_TRUSTED_ORIGINS where the app needs them. The default is an empty list. An entry is an origin, such as https://example.com, not a bare hostname. The setting is CSRF_TRUSTED_ORIGINS. A CSRF failure needs an origin and cookie review. Do not disable CSRF protection.

Once the site is on HTTPS, the checklist also says to set CSRF_COOKIE_SECURE and SESSION_COOKIE_SECURE to True, so those cookies are not sent over plain HTTP.

SECURE_PROXY_SSL_HEADER matters when TLS ends at a proxy and Django would otherwise see the request as HTTP. The default is None. Django says to set it only if you control that proxy, the proxy strips the header from incoming requests, and the proxy sets the header itself for requests that arrived over HTTPS. The Unbroker Django guide does not name a header to trust. Do not set an example value until you know the proxy in front of the app meets those conditions. A redirect loop after turning on SECURE_SSL_REDIRECT is the symptom Django documents for this case. The setting is SECURE_PROXY_SSL_HEADER.

A custom domain is a later step, and it requires Pro. When it is ready, add that hostname to ALLOWED_HOSTS and its HTTPS origin to CSRF_TRUSTED_ORIGINS. DNS and the certificate are Custom domain and HTTPS.

Static files and media

In production you define STATIC_ROOT. collectstatic copies static files there. The development server will not do that job for you. The checklist entry is STATIC_ROOT and STATIC_URL, and the deployment page is How to deploy static files.

Gunicorn does not serve the collected files. Pick a strategy. WhiteNoise, added to MIDDLEWARE directly after Django’s SecurityMiddleware, serves them from the Django process. Run collectstatic at the stage that strategy needs. If that command runs while the image is built, use settings that are safe at build time. WhiteNoise’s steps are Using WhiteNoise with Django. An external static host is the other option the Unbroker guide names.

User uploads are a different directory. MEDIA_ROOT holds files from users, and Django treats them as untrusted. The helper that serves MEDIA_ROOT in development is not a production file server, and the docs show it only when DEBUG is on. On Unbroker, uploaded media goes to persistent storage or object storage, separate from collected assets.

A persistent volume is one absolute path on one service. Files written only to the container filesystem should be treated as temporary, because a deploy, restart, or reschedule can replace that container. A volume-backed service runs one replica. The volume can grow, up to 50 GB, and it cannot shrink. Deleting the service deletes the volume. Volumes require Pro. That limit is persistent volumes and Persistent storage and backups.

If more than one replica must see the same upload, use object storage. The volume is not a shared disk for several replicas.

Database and migrations

Configure Django’s DATABASES setting for the PostgreSQL database you chose. Django does not parse DATABASE_URL by itself. Use the configuration you already have, or a parser you installed on purpose. The engine, name, user, password, host, and port are the connection fields Django documents for PostgreSQL.

On Unbroker there are two PostgreSQL paths. An Apps node is a private database service in the project. A managed cluster is operated as a database host. You still own the schema and the migrations. Store the credentials in the service’s runtime variables. Revealing a connection string can print a secret, so keep that output out of the repo, the chat log, and the error page. The connection steps are Connect your application to PostgreSQL. Operating the database is Postgres in production. Managed databases require Pro.

Run migrations once, as a controlled release step, with the runtime credentials. Do not put them in the image build. Do not run them from every web process, or those processes can compete. Test on a disposable copy before production. The Unbroker release step is the pre-deploy command, and migration commands require Pro. What a code rollback does not undo is Database migrations on deploy.

Background tasks

Email, indexing, and other queue work do not belong in the web process. Put the consumer in its own worker service, with its own start command and its own logs. A worker has no inbound HTTP and no public URL. Worker services require Pro, and they run one replica.

Celery and RQ are examples of that consumer. The worker guide does not name either library. It says the start command should launch the consumer and stay up while it waits for jobs. A script that handles one item and exits is a scheduled job or a one-off command, not a worker. Scheduled jobs require Pro. The split is Background workers and cron jobs, and the steps are Deploy a background worker.

How this works on Unbroker

Create a Dockerfile repository service in Cloud. Include Gunicorn and the database driver in the locked requirements. The guide’s command, for a project whose WSGI module is config.wsgi, is:

gunicorn config.wsgi:application --bind 0.0.0.0:${PORT:-8000} --workers 1 --access-logfile - --error-logfile -

Change config.wsgi to your module. Bind 0.0.0.0, not 127.0.0.1. Listen on the PORT you are given. The ${PORT:-8000} fallback applies only when PORT is empty. When you do not choose a port, a new repository service uses 3000, and Unbroker sets PORT to the service port unless you set PORT yourself. A PORT you set replaces that value, so do not point it at a different port than the service port. The failure guide lists PORT and 0.0.0.0 under health and routing.

Set production variables, confirm the database is reachable, run the migration step, and deploy. Then open a public page, sign in, submit a form, load a static file, and upload a media file if the app has one.

The guide starts from a working Django project, locked Python dependencies, a production database, and Unbroker Pro. Dockerfile builds are not available on Free. Migration commands, worker services, persistent volumes, managed databases, and custom domains are Pro as well. Dockerfile builds are outside Serverless, so this service is not on the sleep-and-wake path that Free HTTP services use. Service types are Service types.

Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Plan rows are on pricing and in Plans.

Checklist

  1. Leave runserver out of the production start command.
  2. Run Gunicorn for a WSGI app, or an ASGI server if you deploy asgi.py. Bind 0.0.0.0 and the supplied PORT.
  3. Set DEBUG = False. Load a stable SECRET_KEY from the environment.
  4. Set ALLOWED_HOSTS to the real hostname. Add HTTPS origins to CSRF_TRUSTED_ORIGINS where the app needs them.
  5. Run python manage.py check --deploy with production settings.
  6. Set STATIC_ROOT, run collectstatic, and serve those files with WhiteNoise or another host. Gunicorn does not.
  7. Put user uploads on a volume or on object storage. A volume keeps the service at one replica.
  8. Run migrations once, as a release step, not in the image build and not in every web process.
  9. Put a queue consumer on its own worker. Use a scheduled job for a command that exits.
  10. Deploy the Dockerfile service on Pro. Check a page, a login, a form, a static file, and a media upload.

FAQ

Can I use runserver in production?

No. Django's deployment checklist says to switch away from manage.py runserver. The runserver command is a lightweight development server. It has not gone through security audits or performance tests, and Django says it is unsuitable for production. It listens on 127.0.0.1:8000 by default, reloads code, and serves static files when staticfiles is enabled. Use a production WSGI or ASGI server instead. Unbroker's Django guide says runserver is not the production start command.

Should I use gunicorn or uvicorn for Django?

Use Gunicorn for a normal WSGI project. Django's primary deployment platform is WSGI, and the Unbroker guide assumes a WSGI app and shows Gunicorn. Use an ASGI server when you deploy asgi.py, for example Uvicorn. Django's Uvicorn page also shows running Uvicorn under Gunicorn with the Uvicorn worker. Either way, bind 0.0.0.0 and the PORT you are given. The simplest documented Gunicorn and Uvicorn commands listen on 127.0.0.1:8000, which other machines cannot reach.

Why do I get a Bad Request (400) after deploying Django?

Check ALLOWED_HOSTS. When DEBUG is False, Django does not work without a suitable ALLOWED_HOSTS value. A host that is not allowed raises DisallowedHost, a SuspiciousOperation. If that exception is not handled elsewhere, Django treats the request as a bad request. The bad request view produces a Bad Request message with status 400, and it is used only when DEBUG is False. Put the real service hostname in ALLOWED_HOSTS. Do not allow every host, and do not turn DEBUG back on to hide the page.

How do I serve static files in Django production?

Set STATIC_ROOT and run collectstatic. The development server serves static files for you. Gunicorn does not. WhiteNoise, configured in Django, can serve the collected files. An external static host is the other option the Unbroker guide names. Keep user uploads out of that directory.

When should Django migrations run on deploy?

Once, as a release step, with the runtime credentials, before the new version takes traffic. The Django guide says to avoid putting migrations in the image build and to avoid running competing migrations in every web process. On Unbroker that release step is the pre-deploy command, and migration commands require Pro. Test the migration on a disposable copy first.

Where should uploaded media files go?

On persistent storage or object storage, not on the container filesystem. A deploy, restart, or reschedule can replace the container, and files written only there should be treated as temporary. Keep media separate from collected static files. A volume-backed service on Unbroker has one replica. The volume can grow up to 50 GB and cannot shrink.

How do I deploy a Django app on Unbroker?

Create a Dockerfile repository service, include Gunicorn and your database driver, and set production variables. The guide's command binds Gunicorn to 0.0.0.0 and PORT, with one worker, and falls back to 8000 only when PORT is empty. The path requires Pro. Dockerfile builds are not available on Free. The steps are Deploy Django and the Django guide.