Configure Stop Grace Period For Docker Swarm In Dokploy

by Alex Johnson 56 views

Are you struggling with dropped connections during Docker deployments? Do you need more control over how your containers shut down? This article guides you through adding a stop_grace_period configuration to Dokploy for Docker Swarm services, ensuring graceful shutdowns and zero-downtime deployments.

The Motivation Behind Graceful Shutdowns

When deploying applications that rely on long-lived connections, such as WebSockets, TCP streams, or database connections, the default 10-second grace period provided by Docker can be insufficient. During rolling updates or redeployments, Docker might forcefully kill containers before they have the opportunity to properly drain active connections. This abrupt termination leads to dropped sessions and brief downtime, negatively impacting the user experience.

Think of it like this: Imagine you're on a phone call, and suddenly, the line is cut off without warning. That's what happens when a container is forcefully killed before it can gracefully shut down. To avoid this abrupt disconnection, we need to extend the time Docker waits before forcefully stopping a container, allowing it to close connections cleanly and prevent data loss. Configuring the stop_grace_period becomes essential for maintaining a seamless user experience, especially in stateful applications where data consistency is paramount.

Docker Swarm and Docker Compose recognize this need and allow you to configure the stop_grace_period. However, Dokploy, in its current state, lacks a direct way to configure this setting through its interface. This limitation forces teams to choose between accepting connection drops during deployments or abandoning Dokploy's streamlined application mode in favor of manually managing Compose/Swarm files.

Adding the stop_grace_period configuration option to Dokploy bridges this gap, empowering you to achieve true zero-downtime deployments for stateful applications while preserving the simplicity and efficiency of Dokploy's deployment workflow. This enhancement provides the necessary control over container shutdowns, ensuring that applications can gracefully terminate connections and maintain data integrity during deployments.

Understanding the Current Behavior

Currently, Dokploy does not offer any configuration options for Docker's stop_grace_period setting. Consequently, when services are updated or redeployed, containers are stopped using Docker's default 10-second grace period, irrespective of the application's specific requirements.

To illustrate this limitation, consider the following scenario:

  1. Deploy an application in Dokploy that maintains long-lived WebSocket connections or database connections.
  2. Navigate to the application's advanced settings or Swarm configuration panel.
  3. Search for an option to configure the graceful shutdown timeout or stop grace period.
  4. Observe that no such configuration option exists.
  5. Initiate a redeployment or rolling update of the service.
  6. Observe that active connections are dropped after 10 seconds when the container is forcefully terminated.
  7. This outcome is undesirable because applications requiring longer shutdown times (e.g., 30-60+ seconds) lack the means to configure this behavior through Dokploy's interface.

This limitation highlights the need for a configurable stop_grace_period in Dokploy. Without it, applications with long-lived connections are vulnerable to disruptions during deployments, potentially leading to data loss and a degraded user experience. By providing a way to adjust the shutdown timeout, Dokploy can better support a wider range of applications and deployment scenarios.

Expected Behavior: Configuring the Stop Grace Period

The ideal scenario is that users should be able to configure the stop_grace_period for their Docker Swarm services directly through Dokploy's user interface. This configuration should then be stored in the database, exposed through the API, and correctly passed to Docker when creating or updating services. This empowers users to fine-tune the shutdown behavior of their containers, ensuring a smooth and graceful transition during deployments.

Imagine a user accessing the Dokploy interface and finding a dedicated field for configuring the stop_grace_period. They can enter a value that corresponds to the desired shutdown time, giving their application ample time to close connections and save data. This setting is then seamlessly integrated into the Docker service configuration, ensuring that the container respects the specified grace period during shutdowns.

Here's a breakdown of the expected behavior:

  • User-Friendly Interface: A clear and intuitive input field within Dokploy's settings allows users to specify the stop_grace_period in seconds.
  • Persistent Storage: The configured value is securely stored in the database, ensuring that it persists across deployments and updates.
  • API Integration: The stop_grace_period is accessible through Dokploy's API, enabling programmatic configuration and automation.
  • Docker Compatibility: The configured value is correctly passed to Docker's API when creating or updating services, ensuring that the container shutdown behavior aligns with the user's specifications.

By implementing these features, Dokploy empowers users to manage the shutdown behavior of their containers effectively, contributing to more reliable and robust deployments.

Verification: Ensuring the Implementation Works

To guarantee that the new stop_grace_period configuration works as expected, a series of verification steps are necessary. These steps involve manual testing and inspection of the Docker service configuration.

Manual Testing:

  1. Database Migration: Begin by running the database migration to add the new column to all relevant tables. This ensures that the database can store the stop_grace_period value for applications and database service types.
  2. Dokploy Application Startup: Start the Dokploy application and navigate to an application's advanced Swarm settings. This allows you to access the configuration interface.
  3. UI Verification: Verify that a "Stop Grace Period" input field appears with helpful tooltip documentation. This confirms that the user interface is correctly displaying the new configuration option.
  4. Value Input and Saving: Enter a value (e.g., 30000000000 for 30 seconds) and save the settings. This tests the ability to input and store the stop_grace_period value.
  5. Deployment/Update Trigger: Deploy or update the application. This initiates the process of applying the new configuration to the Docker service.
  6. Docker Service Inspection: Inspect the created Docker service using docker service inspect <service-name> and verify that the StopGracePeriod field matches your configured value. This confirms that the configuration has been successfully passed to Docker.
  7. Null/Empty Value Testing: Test with a null/empty value and verify that the field is omitted from the Docker service configuration. This ensures that Docker's default behavior is preserved when no stop_grace_period is specified.

By following these manual testing steps, you can thoroughly verify that the stop_grace_period configuration is working correctly and that the application is behaving as expected during shutdowns.

Hints and Testing Approach

For local development and testing, you don't necessarily need a remote server. If you have Docker installed on your PC, you can deploy and test Dokploy locally. Remote servers and the Dokploy server use the same code at deployment time for applications, ensuring consistency across environments. Just hit deploy, and it should work locally.

Important: Make sure to install the builders first. Refer to the Installation Guide for detailed instructions.

Testing Approach:

To properly test your changes, consider these scenarios:

  • Application Testing:
    • Create an empty application.
    • Test saving different values for Stop Grace Period, including empty values.
    • Deploy a simple image (e.g., whoami) with the application.
    • Verify the Stop Grace Period behavior during deployment and shutdown.
  • Database Testing:
    • Create a MySQL database and deploy it.
    • Change the Stop Grace Period setting.
    • Re-deploy and verify the changes persist correctly.

By following these testing approaches, you can ensure that the stop_grace_period configuration is functioning correctly across various application and database scenarios. This comprehensive testing strategy contributes to a more robust and reliable implementation.

By implementing the stop_grace_period configuration in Dokploy, you empower users to manage container shutdowns effectively, leading to more stable and reliable deployments. This feature is crucial for applications with long-lived connections, ensuring a seamless user experience and preventing data loss during updates and redeployments.

For more information about Docker Swarm and graceful shutdowns, visit the official Docker documentation.