mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 19:01:54 +00:00
kevinveenbirkenbachandClaude Opus 4.7
8e293bd921
Root cause of step-08 deploy failures across all 4 test-development
distros in run 26572559126: `make compose-deploy mode=reinstall
apps=web-app-dashboard INFINITO_SERVICES_DISABLED=matomo` (step 07)
made make export the cmdline var into the recipe's shell env, which
reached `runner.py` → `make setup` → `make dotenv`. The dotenv
generator's `setdefault` then baked the runtime-only value into the
on-disk `.env`. Step 08 sourced that .env, filtered `web-app-matomo`
out of its primary apps, and exited with "All primary apps disabled".
Fix:
- Drop the 7 routing knobs (apps, mode, purge, bundles, disable,
full_cycle, variant) from `passthrough.STATIC_KEYS` and from
`default.env`. They are per-invocation; .env is the persistent SPOT
and must not capture them.
- Switch every consumer from `os.environ["KEY"]` strict access to
`os.environ.get("KEY", "")` so the missing-key path stops at "no
filter" instead of a KeyError.
- Rename the env-var surface to match the make-alias surface 1:1
(lowercase): INFINITO_APPS → apps, INFINITO_SERVICES_DISABLED →
disable, INFINITO_BUNDLES → bundles, INFINITO_FULL_CYCLE →
full_cycle, INFINITO_VARIANT → variant, INFINITO_DEPLOY_MODE → mode,
INFINITO_PURGE_ENTITIES → purge. The make alias was the user-facing
name in every doc; routing-knob env vars now use the same name so
the cmdline form, the recipe env-prefix, and the consumer reads
all line up.
- Collapse the Makefile `compose-deploy` recipe to just the two
knobs whose alias differs from the env name (`type` →
INFINITO_DEPLOY_TYPE, `debug` → INFINITO_DEBUG). GNU Make
auto-exports cmdline variables into the recipe's shell env, so the
identical-name `$(if $(apps),apps="$(apps)")` lines were pure
noise.
- Drop `disable: ${disable}` from compose.yml. The dev CLI builds
`extra_env` per `docker exec` call and forwards `disable` via
`-e`, so the container env never needs the value frozen at
compose-up time.
- Update the 3 actual leak call sites
(07/08/09_deploy_*.sh) to the make-alias form
(`disable=matomo`, `full_cycle=true`, `variant=1`).
- Add `SIM112` to ruff's ignore set: the lowercase env names are
the deliberate make/env parity, not a typo.
Repro before fix: `INFINITO_SERVICES_DISABLED=matomo make dotenv`
wrote `INFINITO_SERVICES_DISABLED=matomo` to `.env`. After fix:
`disable=matomo make dotenv` leaves `.env` untouched.
Tests: `make test` and `make autoformat` green (2711 tests, 8 lint
sub-targets).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
# Manage Low-Hardware Resources
|
|
|
|
Use this guide when you work on a machine with limited CPU, RAM, or disk.
|
|
|
|
## Goal Hardware
|
|
|
|
A practical long-term target is:
|
|
|
|
- 64 GB RAM
|
|
- a swapfile about the same size as RAM
|
|
- an external SSD with more than 500 GB if your computer does not have sufficient storage space
|
|
- enough room for Docker images, volumes, build cache, and local repositories
|
|
|
|
If disk space is tight, you SHOULD move Docker data, caches, and your working directory to the SSD.
|
|
|
|
On Linux, you MAY move Docker to a different data path:
|
|
|
|
```json
|
|
{
|
|
"data-root": "/mnt/ssd/docker"
|
|
}
|
|
```
|
|
|
|
Then restart Docker:
|
|
|
|
```bash
|
|
sudo systemctl restart docker
|
|
```
|
|
|
|
The mount MUST be available before Docker starts. Otherwise the daemon may fall back to the system drive or fail to start cleanly.
|
|
|
|
On macOS and Windows, you MUST use Docker Desktop settings instead of `daemon.json`.
|
|
|
|
A same-size swapfile helps absorb memory spikes on Linux. On Windows and macOS, you SHOULD keep enough free disk space available for virtual memory and local caches.
|
|
|
|
## Load Only What You Need
|
|
|
|
For a broad stack like the Community Hub, you SHOULD start only the services you actually need. If you are working on Discourse, you do not need Mastodon, Pixelfed, PeerTube, or Friendica in the same session.
|
|
|
|
You MAY pass `disable=<csv>` to `make compose-deploy` to disable services automatically across all applications without editing any file:
|
|
|
|
```bash
|
|
make compose-deploy mode=reinstall apps=web-app-discourse disable=matomo
|
|
```
|
|
|
|
This sets `enabled: false` and `shared: false` for every listed service in the generated inventory. See [variables.md](variables.md) for details.
|
|
|
|
| Service | Optional | What it provides | Effect of disabling | Safe to disable when |
|
|
|---|---|---|---|---|
|
|
| `matomo` | 🟢 | Analytics tracking | No usage statistics collected. Usually no functional impact. | You are not testing analytics integration |
|
|
| `oidc` | 🟠 | Single sign-on via Keycloak | App falls back to local login | You are not testing SSO/OIDC flows |
|
|
| `ldap` | 🟠 | Central user directory via OpenLDAP | App uses its own local user store | You are not testing LDAP/user sync |
|
|
| `css` | 🟠 | Custom theming/branding stylesheet | App uses its default upstream theme | You are not testing visual customization |
|
|
| `logout` | 🟠 | Shared logout endpoint across apps | Single sign-out does not propagate | You are not testing cross-app logout |
|
|
| `dashboard` | 🟠 | Central navigation hub | App is not reachable via the dashboard | You access the app directly by URL |
|
|
| `redis` | 🔴 | In-memory cache and session store | Caching and queuing are disabled | The app does not require sessions or queues (rarely safe) |
|
|
| `database` | 🔴 | Shared relational database (MariaDB/Postgres) | App cannot persist data | **Never disable.** Required by almost every app. |
|
|
|
|
**Legend:**
|
|
|
|
- 🟢 Safe to disable. Usually no functional impact.
|
|
- 🟠 Optional. Can be disabled, but reduces functionality.
|
|
- 🔴 Required. MUST NOT be disabled.
|
|
|
|
This is a development profile, not a production target.
|
|
|
|
When running Playwright tests, you SHOULD only disable `matomo`. All other services (🟠) are REQUIRED for full end-to-end scenario coverage. Disabling them will cause Playwright tests that depend on SSO, LDAP, theming, or logout flows to fail or produce incomplete results.
|
|
|
|
## Test Smarter
|
|
|
|
On small machines, you SHOULD limit validation to the role you are touching.
|
|
|
|
For Discourse, start with:
|
|
|
|
```bash
|
|
make compose-deploy mode=reinstall apps=web-app-discourse disable=matomo
|
|
```
|
|
|
|
If the local inventory and stack already exist, you SHOULD reuse them:
|
|
|
|
```bash
|
|
make compose-deploy mode=update apps=web-app-discourse disable=matomo
|
|
```
|
|
|
|
You SHOULD use `make compose-deploy` (full discovery) only when you need broad coverage and have enough time and resources.
|
|
|
|
## Measure Before You Delete
|
|
|
|
You SHOULD check what is actually consuming space before cleaning up:
|
|
|
|
```bash
|
|
make diagnose-disk-usage
|
|
```
|
|
|
|
That makes it easier to see whether the real issue is Docker, journald, a package cache, or project state.
|
|
|
|
## Cleanup
|
|
|
|
Run the full cleanup pass to free disk and memory:
|
|
|
|
```bash
|
|
make system-purge
|
|
```
|
|
|
|
On WSL2 or Windows, you MUST pass the additional flag to also configure and run the Windows Disk Cleanup profile.
|
|
Windows manages its own system caches independently from Linux and Docker:
|
|
|
|
```bash
|
|
make system-purge PURGE_WINDOWS_CLEANMGR_SETUP=true
|
|
```
|
|
|
|
### Further Information
|
|
|
|
- [Purge guide](../../../scripts/system/purge/README.md): Canonical entry points for cleanup.
|
|
- [Local purge guide](../../../scripts/tests/deploy/local/purge/README.md): Local deploy cleanup helpers.
|
|
- [Local reset guide](../../../scripts/tests/deploy/local/reset/README.md): Local state reset helpers.
|
|
- [Makefile commands](../tools/make.md): All available make targets.
|
|
|
|
## Discussion
|
|
|
|
Discuss this topic in the related [forum article](https://s.infinito.nexus/minpcdev).
|