{"id":35214565,"url":"https://github.com/tetsuya1126/raspi_overlay-auto-update","last_synced_at":"2026-06-13T00:00:34.050Z","repository":{"id":327318285,"uuid":"1108809459","full_name":"Tetsuya1126/raspi_overlay-auto-update","owner":"Tetsuya1126","description":"Safe unattended apt update for Raspberry Pi using OverlayFS","archived":false,"fork":false,"pushed_at":"2026-05-01T02:08:27.000Z","size":48,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T02:19:23.802Z","etag":null,"topics":["apt","auto-update","bash","debian","embedded-linux","fail-safe","headless","iot","linux-updates","maintenance","overlayfs","raspberry-pi","readonly","sd-card","systemd","unattended-upgrades","watchdog"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tetsuya1126.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T00:21:33.000Z","updated_at":"2026-05-01T01:06:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Tetsuya1126/raspi_overlay-auto-update","commit_stats":null,"previous_names":["tetsuya1126/raspi_overlay-auto-update"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Tetsuya1126/raspi_overlay-auto-update","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tetsuya1126%2Fraspi_overlay-auto-update","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tetsuya1126%2Fraspi_overlay-auto-update/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tetsuya1126%2Fraspi_overlay-auto-update/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tetsuya1126%2Fraspi_overlay-auto-update/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tetsuya1126","download_url":"https://codeload.github.com/Tetsuya1126/raspi_overlay-auto-update/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tetsuya1126%2Fraspi_overlay-auto-update/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34266916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apt","auto-update","bash","debian","embedded-linux","fail-safe","headless","iot","linux-updates","maintenance","overlayfs","raspberry-pi","readonly","sd-card","systemd","unattended-upgrades","watchdog"],"created_at":"2025-12-29T21:20:56.936Z","updated_at":"2026-06-13T00:00:33.776Z","avatar_url":"https://github.com/Tetsuya1126.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Raspberry Pi OverlayFS Auto Update\n\n**Fix the problem: *“apt upgrade disappears after reboot”* on OverlayFS systems.**\n\nFully automated, reboot-safe maintenance framework for **read-only Raspberry Pi environments**.\n\n\u003e Designed for long-term unattended systems — stable, safe, and hands-free.\n\n---\n\n⭐ **If this project helps you, consider giving it a star!**\n\n---\n\n## 🎯 Who is this for?\n\n* Raspberry Pi running in **read-only (OverlayFS) mode**\n* Devices deployed in the field (IoT / edge / remote systems)\n* Systems that must run **unattended for months**\n* Anyone tired of **manual update + reboot workflows**\n\n---\n\n## 💥 What problem does this solve?\n\nOn OverlayFS systems:\n\n* `apt upgrade` changes **disappear after reboot**\n* Writable layer can **fill up over time**\n* Manual maintenance becomes **fragile and risky**\n\n---\n\n## ✅ The Solution\n\nThis project introduces a **reboot-based maintenance workflow**:\n\n1. Switch to writable mode\n2. Apply updates safely\n3. Reboot automatically\n4. Restore clean read-only OverlayFS\n\n✔ No manual steps\n✔ No broken updates\n✔ No overlay corruption\n\n---\n\n## ✨ Key Features\n\n### 🔄 Fully Automated\n\n* Automatic OverlayFS ON/OFF switching\n* systemd timer-based execution\n* Zero manual intervention\n\n### 🛡 Built for Reliability\n\n* Reboot-based safe update design\n* Lock mechanism (prevents duplicate runs)\n* Cooldown protection (avoids excessive writes)\n* Resume support after interruption\n* Self-healing state recovery (fallback to safe state)\n\n### 🔧 Flexible \u0026 Extensible\n\n* YAML-based task definitions\n* Custom scripts supported\n* JSON logging for automation\n\n### 🧪 Developer Friendly\n\n* Dry-run mode (no reboot / safe testing)\n* GitHub Actions CI (shellcheck + syntax validation)\n\n---\n\n## ⚡ Quick Start (under 3 minutes)\n\nInstall and enable automatic maintenance in one step:\n\n### One-line install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Tetsuya1126/raspi_overlay-auto-update/main/install/curl_installer.sh | sudo bash\n```\n\n---\n\n### Or manual install\n\n```bash\ngit clone --branch main --depth 1 https://github.com/Tetsuya1126/raspi_overlay-auto-update.git\ncd raspi_overlay-auto-update\nsudo ./install/install.sh\n```\n\n---\n\n\u003e ⚠️ Always install from the official GitHub repository to ensure safety.\n\n---\n\n## 🔍 How It Works\n\n```text\nTimer Start\n   ↓\nmaintenance.sh\n   ↓\nLock Check\n   ↓\nState Detection\n   ↓\nOverlayFS Mode Check\n   ↓\nReboot if Needed\n   ↓\nRun Tasks (apt, custom scripts)\n   ↓\nRestore OverlayFS (read-only)\n   ↓\nWait for next scheduled run\n```\n\n---\n\n## 🧪 Safe Testing (Dry Run)\n\n```bash\ncd /usr/local/bin/auto-maintenance/\nsudo ./maintenance.sh --dry\n```\n\n* No reboot\n* No OverlayFS changes\n* Logs only\n\n---\n\n## 🛠 Task Configuration\n\nEdit:\n\n```bash\nsudo nano /etc/maintenance_tasks.yaml\n```\n\nExample:\n\n```yaml\ntasks:\n  - name: apt_update\n    cmd: /usr/local/lib/auto-maintenance/maintenance_funcs/apt_update.sh\n\n  - name: custom_script\n    cmd: bash /usr/local/bin/myscript.sh\n```\n\n---\n\n## 🔄 State Transitions (Simplified)\n\n| Overlay | State | Action                       |\n| ------- | ----- | ---------------------------- |\n| ON      | 2     | NEED_OVERLAY_OFF / COOL_DOWN |\n| ON      | 1     | RESUME_TO_OVERLAY_OFF        |\n| ON      | 0     | NEED_OVERLAY_OFF (initial)   |\n| OFF     | 2     | DO_MAINTENANCE / COOL_DOWN   |\n| OFF     | 1     | MAINTENANCE_CONTINUE         |\n| OFF     | 0     | IDLE                         |\n\n---\n\n## 💡 State File Handling\n\nThe system relies on a persistent state file.\n\n* Missing or corrupted state will reset to a safe default (`STATE=0`)\n* Maintenance will restart automatically from a clean state\n* Designed to recover from interruptions without manual intervention\n\n---\n\n## 📄 Logs\n\n```bash\n/var/log/maintenance/maintenance.log\n/var/log/maintenance/task_status.json\n```\n\n---\n\n## 🔐 Security Notice\n\nOfficial releases are **only published in this repository**.\n\nWe do NOT distribute:\n\n* ZIP archives\n* EXE files\n* Third-party mirrors\n\nIf you find this project elsewhere, treat it as untrusted.\n\n---\n\n## 🧩 Tested Environments\n\n* Raspberry Pi 2 / 3 / Zero\n* Raspberry Pi OS / Debian\n* QEMU / VirtualBox\n\n✔ Real-world tested for months\n\n---\n\n## 🛣 Roadmap\n\n* Retry logic for Overlay switching\n* Automatic recovery from failed states\n\n---\n\n## 📚 Documentation\n\nSee the Wiki for detailed usage and configuration. (Keep on update):\nhttps://github.com/Tetsuya1126/raspi_overlay-auto-update/wiki\n\n---\n\n## 🤝 Contributing\n\nIssues and Pull Requests are welcome.\n\n---\n\n## 📄 License\n\nMIT License\n\n---\n\n## 🏁 Status\n\n**v2.0.0 — Final release for real-world usage**\n\n---\n\n## 🏛 Official Repository\n\n**This is the original upstream repository.**\n\nActively maintained and used in real-world deployments.\n\nReliable updates for read-only Raspberry Pi systems.\n\n---\n\nKeywords: Raspberry Pi OverlayFS auto update safe upgrade systemd.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetsuya1126%2Fraspi_overlay-auto-update","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftetsuya1126%2Fraspi_overlay-auto-update","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetsuya1126%2Fraspi_overlay-auto-update/lists"}