traefik-lazyloader

This small app will automatically start and stop docker containers based on access, for instance, via traefik.

How it Works

It works by acting as the fallback-route for the containers. For instance, if you have example.com as a container you want to lazy-load, you add the container, as well as this lazyloader that would act as a lower-priority router for the same route. If the host is accessed, the lazyloader will work to boot up the container and redirect the user as soon as it's responsive.

It then monitors the container's network interface. If the network is idle for X minutes, it will stop the container.

Quick-Start

docker-compose

version: '3.5'

services:
  # Example traefik proxy (Don't need if you already have something set up!)
  reverse-proxy:
    image: traefik:v2.4
    command:
      - --api.insecure
      - --providers.docker
      - --providers.docker.defaultRule=Host(`{{.Name}}.example.com`)
      - --entryPoints.web.address=:80
      - --entryPoints.web.forwardedHeaders.insecure
      - --providers.docker.exposedByDefault=false
    restart: always
    ports:
      - "80:80"     # The HTTP port
      - "8080:8080" # The Web UI (enabled by --api)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # So that Traefik can listen to the Docker events

  # Lazy-loader manager
  lazyloader:
    #build: . # Uncomment to build from source
    image: ghcr.io/zix99/traefik-lazyload:1
    labels:
      - traefik.enable=true
      - "traefik.http.routers.lazyload.priority=-100" # Lower router priority. Would only be hit if the app isn't running
      - "traefik.http.routers.lazyload.rule=Host(`whoami.example.com`, `lazyloader.example.com`)"
    environment:
      TLL_STOPATBOOT: true                   # Stop all lazyloaded containers at boot (great for an example)
      TLL_STATUSHOST: lazyloader.example.com # This hostname will display a status page. Disabled by default
    networks:
      - traefik-bridge
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Must access docker

  whoami:
    image: containous/whoami
    networks:
      - traefik-bridge
    labels:
      - traefik.enable=true
      - "traefik.http.routers.lazywhoami.rule=Host(`whoami.example.com`)"
      - lazyloader=true
      - lazyloader.stopdelay=30s # Overrides the default

networks:
  traefik-bridge:
    external: true
    name: traefik-bridge

You can run docker-compose up on the above for a quick-start. You will need to alter the domains as needed.

Config

Configuration uses viper and can be specified by either overwriting the config.yaml file or via environment variables with the TLL_ prefix (Traefik lazy loader)

# What port to listen on
listen: :8080

# If set, when access via this hostname, will display status page
statushost: ""

# Enable debug logging
verbose: false

# if true, will stop all running tagged containers when the lazyloader starts
stopatboot: false

# which splash-page asset to use
splash: splash.html

# Container defaults
stopdelay: 5m # How long to wait before stopping container
pollfreq: 10s # How often to check

# This will be the label-prefix to look at settings on a container
# usually won't need to change (only if running multiple instances)
labelprefix: lazyloader

Labels

Use these on containers you want to be lazy-loaded.

• lazyloader=true -- (Required) Add to containers that should be managed
• lazyloader.stopdelay=5m -- Amount of time to wait for idle network traffick before stopping a container
• lazyloader.waitforcode=200 -- Waits for this HTTP result from downstream before redirecting user. Can be comma-separated list
• lazyloader.waitforpath=/ -- Checks this path downstream to check for the process being ready, using the waitforcode
• lazyloader.waitformethod=HEAD -- Method to check against the downstream server
• lazyloader.hosts=a.com,b.net,etc -- Set specific hostnames that will trigger. By default, will look for traefik router

Dependencies

• lazyloader.needs=a,b,c -- List of dependencies a container needs (will be started before starting the container). Can only be specified on a lazyloader=true container
• lazyloader.provides=a -- What dependency name a container provides (Not necessarily a lazyloader container)
• lazyloader.provides.delay=5s -- Delay starting other containers for this duration

License

Copyright (C) 2023 Christopher LaPointe

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.