Idle Sleep

OverviewCopy Anchor Link

GoDoxy puts containers to sleep after a period of inactivity and wakes them automatically when traffic arrives. This feature is ideal for development environments, staging servers, or services with unpredictable usage patterns.

Supported PlatformsCopy Anchor Link

• Docker
• Podman through its Docker-compatible API
• Proxmox LXCs

Supported ProtocolsCopy Anchor Link

Quick ReferenceCopy Anchor Link

How It WorksCopy Anchor Link

Sleep BehaviorCopy Anchor Link

1. Container receives no traffic for idle_timeout duration
2. GoDoxy executes stop_method on the container
3. Container dependencies are stopped in order unless another running watcher directly depends on them
4. Traffic to the route triggers wake-up sequence

Wake BehaviorCopy Anchor Link

1. Request arrives for sleeping route
2. For an HTML navigation, GoDoxy returns the loading page immediately and starts one background wake operation
3. Dependencies start first (if configured)
4. Main container starts
5. The loading page receives startup progress over server-sent events
6. GoDoxy waits up to wake_timeout for readiness, then the loading page refreshes into the active service

Non-HTML requests, and all requests when no_loading_page is enabled, wait for wake-up so GoDoxy can proxy the original request after the service becomes ready. Canceling an HTML navigation after its loading page has been returned does not cancel the shared wake operation.

Idle start, ready, sleep, pause, and error transitions appear in the WebUI Live Activity feed.

Dependency ManagementCopy Anchor Link

Containers with depends_on wake their dependencies first, including transitive dependencies. When a container sleeps, its dependencies also sleep unless another running watcher directly depends on them. Shared dependencies remain available until their last running dependent sleeps. Sleeping dependents do not keep dependencies running; traffic wakes the required dependency chain again.

Podman Compose dependencies are discovered automatically through the native Podman inspect API, including dependencies of services without their own idle timeout. This works through a direct provider connection or an agent. When using GoDoxy's socket proxy, enable CONTAINERS and use a version that allows native Podman GET inspect requests.

proxy.depends_on overrides automatic discovery. Podman's native API does not retain Compose readiness conditions, so automatically discovered dependencies use service_started. For health-based readiness, set an explicit label such as proxy.depends_on: redis:service_healthy. If native inspection fails, GoDoxy logs a warning and keeps the routes; restore API access and reload to discover the dependencies.

Condition TypesCopy Anchor Link

Control when dependencies are considered ready:

Docker Compose ExampleCopy Anchor Link

# Without conditions (implies service_started)
depends_on:
  - redis
  - postgres

# With explicit conditions
depends_on:
  redis:
    condition: service_healthy
  postgres:
    condition: service_started

Label SyntaxCopy Anchor Link

labels:
  proxy.depends_on: redis:service_healthy,postgres:service_started

Docker ConfigurationCopy Anchor Link

Enable idle sleep by adding labels to your container:

services:
  app:
    image: nginx:latest
    container_name: my-app
    labels:
      # Required
      proxy.idle_timeout: 1h30s
      # Optional
      proxy.wake_timeout: 30s
      proxy.stop_method: stop
      proxy.stop_timeout: 10s
      proxy.stop_signal: SIGINT
      proxy.start_endpoint: /start
      proxy.no_loading_page: true
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy

  redis:
    image: redis:alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  postgres:
    image: postgres:16
    # Healthcheck configured via GoDoxy health monitoring

Proxmox LXC ConfigurationCopy Anchor Link

See Proxmox Integration for detailed configuration options.

Sleep and Wake NotificationsCopy Anchor Link

Notifications are off by default. Configure providers under providers.notification, then opt an idle-sleep route in using idlewatcher.notify:

# Add inside the route's existing idlewatcher configuration
notify:
  to: [gotify, ntfy] # Names under providers.notification

Omitting the notify block inherits the global notification configuration, or stays silent when none is configured. notify: {} opts in and inherits global targets when to is omitted. If global targets are also omitted, notifications go to all current providers at send time.

To enable notifications for all routes that use idle sleep, add this to config.yml:

defaults:
  idlewatcher:
    notify:
      to: [gotify] # Use notify: {} to broadcast instead

Use notify: {} instead of the target list to send to all current providers. A route can select different providers with to or opt out with notify: {to: []}, overriding global targets. Global notify: {to: []} also disables notifications, but a route can override it with a non-empty target list. Global notification defaults do not enable idle sleep.

For Docker, use proxy.idle_notify_to: gotify,ntfy to select providers. A missing label inherits the global notification configuration. To broadcast, configure global notify: {}. proxy.idle_timeout is still required. An explicit empty string opts a container out, even when global notifications are configured:

labels:
  proxy.idle_timeout: 30m
  proxy.idle_notify_to: ""

These info-level notifications report sleep and wake transitions, with pause wording for paused containers. They do not report readiness or errors, and dependency-only containers do not send them. Initial observation, configuration reload, and watcher teardown do not send notifications.

Property ReferenceCopy Anchor Link

Core PropertiesCopy Anchor Link

Stop ControlCopy Anchor Link

With stop_method: kill, GoDoxy waits up to stop_timeout for the runtime to confirm that the container stopped or paused before stopping its dependencies. A signal such as SIGHUP may leave the container running. In that case, the operation times out and its dependencies remain running.

UI OptionsCopy Anchor Link

Duration FormatCopy Anchor Link

Use standard duration notation:

ExamplesCopy Anchor Link

Development EnvironmentCopy Anchor Link

services:
  dev-api:
    image: myapp/api:latest
    labels:
      proxy.idle_timeout: 30m
      proxy.wake_timeout: 60s
      proxy.stop_method: kill
      proxy.stop_timeout: 5s
    depends_on:
      dev-db:
        condition: service_healthy
  dev-db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s

Staging with Specific Wake EndpointCopy Anchor Link

services:
  staging-app:
    image: myapp/staging:latest
    labels:
      proxy.idle_timeout: 2h
      proxy.start_endpoint: /api/wake
      proxy.no_loading_page: false

Best PracticesCopy Anchor Link

1. Use healthchecks with service_healthy condition for reliable dependencies
2. Set appropriate timeouts based on your service startup time
3. Test wake behavior before deploying to production
4. Monitor container logs during initial setup
5. Use consistent stop signals that match your application