Lazy Containers

Many self-hosted applications are only used a few minutes a day, yet they hold on to memory and CPU around the clock. A lazy container is a ServApp that Cosmos stops when nobody uses it, and starts again by itself the moment someone opens its URL.

You keep the URL, the bookmark and the icon on your home page. The only difference is that the first visit after a quiet period takes a few seconds longer, while the application starts.

Enabling it

Go to ServApps, open the container, and on the Overview tab tick Lazy start (stop when idle), right below Auto Update Container.

An Idle timeout selector appears: 15m, 30m, 1h (the default), 3h, 12h or 24h. This is how long the application must go without any visit before Cosmos stops it.

That is all. Cosmos takes over starting and stopping the container, so its restart policy is set to Never: otherwise Docker would restart what Cosmos just put to sleep. If you turn lazy start off later, set the restart policy back to what you want in the Docker tab.

The container needs a URL pointing at it, since visits to that URL are what wakes it up. If Cosmos itself runs inside Docker, it needs to use host networking (which is the recommended setup).

What your visitors see

When someone opens the URL of a sleeping application, Cosmos starts the container and holds the request until the application is ready. Most applications are up within a few seconds, and the visitor simply gets the page, a little slower than usual.

If the application takes longer than 30 seconds, the browser shows a Starting the application page that refreshes by itself until the application answers. Scripts and API clients receive a temporary error asking them to retry shortly.

Cosmos knows the application is ready when its Docker healthcheck says so, or, for containers without a healthcheck, when its port starts answering.

What keeps a container awake

• Every request through its URL resets the idle timer.
• A request in progress keeps the container awake for as long as it lasts, so long downloads, video streams and websockets are never cut.
• TCP URLs work the same way: a new connection wakes the container, and each open connection keeps it awake.

Only traffic going through a Cosmos URL counts. If you reach the container by a port published directly on the host, or from another container, Cosmos does not see it and may stop the container while you are using it. Browsing the Cosmos interface never wakes your containers: the home page shows their icon without starting them.

In the interface

A sleeping container shows the Dormant status in the ServApps list, instead of Exited. Its URLs show a hollow grey dot, with the tooltip Container is sleeping (lazy start).

You can still start it by hand with the usual buttons; Cosmos will stop it again once the idle timeout has passed.

Each wake-up and each stop is recorded in the events of the container, and the monitoring keeps a count of cold starts per container. If a container fails to wake up three times in a row, Cosmos raises a Lazy container failed to wake up warning so you can look at its logs.

From a compose file

Lazy start is driven by labels, so you can enable it directly from a Cosmos-Compose file:

{
  "services": {
    "myapp": {
      "image": "myapp:latest",
      "container_name": "myapp",
      "labels": {
        "cosmos-lazy": "true",
        "cosmos-lazy-idle": "30m",
        "cosmos-lazy-start-timeout": "90s"
      }
    }
  }
}

• cosmos-lazy: set to true to make the container lazy.
• cosmos-lazy-idle: the idle timeout, as a duration (15m, 1h, 1h30m). 1h by default. Any duration works here, not only the ones offered in the interface.
• cosmos-lazy-start-timeout: how long Cosmos gives the application to become ready once started. 60s by default; raise it for applications that are slow to boot.

Choosing what to make lazy

Good candidates are applications you open from time to time: admin tools, a wiki, a photo editor, a dashboard, a development environment.

Keep always-on anything that works in the background without being visited: download clients, media servers scanning a library, home automation, anything running scheduled jobs or receiving data from other devices without going through a Cosmos URL.

With Cosmos Pro, the same mechanism lets a deployment scale down to zero, and powers Cloud Functions.