Bring the docs up to date with the running stack
The READMEs, CLAUDE.md and todo.md still described Authentik, services removed long ago (Ghost, MMDL, Postiz, Pinchflat...) and two servers. Now they list the 24 services actually deployed (checked against docker ps), explain that netcup and docker-01 are one machine, document Gondulf, StarPunk, Listmonk, Gokapi and dockcheck, and use bin/deploy throughout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Phil
@@ -1,141 +1,58 @@
|
||||
# Infrastructure Improvements TODO
|
||||
|
||||
## High Priority (Quick Wins)
|
||||
Current state (2026-10-31): 24 services in 6 categories, all compose files
|
||||
templated, Pocket ID as SSO (Authentik retired), multi-agent guard rails
|
||||
(`bin/worktree`, `bin/deploy`, `bin/vault-run`, `deploy-guard.yml`).
|
||||
|
||||
### 1. Split the massive docker role ✅ COMPLETED
|
||||
- **Current Issue**: `roles/docker/tasks/main.yml` has 20+ services in one file (176 lines)
|
||||
- **Solution**: Break into logical service groups:
|
||||
```
|
||||
roles/docker/tasks/
|
||||
├── main.yml (orchestrator)
|
||||
├── infrastructure/ (caddy, pocketid, dockge)
|
||||
├── development/ (gitea, codeserver, bytestash)
|
||||
├── media/ (audiobookshelf, kavita, ghost, pinchflat, pinry, hoarder, manyfold)
|
||||
├── productivity/ (paperless, baikal, syncthing, mmdl, heyform, dawarich, palmr, obsidian-livesync)
|
||||
├── communication/ (gotosocial, postiz)
|
||||
└── monitoring/ (changedetection, appriseapi, gotify)
|
||||
```
|
||||
- **COMPLETED**: All services organized into logical categories with category-level tags
|
||||
## Done
|
||||
- Split the docker role into categories with category and service tags.
|
||||
- Central variables in `group_vars/all/` (`domains.yml`, `infrastructure.yml`,
|
||||
`vault.yml`).
|
||||
- Converted every static compose file to a template.
|
||||
- Removed unused services, most recently Authentik, Calibre-Web, dir2opds,
|
||||
kosync, Sneaky Klaus and Audiobookshelf podcasts.
|
||||
- Reserved address range on the `lava` network so fixed IPs can't be taken.
|
||||
- Automatic container updates with dockcheck for labelled containers.
|
||||
|
||||
### 2. Standardize variable management ✅ COMPLETED
|
||||
- **Current Issue**: Secrets in single encrypted file, no clear variable hierarchy
|
||||
- **Solution**: Create proper variable structure:
|
||||
```
|
||||
group_vars/
|
||||
├── all/
|
||||
│ ├── domains.yml (domain and subdomain mappings)
|
||||
│ ├── infrastructure.yml (network config, Docker settings)
|
||||
│ ├── vault.yml (encrypted secrets with vault_ prefix)
|
||||
│ └── services.yml (service configuration flags)
|
||||
```
|
||||
- **COMPLETED**: Implemented comprehensive variable hierarchy, updated all templates to use centralized variables, fixed service tag isolation
|
||||
## Open
|
||||
|
||||
### 3. Template consolidation ✅ PARTIALLY COMPLETED
|
||||
- **Current Issue**: Many compose templates repeat patterns, some services used static files
|
||||
- **Solution**: Create reusable template includes with standard service template structure
|
||||
- **COMPLETED**: Converted all static compose files (caddy, dockge, hoarder) to Jinja2 templates
|
||||
- **REMAINING**: Create reusable template patterns for common configurations
|
||||
### Reusable template patterns
|
||||
Many compose templates repeat the same network, restart and label blocks.
|
||||
Pull the shared parts into includes or macros.
|
||||
|
||||
## Security & Reliability
|
||||
### Health checks
|
||||
Only Pocket ID, Gondulf, Dawarich, Listmonk and Syncthing define health checks
|
||||
in their templates. Add them to the rest where the image supports it.
|
||||
|
||||
### 4. Add health checks
|
||||
- **Issue**: Most services lack proper healthcheck configurations in compose templates
|
||||
- **Solution**: Implement comprehensive health monitoring with standardized healthcheck patterns
|
||||
### Backups
|
||||
Only Paperless-ngx and GoToSocial back up (daily to S3 with
|
||||
`offen/docker-volume-backup`, 7-day retention). Still to do:
|
||||
- Database dumps for the Postgres/MongoDB/CouchDB services.
|
||||
- Volume backups for the file-based services (Kavita, Audiobookshelf, Gitea,
|
||||
Pocket ID, …).
|
||||
- A tested restore.
|
||||
|
||||
### 5. Implement backup strategy
|
||||
- **Issue**: No automated backups for 25 services and their data
|
||||
- **Solution**: Add backup role with:
|
||||
- Database dumps for PostgreSQL services
|
||||
- Volume backups for file-based services
|
||||
- Rotation policies
|
||||
- Restoration testing
|
||||
### Network segmentation
|
||||
Every service shares the `lava` network. Consider separate frontend, backend
|
||||
and database networks.
|
||||
|
||||
### 6. Network segmentation
|
||||
- **Issue**: All services share one Docker network
|
||||
- **Solution**: Separate into:
|
||||
- `frontend` (Public-facing services)
|
||||
- `backend` (Internal services only)
|
||||
- `database` (Database access only)
|
||||
### Security hardening
|
||||
- Add `no-new-privileges` and dropped capabilities where images allow it
|
||||
(only Manyfold has them now). Cronmaster runs as root.
|
||||
- fail2ban (or Caddy rate limits) in front of login pages.
|
||||
|
||||
### 7. Security hardening
|
||||
- Remove unnecessary `user: root` from services
|
||||
- Add security contexts to all containers
|
||||
- Implement least-privilege access patterns
|
||||
- Add fail2ban for authentication services
|
||||
### CI with Gitea Actions
|
||||
Syntax check and `--check` runs on push, using the existing Gitea runner.
|
||||
|
||||
## Automation Opportunities
|
||||
### Configuration drift detection
|
||||
Catch manual changes on the server, e.g. a scheduled `bin/deploy --check`.
|
||||
|
||||
### 8. CI/CD with Gitea Actions
|
||||
- Leverage self-hosted Gitea for:
|
||||
- Ansible syntax validation
|
||||
- Service configuration testing
|
||||
- Automated deployment triggers
|
||||
- Rollback capabilities
|
||||
### Service start order
|
||||
Apps that use Pocket ID don't wait for it to be up.
|
||||
|
||||
### 9. Configuration drift detection
|
||||
- Add validation tasks to catch manual changes
|
||||
- Implement configuration validation with proper assertions
|
||||
|
||||
### 10. Service dependency management
|
||||
- **Issue**: Some services depend on Pocket ID SSO but no startup ordering
|
||||
- **Solution**: Implement dependency checking and startup ordering
|
||||
|
||||
### 11. Ansible best practices
|
||||
- Replace deprecated `apt_key` with proper patterns
|
||||
- Use `ansible.builtin` FQCN consistently
|
||||
- Add `check_mode` support
|
||||
- Implement proper idempotency checks
|
||||
|
||||
### 12. Documentation automation
|
||||
- Auto-generate service inventory
|
||||
- Create service documentation templates
|
||||
- Implement automated documentation updates
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
### Week 1: Foundation
|
||||
- [x] Document improvements in todo.md
|
||||
- [x] Reorganize docker role structure
|
||||
- [x] Convert static compose files to templates
|
||||
- [x] Remove unused services (beaver, grist, stirlingpdf, tasksmd, redlib)
|
||||
- [x] Clean up templates and files directories
|
||||
- [x] Implement variable hierarchy
|
||||
- [ ] Create reusable template patterns
|
||||
|
||||
### Week 2: Security & Monitoring
|
||||
- [ ] Add health checks
|
||||
- [ ] Implement backup strategy
|
||||
- [ ] Security hardening
|
||||
|
||||
### Week 3: Automation
|
||||
- [ ] CI/CD pipeline setup
|
||||
- [ ] Configuration validation
|
||||
- [ ] Documentation automation
|
||||
|
||||
### Week 4: Advanced Features
|
||||
- [ ] Network segmentation
|
||||
- [ ] Dependency management
|
||||
- [ ] Monitoring dashboard
|
||||
|
||||
## Completed Work Summary
|
||||
|
||||
### ✅ Major Accomplishments
|
||||
- **Docker Role Reorganization**: Split monolithic 176-line main.yml into 6 logical service categories
|
||||
- **Template Standardization**: Converted all static compose files to Jinja2 templates
|
||||
- **Service Cleanup**: Removed 5 unused/broken services (beaver, grist, stirlingpdf, tasksmd, redlib)
|
||||
- **Category-Based Deployment**: Can now deploy services by category using tags (infrastructure, media, etc.)
|
||||
- **Variable Management**: Implemented comprehensive centralized variable hierarchy with proper secret organization
|
||||
- **Service Tag Isolation**: Fixed service tags to deploy individual services only (not entire categories)
|
||||
- **Documentation Updates**: Updated all README files and CLAUDE.md to reflect new architecture
|
||||
|
||||
### 📊 Current Stats
|
||||
- **25 active services** organized into 6 categories
|
||||
- **100% templated** compose files (no static files)
|
||||
- **6 service directories** for logical organization
|
||||
- **Clean file structure** with only essential static files
|
||||
|
||||
## Notes
|
||||
- Current architecture is solid and much better organized for long-term maintainability
|
||||
- Focus on high-impact, low-effort improvements first
|
||||
- Leverage existing infrastructure (Gitea, Pocket ID) for automation
|
||||
- Template-driven approach enables future dynamic configuration
|
||||
### Ansible clean-up
|
||||
- Replace the deprecated `apt_key` task for Docker's repo (it also fetches the
|
||||
Ubuntu key for a Debian repo).
|
||||
- Use `ansible.builtin.` names everywhere.
|
||||
- The Dockge compose file is templated twice (`tasks/main.yml` and
|
||||
`tasks/infrastructure/main.yml`).
|
||||
|
||||
Reference in New Issue
Block a user