Dokploy: Configure Stop Grace Period For Docker Swarm

by Alex Johnson 54 views

Introduction: The Need for Graceful Shutdowns in Docker Swarm

Docker Swarm has become a popular choice for orchestrating containerized applications, offering scalability and ease of deployment. However, a critical aspect often overlooked is the graceful shutdown of containers, especially when dealing with long-lived connections. Imagine a scenario where you're updating your application. Without proper handling, Docker's default 10-second grace period might not be enough. This can lead to abruptly terminated connections, which causes downtime and frustrates your users. This is where the stop_grace_period configuration comes into play. It allows containers to manage shutdown signals and close connections. This feature is especially important for applications with WebSockets, TCP streams, or database connections, as they require more time to finish ongoing processes.

Traditionally, achieving zero-downtime deployments with such applications has been a challenge. Developers would often be forced to employ complex workarounds or manual intervention. Dokploy aims to simplify this process, but it currently lacks a crucial configuration option. This feature empowers developers to deploy their applications seamlessly, while maintaining a smooth user experience. This article explores the current state of Dokploy's Docker Swarm integration, the proposed solution to incorporate stop_grace_period, and the benefits this change will bring.

The Problem: Dokploy's Current Limitations

Currently, Dokploy doesn't expose any way to configure the stop_grace_period setting for Docker Swarm services. This means that when an application is updated or redeployed, containers are stopped with the default 10-second grace period regardless of your app's needs. This can be problematic for applications needing a longer time for graceful shutdowns. Users are forced to either accept dropped connections during deployments or bypass Dokploy's streamlined application mode. This forces teams to choose between the ease of use of Dokploy and the need for zero-downtime deployments.

The Proposed Solution: Implementing stop_grace_period Configuration in Dokploy

The solution is to enable users to configure the stop_grace_period directly through Dokploy's interface. This setting will be stored in the database, exposed via the API, and passed to Docker when creating or updating services. Specifically:

  • Database Integration: A new database field will store the stop_grace_period value (in nanoseconds, which matches Docker's API). This field will be available for applications and all database service types.
  • UI Enhancement: The swarm settings UI will include an input field for configuring the stop_grace_period. Helpful documentation about the expected format will be included.
  • Docker API Integration: When creating or updating Docker Swarm services, the configured stop_grace_period will be passed correctly to Docker's API.
  • Data Handling: The value will be handled correctly as a BigInt in TypeScript and converted appropriately when interfacing with Docker.
  • Default Behavior: When the field is null or unset, the setting will be omitted from the Docker service configuration, allowing Docker's default behavior (10 seconds).

This enhancement offers several benefits:

  • Zero-Downtime Deployments: Allows applications to gracefully handle shutdowns and maintain active connections during updates.
  • Improved User Experience: Minimizes disruption for end-users, ensuring a smoother application experience.
  • Simplified Configuration: Provides an easy-to-use interface within Dokploy to configure graceful shutdown behavior.
  • Flexibility: Supports applications with various needs for shutdown times.

Implementation Details and Acceptance Criteria

This feature requires several key steps for successful implementation. The following are the acceptance criteria and detailed steps needed to achieve the required behavior.

  • Database Migration: Run the database migration to add the new column to all relevant tables. This will store the stop_grace_period value, ensuring it persists across deployments.
  • User Interface: Start the Dokploy application and navigate to an application's advanced swarm settings. Verify that a