Compare commits
3 commits
2ad7697142
...
c2279a5785
| Author | SHA1 | Date | |
|---|---|---|---|
| c2279a5785 | |||
| a0272c2c10 | |||
| 54a0d0f232 |
5 changed files with 332 additions and 20 deletions
67
README.md
67
README.md
|
|
@ -5,10 +5,11 @@
|
||||||
| Container | Image | Purpose |
|
| Container | Image | Purpose |
|
||||||
|-----------|-------|---------|
|
|-----------|-------|---------|
|
||||||
| `duckdns` | `lscr.io/linuxserver/duckdns` | Dynamic DNS — keeps `*.duckdns.org` pointed at the home IP |
|
| `duckdns` | `lscr.io/linuxserver/duckdns` | Dynamic DNS — keeps `*.duckdns.org` pointed at the home IP |
|
||||||
| `homeassistant` | `homeassistant/home-assistant` | Home automation, reachable at `:8123` |
|
| `caddy` | `caddy` (custom build) | HTTPS reverse proxy with automatic Let's Encrypt certificates via DuckDNS DNS-01 |
|
||||||
|
| `homeassistant` | `homeassistant/home-assistant` | Home automation, reachable at `https://ha-padriano.duckdns.org` |
|
||||||
| `timemachine` | `mbentley/timemachine:smb` | Time Machine backup server over SMB |
|
| `timemachine` | `mbentley/timemachine:smb` | Time Machine backup server over SMB |
|
||||||
| `samba` | `dperson/samba` | General SMB file share for Mac and Linux clients |
|
| `samba` | `dperson/samba` | General SMB file share for Mac and Linux clients |
|
||||||
| `forgejo` | `codeberg.org/forgejo/forgejo` | Self-hosted Git server, web UI at `:3000`, SSH at `:2222` |
|
| `forgejo` | `codeberg.org/forgejo/forgejo` | Self-hosted Git server at `https://git-padriano.duckdns.org`, SSH at `:2222` |
|
||||||
|
|
||||||
## Initial Setup
|
## Initial Setup
|
||||||
|
|
||||||
|
|
@ -19,7 +20,9 @@
|
||||||
nano .env
|
nano .env
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Create the required host directories if they don't exist:
|
2. Register the required DuckDNS subdomains at [duckdns.org](https://www.duckdns.org): `ha-padriano`, `padrianoha`, `padriano`, `git-padriano`.
|
||||||
|
|
||||||
|
3. Create the required host directories if they don't exist:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mkdir -p /home/padriano/projects/forgejo
|
mkdir -p /home/padriano/projects/forgejo
|
||||||
|
|
@ -32,11 +35,23 @@
|
||||||
sudo chown 1001:1001 /home/padriano/share
|
sudo chown 1001:1001 /home/padriano/share
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Bring the full stack up:
|
4. Add the reverse proxy trusted header config to Home Assistant:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo tee -a /home/padriano/projects/ha/config/configuration.yaml > /dev/null << 'EOF'
|
||||||
|
|
||||||
|
http:
|
||||||
|
use_x_forwarded_for: true
|
||||||
|
trusted_proxies:
|
||||||
|
- 172.16.0.0/12
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
5. Bring the full stack up (first run builds the custom Caddy image):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd /home/padriano/projects/composer
|
cd /home/padriano/projects/composer
|
||||||
docker compose up -d
|
docker compose up -d --build
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -115,14 +130,26 @@ docker inspect forgejo
|
||||||
### duckdns
|
### duckdns
|
||||||
|
|
||||||
- Config stored at `/home/padriano/projects/duckdns/config`
|
- Config stored at `/home/padriano/projects/duckdns/config`
|
||||||
- Uses `network_mode: host` — required for Avahi/mDNS broadcast
|
- Domains managed: `ha-padriano`, `padrianoha`, `padriano`, `git-padriano` (all `.duckdns.org`)
|
||||||
- Domains managed: `ha-padriano`, `padrianoha`, `padriano` (all `.duckdns.org`)
|
- Subdomains must be registered manually at [duckdns.org](https://www.duckdns.org) before they can be updated
|
||||||
|
|
||||||
|
### caddy
|
||||||
|
|
||||||
|
- Custom image built from `caddy/Dockerfile` — adds the [DuckDNS DNS provider plugin](https://github.com/caddy-dns/duckdns) to the official Caddy image
|
||||||
|
- Config at `caddy/Caddyfile`; TLS certificates stored in the `caddy_data` Docker volume
|
||||||
|
- Obtains free Let's Encrypt certificates via **DNS-01 challenge** (no extra ports needed, no cost)
|
||||||
|
- Listens on `:80` (redirects to HTTPS) and `:443`
|
||||||
|
- Routes:
|
||||||
|
- `ha-padriano.duckdns.org` → Home Assistant `:8123`
|
||||||
|
- `git-padriano.duckdns.org` → Forgejo `:3000`
|
||||||
|
- To reload config without restarting: `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`
|
||||||
|
|
||||||
### homeassistant
|
### homeassistant
|
||||||
|
|
||||||
- Config stored at `/home/padriano/projects/ha/config`
|
- Config stored at `/home/padriano/projects/ha/config`
|
||||||
- Web UI: `http://server:8123` or `http://ha-padriano.duckdns.org`
|
- Web UI: `https://ha-padriano.duckdns.org` (via Caddy) or `http://server:8123` on the LAN
|
||||||
- Uses `network_mode: host` for device discovery (mDNS, Zigbee, etc.)
|
- Runs on the `internal` bridge network so Caddy can reach it by container name
|
||||||
|
- `configuration.yaml` must include `http.use_x_forwarded_for: true` and `trusted_proxies` for the Docker bridge range so HA accepts forwarded headers from Caddy
|
||||||
- Has a healthcheck — status shows `(health: starting)` for ~60s on first boot
|
- Has a healthcheck — status shows `(health: starting)` for ~60s on first boot
|
||||||
|
|
||||||
### timemachine
|
### timemachine
|
||||||
|
|
@ -145,35 +172,36 @@ docker inspect forgejo
|
||||||
|
|
||||||
- All data (repos, config, SQLite DB) stored at `/home/padriano/projects/forgejo`
|
- All data (repos, config, SQLite DB) stored at `/home/padriano/projects/forgejo`
|
||||||
- Backing up this single directory is sufficient for a full restore
|
- Backing up this single directory is sufficient for a full restore
|
||||||
|
- Port 3000 is no longer exposed on the host — access is via Caddy only
|
||||||
|
|
||||||
#### First-run setup
|
#### First-run setup
|
||||||
|
|
||||||
Visit `http://server:3000` on first start and complete the install wizard:
|
Visit `http://server:3000` on first start (LAN only) and complete the install wizard:
|
||||||
|
|
||||||
- **Base URL**: `http://padriano.duckdns.org:3000`
|
- **Base URL**: `https://git-padriano.duckdns.org`
|
||||||
- **SSH domain**: `padriano.duckdns.org`
|
- **SSH domain**: `git-padriano.duckdns.org`
|
||||||
- **SSH port**: `2222`
|
- **SSH port**: `2222`
|
||||||
|
|
||||||
#### Access
|
#### Access
|
||||||
|
|
||||||
| Method | Local network | External (via DuckDNS) |
|
| Method | Local network | External (via DuckDNS) |
|
||||||
|--------|---------------|------------------------|
|
|--------|---------------|------------------------|
|
||||||
| Web UI | `http://server:3000` | `http://padriano.duckdns.org:3000` |
|
| Web UI | `http://server:3000` | `https://git-padriano.duckdns.org` |
|
||||||
| Git SSH | `ssh://git@server:2222` | `ssh://git@padriano.duckdns.org:2222` |
|
| Git SSH | `ssh://git@server:2222` | `ssh://git@git-padriano.duckdns.org:2222` |
|
||||||
|
|
||||||
For external access, forward these ports on your router to `192.168.1.116`:
|
For external access, forward these ports on your router to the server IP:
|
||||||
|
|
||||||
- TCP `3000` → Forgejo web UI
|
- TCP `443` → Caddy (HTTPS — serves both HA and Forgejo)
|
||||||
- TCP `2222` → Forgejo SSH
|
- TCP `2222` → Forgejo SSH
|
||||||
|
|
||||||
#### Git remote URL examples
|
#### Git remote URL examples
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Add remote via HTTP
|
# Add remote via HTTPS
|
||||||
git remote add origin http://padriano.duckdns.org:3000/padriano/my-repo.git
|
git remote add origin https://git-padriano.duckdns.org/padriano/my-repo.git
|
||||||
|
|
||||||
# Add remote via SSH
|
# Add remote via SSH
|
||||||
git remote add origin ssh://git@padriano.duckdns.org:2222/padriano/my-repo.git
|
git remote add origin ssh://git@git-padriano.duckdns.org:2222/padriano/my-repo.git
|
||||||
|
|
||||||
# Clone via SSH (local)
|
# Clone via SSH (local)
|
||||||
git clone ssh://git@server:2222/padriano/my-repo.git
|
git clone ssh://git@server:2222/padriano/my-repo.git
|
||||||
|
|
@ -201,6 +229,7 @@ du -sh /home/padriano/projects/* /home/padriano/backup/*
|
||||||
| Service | Host path | Notes |
|
| Service | Host path | Notes |
|
||||||
|---------|-----------|-------|
|
|---------|-----------|-------|
|
||||||
| `duckdns` | `/home/padriano/projects/duckdns/config` | Token cache, not critical |
|
| `duckdns` | `/home/padriano/projects/duckdns/config` | Token cache, not critical |
|
||||||
|
| `caddy` | Docker volume `caddy_data` | Issued TLS certificates — auto-reissued if lost |
|
||||||
| `homeassistant` | `/home/padriano/projects/ha/config` | All HA config and automations |
|
| `homeassistant` | `/home/padriano/projects/ha/config` | All HA config and automations |
|
||||||
| `timemachine` | `/home/padriano/backup/timemachine` | Mac backup sparsebundles |
|
| `timemachine` | `/home/padriano/backup/timemachine` | Mac backup sparsebundles |
|
||||||
| `samba` | `/home/padriano/share` | General file share — back up as needed |
|
| `samba` | `/home/padriano/share` | General file share — back up as needed |
|
||||||
|
|
|
||||||
13
caddy/Caddyfile
Normal file
13
caddy/Caddyfile
Normal file
|
|
@ -0,0 +1,13 @@
|
||||||
|
ha-padriano.duckdns.org {
|
||||||
|
reverse_proxy homeassistant:8123
|
||||||
|
tls {
|
||||||
|
dns duckdns {env.DUCKDNS_TOKEN}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
git-padriano.duckdns.org {
|
||||||
|
reverse_proxy forgejo:3000
|
||||||
|
tls {
|
||||||
|
dns duckdns {env.DUCKDNS_TOKEN}
|
||||||
|
}
|
||||||
|
}
|
||||||
5
caddy/Dockerfile
Normal file
5
caddy/Dockerfile
Normal file
|
|
@ -0,0 +1,5 @@
|
||||||
|
FROM caddy:builder AS builder
|
||||||
|
RUN xcaddy build --with github.com/caddy-dns/duckdns
|
||||||
|
|
||||||
|
FROM caddy:latest
|
||||||
|
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
|
||||||
|
|
@ -18,7 +18,12 @@ services:
|
||||||
image: homeassistant/home-assistant:2024.5.4
|
image: homeassistant/home-assistant:2024.5.4
|
||||||
container_name: homeassistant
|
container_name: homeassistant
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
network_mode: host
|
ports:
|
||||||
|
- "8123:8123"
|
||||||
|
networks:
|
||||||
|
internal:
|
||||||
|
macvlan_lan:
|
||||||
|
ipv4_address: 192.168.1.246
|
||||||
depends_on:
|
depends_on:
|
||||||
- duckdns
|
- duckdns
|
||||||
environment:
|
environment:
|
||||||
|
|
@ -40,6 +45,8 @@ services:
|
||||||
ports:
|
ports:
|
||||||
- "3000:3000"
|
- "3000:3000"
|
||||||
- "2222:22"
|
- "2222:22"
|
||||||
|
networks:
|
||||||
|
- internal
|
||||||
environment:
|
environment:
|
||||||
- USER_UID=${PUID}
|
- USER_UID=${PUID}
|
||||||
- USER_GID=${PGID}
|
- USER_GID=${PGID}
|
||||||
|
|
@ -48,6 +55,25 @@ services:
|
||||||
- /etc/timezone:/etc/timezone:ro
|
- /etc/timezone:/etc/timezone:ro
|
||||||
- /etc/localtime:/etc/localtime:ro
|
- /etc/localtime:/etc/localtime:ro
|
||||||
|
|
||||||
|
caddy:
|
||||||
|
build: ./caddy
|
||||||
|
container_name: caddy
|
||||||
|
restart: unless-stopped
|
||||||
|
ports:
|
||||||
|
- "80:80"
|
||||||
|
- "443:443"
|
||||||
|
environment:
|
||||||
|
- DUCKDNS_TOKEN=${DUCKDNS_TOKEN}
|
||||||
|
volumes:
|
||||||
|
- ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
|
||||||
|
- caddy_data:/data
|
||||||
|
- caddy_config:/config
|
||||||
|
networks:
|
||||||
|
- internal
|
||||||
|
depends_on:
|
||||||
|
- homeassistant
|
||||||
|
- forgejo
|
||||||
|
|
||||||
samba:
|
samba:
|
||||||
image: dperson/samba:latest
|
image: dperson/samba:latest
|
||||||
container_name: samba
|
container_name: samba
|
||||||
|
|
@ -93,5 +119,11 @@ services:
|
||||||
- /home/padriano/projects/composer/timemachine/smb.conf:/etc/samba/smb.conf:ro
|
- /home/padriano/projects/composer/timemachine/smb.conf:/etc/samba/smb.conf:ro
|
||||||
|
|
||||||
networks:
|
networks:
|
||||||
|
internal:
|
||||||
|
driver: bridge
|
||||||
macvlan_lan:
|
macvlan_lan:
|
||||||
external: true
|
external: true
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
caddy_data:
|
||||||
|
caddy_config:
|
||||||
|
|
|
||||||
233
plans/Plan-HA-upgrade.md
Normal file
233
plans/Plan-HA-upgrade.md
Normal file
|
|
@ -0,0 +1,233 @@
|
||||||
|
# Home Assistant Upgrade Plan: 2024.5.4 → 2026.5.0 (revised)
|
||||||
|
|
||||||
|
Direct jump (no intermediate version stops). Two structural compose changes are folded into this upgrade: bump the `image:` tag, and swap the healthcheck endpoint to one that doesn't require auth on modern HA.
|
||||||
|
|
||||||
|
## Current versions
|
||||||
|
|
||||||
|
- Core: `2024.5.4`
|
||||||
|
- Frontend: `20240501.1`
|
||||||
|
|
||||||
|
## Target versions (as of May 2026)
|
||||||
|
|
||||||
|
- Core: `2026.5.0` (released May 6, 2026)
|
||||||
|
- Frontend: `20260325.6` (stable) — bundled inside the core image, no separate action needed
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
The Home Assistant instance runs as a Docker container defined in `docker-compose.yml`, pinned to `homeassistant/home-assistant:2024.5.4`. The config is volume-mounted at `/home/padriano/projects/ha/config`.
|
||||||
|
|
||||||
|
## 1. Pre-flight checks (read-only)
|
||||||
|
|
||||||
|
Before touching anything, gather facts and confirm assumptions:
|
||||||
|
|
||||||
|
- **Architecture**: `uname -m` — confirm `x86_64` (the official HA image supports it; `armhf` was dropped in 2025).
|
||||||
|
- **Custom components / HACS**: `ls /home/padriano/projects/ha/config/custom_components 2>/dev/null` — currently empty, good. If anything appears, abort and check each integration's HA 2026.5 compatibility first.
|
||||||
|
- **USB device passthrough**: confirm no `devices:` mapping in `docker-compose.yml` (none today — no Z-Wave/Zigbee radios at risk).
|
||||||
|
- **Recorder DB size**: `du -sh /home/padriano/projects/ha/config/home-assistant_v2.db*` — record this. The bigger it is, the longer the first-boot schema migration will take.
|
||||||
|
- **Free disk**: `df -h /home/padriano/projects/ha` — already 405 GB free, plenty for backup + image pull.
|
||||||
|
- **Current version (auth-free)**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker exec homeassistant python -c "from homeassistant.const import __version__; print(__version__)"
|
||||||
|
# expected: 2024.5.4
|
||||||
|
```
|
||||||
|
|
||||||
|
(The old `curl /api/ | grep version` is unreliable and won't work post-upgrade because `/api/` requires auth on modern HA.)
|
||||||
|
- **Current container health**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker inspect --format '{{.State.Health.Status}}' homeassistant
|
||||||
|
# expected: healthy
|
||||||
|
```
|
||||||
|
- **Reverse-proxy reachability**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsS -o /dev/null -w "%{http_code}\n" https://ha-padriano.duckdns.org
|
||||||
|
# record current status code so we can compare post-upgrade
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Backups
|
||||||
|
|
||||||
|
### 2a. Record image digest and pin a local rollback tag
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker inspect --format '{{.Image}}' homeassistant > /home/padriano/projects/ha/image-digest-2024.5.4.txt
|
||||||
|
docker tag "$(cat /home/padriano/projects/ha/image-digest-2024.5.4.txt)" homeassistant/home-assistant:2024.5.4-rollback
|
||||||
|
```
|
||||||
|
|
||||||
|
The local `:2024.5.4-rollback` tag guarantees the exact previous image stays resolvable even if the upstream `:2024.5.4` tag is ever repushed or GC'd.
|
||||||
|
|
||||||
|
### 2b. Create a HA backup from within Home Assistant
|
||||||
|
|
||||||
|
Open Home Assistant UI → **Settings → System → Backups → Create backup** (full backup). This captures integrations state, `.storage/`, and all config managed by HA. Download the `.tar` file.
|
||||||
|
|
||||||
|
### 2c. Off-host copy of the HA backup
|
||||||
|
|
||||||
|
The backup from 2b lands in `/home/padriano/projects/ha/config/backups/` (HA writes it inside `/config`, same disk). Copy it off to `/home/padriano/share/` so we don't only rely on a same-disk copy:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp /home/padriano/projects/ha/config/backups/*.tar /home/padriano/share/ha-backup-2024.5.4.tar
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2d. Filesystem backup of the config directory
|
||||||
|
|
||||||
|
Stop the container first to get a consistent SQLite snapshot — otherwise `home-assistant_v2.db-wal` may be mid-write and the copy may be inconsistent.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose stop homeassistant
|
||||||
|
cp -a /home/padriano/projects/ha/config /home/padriano/projects/ha/config.bak-2024.5.4
|
||||||
|
diff -rq /home/padriano/projects/ha/config /home/padriano/projects/ha/config.bak-2024.5.4 && echo "Backup OK" || echo "Backup MISMATCH"
|
||||||
|
```
|
||||||
|
|
||||||
|
(The container will be restarted in step 5; you can also `docker compose up -d homeassistant` here briefly if you want HA running while you do step 3.)
|
||||||
|
|
||||||
|
## 3. Review breaking changes
|
||||||
|
|
||||||
|
Read the "Backward-incompatible changes" section for each monthly release between 2024.6 and 2026.5:
|
||||||
|
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.6/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.7/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.8/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.9/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.10/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.11/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2024.12/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.1/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.2/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.3/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.4/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.5/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.6/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.7/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.8/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.9/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.10/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.11/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2025.12/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2026.1/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2026.2/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2026.3/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2026.4/
|
||||||
|
- https://www.home-assistant.io/changelogs/core-2026.5/
|
||||||
|
|
||||||
|
High-impact themes across this window:
|
||||||
|
|
||||||
|
- **2024.6**: AlarmDecoder entities renamed with `alarmdecoder_` prefix; Ping integration `disconnected` → `unavailable`.
|
||||||
|
- **2024.7–2024.12**: many YAML-only integration configs removed in favor of UI config flow.
|
||||||
|
- **2025.x**: SQLAlchemy / recorder schema bumps (long first-boot migration expected); `legacy_templates` removal; tightened `http:` / `trusted_proxies` validation.
|
||||||
|
- **2026.x**: skim release notes the day of upgrade for any last-minute regressions/hotfixes.
|
||||||
|
|
||||||
|
Grep `/home/padriano/projects/ha/config` for any deprecated YAML keys flagged by the changelogs before proceeding.
|
||||||
|
|
||||||
|
## 4. Edit `docker-compose.yml`
|
||||||
|
|
||||||
|
Two changes to the `homeassistant` service:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
homeassistant:
|
||||||
|
image: homeassistant/home-assistant:2026.5.0 # was 2024.5.4
|
||||||
|
...
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "curl", "-fsSL", "http://localhost:8123/manifest.json"] # was /api/ (now requires auth)
|
||||||
|
interval: 30s
|
||||||
|
timeout: 10s
|
||||||
|
retries: 5
|
||||||
|
start_period: 30m # was 60s — first-boot recorder schema migration can take a long time
|
||||||
|
```
|
||||||
|
|
||||||
|
Rationale for `start_period: 30m`: during `start_period`, failing health checks don't mark the container `unhealthy`. The first-boot recorder schema migration can run for many minutes, and a stock 60s `start_period` would flip the container to `unhealthy` mid-migration. Note this is cosmetic/observability — plain Docker does **not** kill or restart an `unhealthy`-but-running container (`restart: unless-stopped` only acts on container *exit*), and nothing here gates on HA's health (`caddy`'s `depends_on` has no `condition: service_healthy`). So the only real risk of a too-short `start_period` is a misleading `unhealthy` status and noisy monitoring during migration. 30 min gives headroom; revert to a shorter value in a follow-up once we've measured the real first-boot time.
|
||||||
|
|
||||||
|
Validate before applying:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /home/padriano/projects/composer
|
||||||
|
docker compose config
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Pull and start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /home/padriano/projects/composer
|
||||||
|
docker compose pull homeassistant
|
||||||
|
docker compose up -d homeassistant
|
||||||
|
```
|
||||||
|
|
||||||
|
`pull` only fetches the `homeassistant` image; `duckdns`, `caddy`, `forgejo`, `samba`, `timemachine` are untouched (intended).
|
||||||
|
|
||||||
|
## 6. Verify
|
||||||
|
|
||||||
|
- **Watch the HA log** (where migration detail actually goes — `docker compose logs` only shows stdout):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
tail -F /home/padriano/projects/ha/config/home-assistant.log
|
||||||
|
```
|
||||||
|
|
||||||
|
Look for `Database upgrade in progress`, then `Setup of domain X took …`, finally `Home Assistant initialized in …`.
|
||||||
|
- **Container health**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker inspect --format '{{.State.Health.Status}}' homeassistant
|
||||||
|
# wait until: healthy
|
||||||
|
```
|
||||||
|
- **Version (auth-free)**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker exec homeassistant python -c "from homeassistant.const import __version__; print(__version__)"
|
||||||
|
# expected: 2026.5.0
|
||||||
|
```
|
||||||
|
- **Local HTTP**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:8123/manifest.json
|
||||||
|
# expected: 200
|
||||||
|
```
|
||||||
|
- **Reverse proxy** (validates `trusted_proxies` still works against modern HA `http:` validation):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsS -o /dev/null -w "%{http_code}\n" https://ha-padriano.duckdns.org
|
||||||
|
# expected: same status code as recorded in step 1
|
||||||
|
```
|
||||||
|
- **UI**: open Home Assistant → **Settings → Repairs** and address any flagged migration items.
|
||||||
|
|
||||||
|
## 7. Rollback
|
||||||
|
|
||||||
|
**Decide which option by where the upgrade failed.** Once 2026.5.0 has booted successfully it migrates the recorder DB schema *and* `.storage/` to the new format, and HA does **not** support schema downgrade. So whether reverting the image tag alone is safe depends entirely on whether migration started — check the HA log (step 6) for `Database upgrade in progress`:
|
||||||
|
|
||||||
|
- **Migration never started** (new container crashed/failed early, you never saw that line) → the on-disk config is untouched. Use **Option A** (revert tag only).
|
||||||
|
- **Migration started or completed** (you saw that line, or HA reached the UI) → the DB/`.storage/` are now on the new schema. **Option A will fail** — old core will refuse the newer recorder schema. Use **Option B** (restore the config backup).
|
||||||
|
|
||||||
|
### Option A — revert image tag only (safe ONLY if migration never started)
|
||||||
|
|
||||||
|
Edit `docker-compose.yml`:
|
||||||
|
- set `image:` back to `homeassistant/home-assistant:2024.5.4`
|
||||||
|
- revert the healthcheck `test` line to `http://localhost:8123/api/`
|
||||||
|
- revert `start_period: 60s`
|
||||||
|
|
||||||
|
Then:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /home/padriano/projects/composer
|
||||||
|
docker compose up -d homeassistant
|
||||||
|
```
|
||||||
|
|
||||||
|
The local `homeassistant/home-assistant:2024.5.4-rollback` tag from step 2a guarantees the exact previous image is still resolvable even if the upstream tag was repushed.
|
||||||
|
|
||||||
|
### Option B — restore config backup (default once migration has run)
|
||||||
|
|
||||||
|
Revert the image tag and healthcheck per Option A, then restore the pre-upgrade config so the DB/`.storage/` schema matches 2024.5.4:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose stop homeassistant
|
||||||
|
mv /home/padriano/projects/ha/config /home/padriano/projects/ha/config.failed-2026.5.0 # keep the failed state for diagnosis instead of rm -rf
|
||||||
|
cp -a /home/padriano/projects/ha/config.bak-2024.5.4 /home/padriano/projects/ha/config
|
||||||
|
docker compose up -d homeassistant
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option C — last resort
|
||||||
|
|
||||||
|
Restore the HA `.tar` backup (from step 2b/2c) via the HA UI recovery mode on a fresh `2024.5.4` container.
|
||||||
|
|
||||||
|
## 8. Post-upgrade follow-up
|
||||||
|
|
||||||
|
- Measure the actual first-boot migration time from the HA log and lower `healthcheck.start_period` back to a sensible steady-state value (e.g. `2m`) in a follow-up commit.
|
||||||
|
- Once stable for a few days, delete `/home/padriano/projects/ha/config.bak-2024.5.4` and the local `:2024.5.4-rollback` image tag (`docker rmi homeassistant/home-assistant:2024.5.4-rollback`) to reclaim disk.
|
||||||
Loading…
Add table
Reference in a new issue