Django deployments without downtime: static files and migrations

This blog post is based on a product presentation by Antonis Kalipetis, Staff Engineer at SymfonyCon 2023, about Upsun's experience with Nix. We utilized ChatGPT for transcription and to enhance the grammar and syntax.

Django deployments have evolved since the framework's early days. While Django migrations were introduced in version 1.6 to simplify our lives, modern deployment patterns, such as rolling updates and horizontal scaling, have introduced new complexities that developers need to understand and plan for. In a live workshop, Antonis walked through what actually breaks during deployments and how to prevent it.

Understanding Django deployment architecture

Every Django application deployment consists of several key components working together. At the front, you have a proxy server - typically Nginx, Apache, or newer options like Caddy and Traefik. This proxy handles TLS termination, domain routing, and redirects. Behind it sits your application server, commonly Gunicorn or Uvicorn for asynchronous applications. Supporting these are a cache layer (such as Redis or Memcached) and a database (PostgreSQL, MySQL, or increasingly SQLite, for certain use cases).

This architecture works well for single-server deployments, but modern applications often run across multiple servers with rolling updates, creating scenarios where different versions of your application run simultaneously.

The static assets challenge

When you develop Django applications locally, manage.py runserver handles static file serving automatically. In production, however, this approach becomes problematic. Python application servers are designed to handle one request at a time (with some exceptions for ASGI), making them unsuitable for serving static content, such as CSS, JavaScript, and images.

The problem multiplies with scale

The real challenge arises when multiple application servers are running different versions of your code. Consider this scenario: you update your CSS with a new brand color and deploy using Django's ManifestStaticFilesStorage. This storage backend creates hashed filenames, such as app.a1b2c3d4.css to enable permanent caching.

During a rolling deployment, you might have:

• Server A is running the old version with app.old123.css
• Server B is running the new version with app.new456.css

If a user's request for the new CSS file gets routed to the old server, they'll receive a 404 error, breaking the page styling.

Solutions for static asset management

External storage: Upload static files to services like Amazon S3 or similar cloud storage. This ensures all versions of your application can access the same static files.

Proxy-level caching: Configure your proxy server (Nginx, etc.) to cache static files for a reasonable duration. This creates a buffer during deployments where old files remain available while new ones propagate.

Shared file systems: Mount the static directory across all servers so both old and new application versions can serve files from the same location.

WhiteNoise middleware: This Python library serves static files directly from your Django application with efficient caching headers, though it does use application server resources.

Schema migration complexities

Django migrations are powerful, but they require careful planning in multi-version environments. The presenter demonstrated this with a practical example using a Bigfoot sighting reporting application.

The compatibility problem

Adding a new field to a model seems straightforward, but consider what happens when you add a required field with a default value:

# New field added

gdpr_accepted = models.BooleanField(default=False)

After running migrations, the new application version is aware of this field, but the old version is not. When the old version tries to save a record, it fails because the database expects the gdpr_accepted field, but the old code doesn't provide it.

Django 5's database defaults

The presenter highlighted Django 5's new db_default parameter as a solution:

gdpr_accepted = models.BooleanField(db_default=False)

With db_default, the database itself handles the default value, not the Python code. This means old application versions can successfully save records even without knowledge of the new field.

Migration strategy best practices

• Forward and Backward Compatibility: Design migrations that work with both the current and previous versions of your application code.
• Multi-Step Deployments: For complex schema changes, consider deploying in multiple stages:

1. Add the new field as nullable
2. Deploy code that handles both old and new schemas
3. Populate existing records
4. Make the field non-nullable if needed

• Data Migration Considerations: When you need to update existing data, create separate data migrations that can run safely alongside the old application code.

The rolling update challenge

Rolling updates create a temporary state where multiple versions of your application run simultaneously. This requires careful coordination between:

• Migration timing: When to apply database changes
• Code deployment: Ensuring compatibility between versions
• Static file distribution: Managing asset versions across servers
• Rollback planning: Having a clear strategy when things go wrong

Rollback reality check

While Django makes rolling back migrations seem simple with manage.py migrate app_name 0001, production rollbacks are rarely that straightforward. The presenter emphasized from experience that rollbacks often encounter unexpected issues, making prevention through careful planning more valuable than relying on rollback capabilities.

Practical deployment strategies

• Environment Parity: Ensure your staging environment closely mirrors production, including multi-server setups when possible.
• Feature Flags: Use feature flags to deploy code without immediately exposing new functionality, allowing you to separate code deployment from feature activation.
• Blue-Green Deployments: Maintain two identical production environments and switch traffic between them, eliminating the multi-version complexity entirely.
• Canary Releases: Gradually route traffic to new versions, allowing you to catch issues before they affect all users.

Platform solutions

Modern Platform-as-a-Service providers like Upsun address many of these challenges through:

• Automated static file handling with shared storage
• Managed database migrations with timing controls
• Built-in caching layers at the proxy level
• Tools for coordinating multi-service deployments

However, understanding the underlying challenges remains crucial even when using managed platforms.

Key takeaways

Django's built-in tools, such as migrations and static file management, are powerful, but they require thoughtful application in production environments. The complexity increases significantly when you move from single-server deployments to horizontally scaled, continuously deployed applications.

Success requires:

• Planning migrations for compatibility across application versions
• Implementing robust static file serving strategies
• Understanding the timing and coordination of rolling deployments
• Having realistic rollback procedures
• Testing deployment processes in staging environments

As Django applications grow and deployment patterns become more sophisticated, developers must evolve their understanding beyond local development patterns. The framework provides the tools, but successful production deployments require careful orchestration of these tools within your specific infrastructure context.

While Django continues to make our development lives easier, production deployment remains an area where careful planning and understanding of the underlying systems pays dividends in application reliability and user experience.