computer-playbook/docs/contributing/tools/makefile.md

Makefile Commands

Use these commands from the repository root. This is the SPOT for make targets in Infinito Nexus. Use the dedicated script READMEs for the underlying shell helpers, and use the development/testing guides for deeper workflow details.

Image Builds

Category	Command	What it does	When to use it
Build	make build	Builds the local image for the active INFINITO_DISTRO.	Use this after Dockerfile changes or whenever you want a fresh local image.
Build if missing	make build-missing	Builds the image only when it is not already present locally.	Use this for a quick local check when you do not want to rebuild unnecessarily.
No-cache build	make build-no-cache	Rebuilds the image without Docker cache.	Use this when cache reuse might hide a change or when you are debugging the build.
No-cache all distros	make build-no-cache-all	Rebuilds the no-cache image for every distro in DISTROS.	Use this for release-level validation or when you need to verify all distro variants.
Build dependency image	make build-dependency	Pulls the pkgmgr base image used by the build.	Use this when you want to refresh the base image or debug build inputs.
Cleanup CI images	make build-cleanup	Removes Docker images created for CI-style build workflows.	Use this when local disk usage grows or old CI images accumulate.
Regenerate Docker ignore	make dockerignore	Regenerates .dockerignore from .gitignore.	Use this when the Docker ignore file needs to be refreshed.

Install

Category	Command	What it does	When to use it
System Python prerequisites	make install-system-python	Installs the system Python prerequisites.	Use this when the host is missing the Python base packages.
Virtual environment	make install-venv	Creates the virtual environment.	Use this when you need the repository Python environment.
Python tooling	make install-python	Installs the Python tooling.	Use this when you need the Python toolchain after creating the virtual environment.
Ansible dependencies	make install-ansible	Installs the Ansible dependencies.	Use this when you changed Ansible-related code or need the Ansible collections.
Lint dependencies	make install-lint	Installs lint-related tooling.	Use this when you only need the lint stack.
Full install	make install	Installs the repository tooling needed for development and tests.	Use this on a fresh machine or before validation.

Environment Setup

Category	Command	What it does	When to use it
Environment bootstrap	make environment-bootstrap	Runs the local bootstrap sequence for WSL2, lint tooling, AppArmor, DNS, and IPv6.	Use this when you want to prepare a fresh development host.
Environment teardown	make environment-teardown	Reverses the local bootstrap sequence.	Use this when you want to restore host settings.
Enable WSL2 systemd	make wsl2-systemd-check	Ensures WSL2 systemd support is configured.	Use this before WSL2-specific setup that depends on systemd.
Set up DNS on WSL2	make wsl2-dns-setup	Configures DNS for WSL2.	Use this when you are working in WSL2 and need local DNS routing.
Configure DNS	make dns-setup	Configures DNS on the current host.	Use this for Linux host DNS setup.
Remove DNS	make dns-remove	Removes the DNS configuration.	Use this to clean up the DNS setup.
Trust CA on Windows	make wsl2-trust-windows	Imports the local CA and updates hosts entries from WSL2.	Use this when you need Windows trust-store updates from WSL2.
Trust local CA	make trust-ca	Trusts the local CA on Linux and WSL2.	Use this after the CA or host entries change.
Disable IPv6	make disable-ipv6	Disables IPv6 for local development.	Use this when a workflow needs IPv6 off.
Restore IPv6	make restore-ipv6	Restores the previous IPv6 settings.	Use this after a temporary IPv6 change.

Repository Setup and Discovery

Category	Command	What it does	When to use it
Setup	make setup	Runs the repository setup step after generating .dockerignore.	Use this when you want the baseline project setup without installing the full dev stack.
Setup development	make setup-development	Creates the development setup marker.	Use this when you want to prepare a development-specific setup state.
Bootstrap	make bootstrap	Installs dependencies and prepares the project.	Use this on a fresh machine or a new checkout.
Setup clean	make setup-clean	Cleans ignored files and then runs setup.	Use this when you want a clean setup pass.
List roles	make list	Prints the repository role list.	Use this when you need the current role inventory.
Tree view	make tree	Prints the repository tree.	Use this when you want a compact structural overview.
Meta graph inputs	make mig	Builds the meta graph inputs from list and tree.	Use this when you are generating or refreshing meta graph data.

Runtime Stack

Category	Command	What it does	When to use it
Start stack	make up	Starts the local compose stack and builds the image if it is missing.	Use this to bring the development stack online.
Stop stack	make down	Stops the compose stack and removes volumes.	Use this when you want a clean shutdown and disposable local state.
Pause services	make stop	Stops running services without removing volumes.	Use this when you want a fast stop and plan to start the same state again.
Restart stack	make restart	Stops the stack and starts it again.	Use this after configuration changes or when the stack needs a full restart.
Inspect container	make exec	Opens an interactive shell in the running infinito container.	Use this when you need to inspect live state or run a quick command inside the container.

Validation

Lint

Category	Command	What it does	When to use it
Install lint tooling	make install-lint	Installs lint-related tooling.	Use this when you only need the lint stack.
Lint	make lint	Runs the main lint checks for the repository.	Use this when you want a broad lint pass before pushing.
Lint test suite	make test-lint	Runs the lint test suite inside the development environment.	Use this when you want CI-like lint validation.
Lint action	make lint-action	Runs the GitHub Actions lint checks.	Use this when you changed workflow files or workflow logic.
Lint Ansible	make lint-ansible	Runs the Ansible lint checks.	Use this when you changed Ansible roles, inventories, or playbook-related files.
Lint Python	make lint-python	Runs the Python lint checks.	Use this when you changed Python code.
Lint shell	make lint-shellcheck	Runs shellcheck lint checks.	Use this when you changed shell scripts.

Test

Category	Command	What it does	When to use it
Install dependencies	make install	Installs the repository tooling needed for development and tests.	Use this before running validation on a fresh machine or environment.
Unit tests	make test-unit	Runs the unit test suite.	Use this when you changed Python logic or other isolated code paths.
Integration tests	make test-integration	Runs the integration test suite.	Use this when your change affects behavior across modules or runtime boundaries.
Combined validation	make test	Runs the main combined validation flow.	Use this whenever a change touches at least one file that is not .md or .rst, or before opening a Pull Request.

Act

Category	Command	What it does	When to use it
Act workflow suite	make act-all	Runs the full local Act workflow suite.	Use this when you want to verify workflow behavior locally.
Act app workflow	make act-app	Runs the app-focused Act checks.	Use this when you are changing app-scoped workflow logic.
Act workflow file	make act-workflow	Runs one selected workflow with Act.	Use this when you want to focus on a single workflow file.

Cleanup

Category	Command	What it does	When to use it
Remove ignored files	make clean	Removes ignored files from the working tree.	Use this when you want to clear generated files without sudo.
Remove ignored files with sudo	make clean-sudo	Removes ignored files from the working tree with elevated privileges.	Use this when file ownership prevents a normal clean.
System purge	make purge-system	Runs scripts/system/purge/system.sh to clear repository, Docker, journald, package, and language caches.	Use this when disk usage is tight or you want the broad low-hardware cleanup pass.
Full purge	make purge-all	Runs scripts/system/purge/all.sh, which chains make container-purge-system, make build-cleanup, and make purge-system.	Use this when you want the broadest local cleanup bundle.
Refresh inventory	make container-refresh-inventory	Recreates the local inventory without deploying apps.	Use this when your local inventory is broken or you want a clean reset.
Purge app entity	make container-purge-entity	Purges one or more app entities inside the running container.	Use this before rerunning a purged app deployment.
Purge container state	make container-purge-system	Removes inventory, web config, and lib state in the running container.	Use this when you want a destructive local container reset.

Local Deploy

Category	Command	What it does	When to use it
Fresh kept app	make deploy-fresh-kept-app	Creates a new inventory and deploys one app.	Use this for the single-app fresh path.
Fresh purged app	make deploy-fresh-purged-app	Creates a new inventory, purges the app state, and redeploys one app.	Use this when you want a fresh app after cleanup.
Reuse kept app	make deploy-reuse-kept-app	Reuses an existing inventory and redeploys one app quickly.	Use this for the fast reuse path.
Reuse purged app	make deploy-reuse-purged-app	Reuses an existing inventory, purges the app state first, and redeploys one app quickly.	Use this when you want a fast reset-and-redeploy path.
Fresh kept all	make deploy-fresh-kept-all	Builds the broader local deployment flow across apps.	Use this when you explicitly need broad coverage.
Reuse kept all	make deploy-reuse-kept-all	Reuses the existing inventory and redeploys the broad app set.	Use this for the faster broad reuse path.

Notes

• The commands use the current INFINITO_DISTRO setting from the environment where relevant.
• For app-level local deploy flows and end-to-end checks, see Development.
• For validation strategy and Playwright guidance, see Testing and Validation.