Tugport optimizes API performance by caching Docker state in memory

Tugport, an open-source self-hosted Docker management panel, has significantly improved its API response times by shifting from real-time Docker queries to in-memory caching. Starting with version 0.1.28 released on October 26, 2026, the application serves service status, disk usage metrics, and update checks from cached values that are refreshed in the background rather than blocking user requests.

What happened

Prior to this update, the Tugport panel suffered from noticeable latency when loading project lists or server statistics. Each request for service state required the API to list containers on every connected server, a process that could take approximately 100 milliseconds per listing on a busy system. Similarly, calculating Docker disk usage involved sizing every volume, a task that could take seconds, while checking for software updates on every settings page visit risked hitting GitHub’s rate limits for unauthenticated calls.

The solution, implemented in commit b460853 via pull request #39, involves ten files and 107 lines of added code. The developer realized that the panel’s proxy component already maintained an up-to-date routing table for traffic management. By exposing this internal state to the API, the panel can answer questions about container status without querying the Docker daemon directly. For slower, less critical data like disk usage and update availability, the system now uses a stale-while-revalidate strategy, serving cached data immediately while refreshing it in the background.

Testing conducted on November 14, 2026, against the live panel running version 0.1.35, confirmed the effectiveness of these changes. The time required to list all services became statistically indistinguishable from the fastest API endpoint, which simply returns the application version. The difference in response times was smaller than the network noise, indicating that the heavy lifting of Docker introspection had been successfully removed from the critical path of user requests.

Key details

• Version release: The caching improvements were introduced in Tugport v0.1.28 on October 26, 2026.
• Service state caching: The API now reads from a shared snapshot of container states maintained by the proxy, which rebuilds its table on Docker events and every 30 seconds.
• Event handling: To ensure immediate visibility of new or deleted services, the proxy now listens for Docker create and destroy events in addition to start, stop, and health changes.
• Disk usage freshness: Docker disk usage data is cached for five minutes, with background refreshes ensuring the first request after a restart is also fast.
• Update check interval: Checks for new releases on GitHub are cached for ten minutes to avoid rate limiting and reduce external round trips.
• Performance result: On v0.1.35, the /api/services endpoint median response time was 90 ms, comparable to the 87 ms median for the lightweight /api/me endpoint.

Background

Understanding this optimization requires a look at how Docker management tools typically interact with the Docker daemon. Most panels query the Docker API directly whenever a user loads a dashboard. This involves inter-process communication and, in distributed setups, network calls to remote hosts. Operations like listing all containers or calculating the size of volumes are computationally expensive because Docker must inspect metadata for every object.

The concept used here is often called "stale-while-revalidate." Instead of making a user wait for fresh data, the system serves the last known good value immediately. Simultaneously, it triggers a background process to fetch the latest data. If the background fetch fails, the system retains the old value and waits for the next interval before trying again. This pattern is common in web browsers for caching assets but is less frequently applied to backend state management in infrastructure tools, where accuracy is often prioritized over speed.

Why it matters

For teams running their own infrastructure, dashboard responsiveness is a key factor in operational efficiency. A slow panel discourages frequent checks, potentially leading to delayed detection of issues. By reducing the latency of service listings to match that of simple metadata calls, Tugport ensures that the interface feels snappy even as the number of managed containers grows. This is particularly important for self-hosters who may run dozens of services on limited hardware, where every millisecond of CPU time saved on monitoring overhead can be allocated to actual workloads.

Furthermore, this approach reduces the load on the Docker daemon itself. Constantly listing containers and calculating disk usage can consume significant I/O and CPU resources, especially on servers with many volumes or active builds. By caching these results, Tugport minimizes its footprint on the host system, leaving more resources available for the applications it is meant to manage. This aligns with the broader goal of self-hosting: maximizing utility while minimizing administrative friction.

What you can do

• Upgrade Tugport: If you are using Tugport, ensure you are running version 0.1.28 or later to benefit from the performance improvements.
• Review caching strategies: Examine your own internal tools for similar patterns where real-time precision is not strictly necessary, and consider implementing stale-while-revalidate logic for heavy queries.
• Monitor proxy events: If you maintain similar tools, verify that your event listeners cover all lifecycle stages, including creation and destruction, to avoid stale UI states.
• Check rate limits: Audit any external API calls in your self-hosted tools, such as GitHub update checks, and implement caching to prevent hitting rate limits during peak usage.
• Benchmark your API: Use tools to measure endpoint latency under load, comparing heavy data endpoints against lightweight ones to identify potential bottlenecks.
• Consider background workers: Offload expensive computations to background tasks that update a shared state store, allowing your main API threads to remain responsive.