Enhance Docker Swarm Deployments With Stop Grace Period

The Need for Configurable stop_grace_period in Docker Swarm Services

Docker Swarm and Dokploy are powerful tools for deploying and managing containerized applications. However, a crucial aspect often overlooked is the graceful shutdown of containers, particularly for applications with long-lived connections. The default 10-second grace period in Docker can be insufficient for applications like WebSockets, TCP streams, and database connections. This leads to dropped sessions and brief downtime during rolling updates or redeployments. Imagine a scenario where a user is in the middle of a critical transaction, or a long running process is interrupted, which is not good. To solve this, the stop_grace_period setting comes to the rescue. This is how the applications can handle shutdown signals and close connections. Currently, Dokploy does not allow this configuration directly through its interface. This limitation forces users to accept connection drops or resort to manual configuration, which can be complex.

The Problem: Default Grace Period Limitations

The fundamental issue lies in the default 10-second grace period. This is often not enough for applications to gracefully shut down, leading to various issues. Consider a database connection that requires time to close connections, write data, and finalize transactions. A mere 10 seconds is usually not sufficient, leading to lost data, corrupted transactions, and service disruptions. The same is true for WebSocket connections and streaming services. These need time to notify clients and properly close connections. Without a mechanism to control the shutdown time, developers are at the mercy of the default, which is rarely adequate for many real-world applications. The lack of configurability forces developers to choose between potentially losing data or abandoning the benefits of Dokploy's streamlined deployment process. This is a significant drawback, especially for stateful applications where data integrity and continuous availability are paramount. The ability to configure the stop_grace_period is, therefore, essential for achieving true zero-downtime deployments and ensuring a seamless user experience. By allowing administrators to set a custom grace period, Dokploy can provide users with the flexibility to ensure services shut down properly without interrupting running processes.

The Solution: Implementing Configurable Grace Periods

The solution is to enable users to configure the stop_grace_period directly through the Dokploy interface. This would involve adding a new field in the UI where users can specify the desired grace period in seconds. This value would then be stored in the database, exposed through the API, and properly passed to Docker when creating or updating services. Furthermore, the application will need to ensure that the value is correctly handled as a BigInt in the backend to match Docker's API, and that it is appropriately converted when interacting with Docker. When the field is null or unset, the setting should be omitted from Docker service configuration, allowing Docker's default behavior to be applied. The implementation requires modifications to the database schema to add a new field to store the grace period value, the UI to include an input field for configuration, the backend to handle the value and pass it to Docker, and the testing framework to ensure everything works correctly. Proper testing is essential to verify that the configured value is correctly passed to Docker, that the service behaves as expected during redeployments, and that the default behavior is preserved when no value is provided.

Current Limitations and Expected Behavior

Current Behavior: A Lack of Configuration

Currently, Dokploy lacks a configuration option for Docker's stop_grace_period. When services are updated or redeployed, containers are stopped with Docker's default 10-second grace period, irrespective of the application's specific needs. This can be a major problem for applications which need more time to finish their operations, and they get abruptly terminated after 10 seconds. This is often not enough time for many applications to gracefully handle shutdown signals, close connections, or save data. The absence of this feature forces developers to compromise on the application's stability and data integrity, potentially leading to errors and a poor user experience. Imagine an application managing critical transactions. If it is terminated prematurely, the transactions may be left in an inconsistent state, leading to data corruption and potential financial losses. Similarly, applications with long-lived WebSocket connections can experience abrupt disconnections, causing disruptions in real-time communication. This limitation significantly hinders the ability to achieve true zero-downtime deployments. To solve this, Dokploy must include a configuration option that permits users to customize the stop_grace_period.

Expected Behavior: Configuring the stop_grace_period

The expected behavior is for users to configure the stop_grace_period for their Docker Swarm services directly through the Dokploy interface. This setting should be stored in the database, accessible through the API, and correctly passed to Docker during service creation or updates. Specifically, users should be able to specify a value representing the grace period, and Dokploy should ensure this value is used when stopping containers. When updating applications, the Dokploy platform should give the specified stop grace period to the Docker engine. Also, the application must confirm that this is correctly passed to the Docker engine. This ensures that the containers have enough time to finish their processes and shut down correctly. Dokploy should also handle situations where the field is left blank. In this case, the container should use Docker's default behavior. The user should be able to update, redeploy, or roll out their changes with no downtime and no disruption to the existing connections. This will ensure that applications that need more time to shut down, for example, database services, can do so without losing any data or interrupting any connections.

Technical Implementation and Verification

Implementing the stop_grace_period Configuration

The implementation of the stop_grace_period configuration requires several steps. First, the database schema needs to be updated to include a new field. This field will store the grace period value, likely in nanoseconds to match Docker's API. A user interface (UI) element must be added to enable users to set the grace period. This will be in the form of an input field within the swarm settings UI. The input field will need to include appropriate documentation to guide users on the required format. The backend code will need to be modified to retrieve the grace period value from the database, convert it, and pass it to Docker's API when creating or updating Docker Swarm services. Special care should be taken to ensure that the value is correctly handled as a BigInt in the backend code and that it is appropriately converted when interacting with Docker. The system should also handle null or empty values correctly by omitting the setting from Docker service configuration. This ensures that Docker's default behavior is preserved when no value is provided. During the deployment process, Dokploy will have to pass the grace period configuration to Docker correctly. The application should also be designed to support the graceful shutdown of its containers.

Verification and Testing

Thorough verification and testing are crucial to ensure that the implementation works correctly and does not introduce any regressions. Manual testing will involve running database migrations to add the new column to all relevant tables. Then, it will require starting the Dokploy application and navigating to the application's advanced swarm settings. The presence of the