Skip to content

docs: clarify unreleased changes and image versioning #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rdwr-egore merged 1 commit into from
Oct 14, 2026
Merged

docs: clarify unreleased changes and image versioning #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 16 additions & 61 deletions DEPLOYMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -487,13 +487,14 @@ Before running `git pull` (see [6.3 Upgrade Guide](#63-upgrade-guide)), record t
git rev-parse HEAD > backup/previous-commit.txt
```

To roll back to the previous version after a failed upgrade:
To restore the prior source checkout:

```bash
git checkout "$(cat backup/previous-commit.txt)"
docker compose up -d
```

This **does not roll back the running container**. To revert deployed behavior, restore the previous `WATCHDOG_VERSION` and redeploy the corresponding image as described in [5.2 Image Rollback](#52-roll-back-an-image-upgrade).

Also restore the `.env` and `watchdog-config.yaml` files backed up before the upgrade — see [6.3 Upgrade Guide](#63-upgrade-guide).

---
Expand Down Expand Up @@ -574,7 +575,7 @@ docker compose up -d

### 6.3 Upgrade Guide

There are two ways to upgrade the Watchdog: the application code, or the Docker image only.
Updating the source checkout and upgrading the running Docker image are different operations. Only deploying a new image changes the running watchdog code.

#### Before You Begin (Recommended)

Expand All @@ -596,72 +597,26 @@ cp backup/watchdog-config.yaml.bak watchdog-config.yaml

---

#### Upgrade Application Only

##### Option A: Upgrade from Git Repository

*Note* - Requires internet connectivity.

1. Navigate to the project directory:

```bash
cd Container_Alert
```

2. Record the current commit, for [rollback](#53-roll-back-an-application-upgrade-git) if needed:

```bash
mkdir -p backup
git rev-parse HEAD > backup/previous-commit.txt
```

3. Stop the running container:

```bash
docker compose down
```

4. Download the latest source code:

```bash
git fetch origin
git pull origin main
```

5. Start the updated container:

```bash
docker compose up -d
```

6. Verify:
#### Update Source Code (Not a Running Image)

```bash
docker ps
docker compose logs docker-container-watchdog
```
The application (`watchdog.py`, `lifecycle.py`, `ha_monitor.py`) is **built into the Docker image**, not bind-mounted. Updating the Git checkout alone **does not deploy code**, and `docker compose up -d` with the same pinned image will not apply the latest changes. Do not stop the running watchdog just to update source files.

If verification fails, see [5.3 Roll Back an Application Upgrade (Git)](#53-roll-back-an-application-upgrade-git).
To update the repository without changing the running container:

---

##### Option B: Upgrade Application Only (Offline)

1. Obtain the latest version of the application. You can either obtain the latest archive from the RE team or download it directly from GitHub (https://github.com/Radware/CyberController-Container-Alert.git).
2. Uninstall the current version — see [6.4 Uninstalling](#64-uninstalling).
3. Replace the existing files in the application directory:

```bash
cd /path/to/Container_Alert
```
```bash
mkdir -p backup
git rev-parse HEAD > backup/previous-commit.txt
git fetch origin
git pull --ff-only origin main
```

4. Redeploy the latest version — see [3. Deployment Steps](#3-deployment-steps).
To deploy new code, first prepare a **new numbered release**: update `VERSION` and the README version history, build and test the matching `watchdog:<VERSION>` image using `docker-compose.build.yaml`, and verify it contains all required Python modules. Keep the previous versioned image for rollback; update `.env`'s `WATCHDOG_VERSION` only when deploying the verified new image. For offline deployments, distribute the new `VERSION` and matching `watchdog.tar`, then use `install.sh`. See [Deployment Steps](#3-deployment-steps), [Image Rollback](#52-roll-back-an-image-upgrade), and [README Version History](README.md#10-version-history).

---

#### Upgrade Docker Image Only

Automatic upgrades are **not enabled** by default. Before upgrading, tag the current image so it can be [rolled back](#52-roll-back-an-image-upgrade) if the new image misbehaves:
Automatic upgrades are **not enabled**. Preserve the existing versioned `watchdog:<VERSION>` image for [rollback](#52-roll-back-an-image-upgrade). Only if the old image exists solely as `watchdog:latest`, save that image as `watchdog:rollback` before loading the replacement:

```bash
docker tag watchdog:latest watchdog:rollback
Expand All @@ -671,7 +626,7 @@ There are two ways to upgrade the image — online or offline. Follow only one o

##### Option A: Online Image Upgrade

If you have internet access, pull the latest image:
If a new versioned image has been published to the image registry configured for this deployment, pull that tag. A local-only `watchdog:<VERSION>` image is not available via `docker compose pull`; build it or load the release archive instead:

```bash
docker compose pull
Expand Down
5 changes: 5 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -629,8 +629,13 @@ Probe selection is automatic: containers with a Docker `HEALTHCHECK` are monitor

## 10. Version History

**Release status (2026-10-14):** `VERSION` remains `1.5.4`. The changes below are merged into `main` but **unreleased**: the running `watchdog:1.5.4` image does not acquire them from `git pull`.

**Release procedure:** After validating a release candidate, increment `VERSION`, add a dated entry here, build and verify `watchdog:<VERSION>`, and package the matching `watchdog.tar` for offline installs. Pin deployment with `WATCHDOG_VERSION` in `.env`; verify upgrade and rollback before tagging the exact released commit (`vX.Y.Z`) and publishing release notes. Do not overwrite an old versioned image with new code. GitHub CI checks PRs but does not publish releases automatically; as of this update, no Git tags or GitHub Releases exist.

| Version | Date | Author | Changes |
|---------|------------|--------|---------|
| Unreleased (post-1.5.4) | 2026-10-14 | Radware engineering | [#6](https://github.com/Radware/CyberController-Container-Alert/pull/6): Docker event ID resolution and bounded missing-container warnings; [#5](https://github.com/Radware/CyberController-Container-Alert/pull/5): authoritative `RestartCount`, deduplicated restart-loop incidents, stable recovery; [#7](https://github.com/Radware/CyberController-Container-Alert/pull/7): planned Docker stop correlation and corrected exit-137 handling; [#4](https://github.com/Radware/CyberController-Container-Alert/pull/4): optional independent HA active-node change alerts. |
| 1.5.4 | 2026-09-23 | Rahul Kumar | Versioned Docker image (`watchdog:<VERSION>`) driven by the root `VERSION` file; installer loads the packaged `watchdog.tar`, rejects an archive that does not carry the release tag, aborts on Compose failures, and verifies the running image; restart-loop detection now uses Docker `RestartCount` instead of counting poll observations; `container_health_checks` overrides implemented; fixed `.env` migration on root-owned files; `watchdog-config.yaml` made readable by the non-root container user |
| 1.5.3 | 2026-09-16 | Rahul Kumar | Resource Limits Enforced |
| 1.5.2 | 2026-08-31 | Rahul Kumar | Updated error message"Suppressing expected Cyber Controller SQL dump syntax-check container termination (exit 137) alert" |
Expand Down
Loading