From 065d367504ae3e9b7141f7a7daa6fe1db7aeb4e7 Mon Sep 17 00:00:00 2001 From: flu0r1ne Date: Tue, 12 Sep 2023 05:19:00 -0500 Subject: Add README and script --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d22a5b --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +# Docker Auto Rebuild Script (`rbuild`) + +> Note: This script is experimental. Contributions are welcome. + +This short Python script automatically rebuilds Docker Compose deployments to apply security updates +and pull new images, ideally from a stable release if the application is well containerized. Docker +Compose is frequently used for small one-off deployments in CI/CD pipelines, small to medium businesses, +and self-hosted services. In such scenarios, utilizing a full-fledged container registry and monitoring +service like `Watchtower` might be excessive. This is a lightweight, zero-dependency script that can be +scheduled using `cron` or a similar task scheduler. It triggers a rebuild if `BUILD_TTL` seconds have passed, +if the configuration file changes, or if the `--force-rebuild` flag is set. The script also cleans up old containers +after rebuilding. It assumes that security updates will be applied during the build process and invalidates the image +cache to ensure a rebuild. + +However, this script has *numerous limitations*. It is not suitable for environments requiring high availability, as +it lacks support for rolling updates and rollbacks in the event of container failures. Additionally, it doesn't offer +auto-scaling capabilities. For those requirements, consider using Kubernetes or a similar orchestration platform. + +> Initially, my ambition was to design a system that could automatically roll back if an image failed after an update. +In fact, I planned to implement a rollback policy akin to Docker's own `restart-policy`. If I was going to take this on, +I wanted to do it right. That meant the program would need to daemonize itself, listen for `docker events` to catch any +container failures, and use a timer to trigger rebuilds. Things quickly became complicated as I considered the state management +needed for each service—each potentially having fallback images, active images, and newly built images. I also considered +questions like how the daemon would maintain its state across restarts, and what the consequences might be if a human operator +were to accidentally remove images. These are all legitimate questions with viable solutions, but as I stared at the escalating +complexity of the required state machine, I realized this wasn't something I could knock out in a single night. While it's still +on my radar, it's taken a backseat since this simpler version fulfills my current needs. + +## How to Use + +To schedule the script to run at 3:00 a.m. on an Ubuntu host, follow these steps: + +1. Make the script executable: + + ```bash + chmod +x rbuild.py + mv rbuild.py /usr/local/bin/ + ``` + +2. Open the crontab editor: + + ```bash + crontab -e + ``` + +3. Add the following line to run the script every 30 minutes: + + ```cron + */30 * * * * /usr/local/bin/rbuild.py + ``` + +### Environment Variables + +- `BUILD_PERIOD`: Time (in seconds) after which the script triggers a rebuild. Defaults to 86400 (1 day). +- `UP_TIMEOUT_PERIOD`: Time (in seconds) that the script will wait while bringing up containers. Defaults to 60 seconds. + +## Usage + +``` +usage: rbuild.py [-h] [--build-period BUILD_PERIOD] [--up-timeout-period UP_TIMEOUT_PERIOD] [--force-rebuild] [--remove-images] filename + +Automatically rebuild a series of containers using Docker Compose. + +positional arguments: + filename The docker-compose file to use. + +options: + -h, --help Show this help message and exit. + --build-period BUILD_PERIOD + Rebuild period in seconds. + --up-timeout-period UP_TIMEOUT_PERIOD + Timeout period for bringing up containers in seconds. + --force-rebuild Force a rebuild of all containers. + --remove-images Remove all existing images. +``` + +## License + +MIT -- cgit v1.2.3