mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
kevinveenbirkenbachandClaude Opus 5
af605b049f
RFC 6761 reserves .test for testing and .example for documentation, and the project's own domain was doing both jobs under the documentation name. It is what default.env hands every local deploy and what the test fixtures assert against, so it is a testing name. Rename it wherever it stands for the running machine: the environment defaults, the development inventory, the workspace and trust scripts, the test suites, and the four documents that describe real behaviour - the DNS mapping to loopback, the browser CA trust, WSL2 resolution. Those documents would have started lying the moment default.env changed. The sandbox allowlist moves with them, since egress is matched per pattern and nothing resolves the old name any more, and the sandbox document that mirrors that list follows it. Two places keep .example on purpose: the link-style sample in the documentation guide, which is documentation about documentation, and every generic fixture name elsewhere in the suite - a.example, foo.example and their kin. Those are a larger sweep of their own and are not touched here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# Development Environment Setup 🛠️
|
|
|
|
Use the repository's real setup flow. The main source of truth is the [Makefile](../../../Makefile).
|
|
|
|
Important:
|
|
|
|
- Some local development commands change host settings such as [DNS](https://en.wikipedia.org/wiki/Domain_Name_System), [AppArmor](https://en.wikipedia.org/wiki/AppArmor), and [IPv6](https://en.wikipedia.org/wiki/IPv6).
|
|
- Some commands use `sudo`.
|
|
- Read the setup guides first if you are new to this environment.
|
|
- The local development workflow is mainly tested on Linux.
|
|
|
|
## Platform-Specific Instructions 🖥️
|
|
|
|
- [Linux](platform/linux.md)
|
|
- [macOS](platform/macos.md)
|
|
- [Windows (WSL2)](platform/windows-wsl2.md)
|
|
|
|
## Shared Repository Workflow 🔄
|
|
|
|
These steps are the shared repository workflow and apply regardless of whether you work on Linux, macOS, or Windows with WSL2.
|
|
|
|
### Bootstrap 🚀
|
|
|
|
Run these commands from the repository root:
|
|
|
|
```bash
|
|
make bootstrap
|
|
make environment-bootstrap
|
|
make compose-up
|
|
make network-trust-ca
|
|
```
|
|
|
|
#### Bootstrap Commands 📋
|
|
|
|
| Phase | Command | What it does |
|
|
|---|---|---|
|
|
| Initial setup | `make bootstrap` | Installs project dependencies and runs the first repository setup. |
|
|
| Host preparation | `make environment-bootstrap` | Prepares the local development machine for the project workflow. |
|
|
| Start stack | `make compose-up` | Starts the local development stack. |
|
|
| Browser trust | `make network-trust-ca` | Trusts the generated local [CA](https://en.wikipedia.org/wiki/Certificate_authority) so `*.infinito.test` works correctly in your browser. |
|
|
|
|
The `pre-commit` hooks are installed automatically by `make environment-bootstrap`.
|
|
Per-machine overrides go into the process environment before invoking `make` (e.g. `export INFINITO_FOO=…`); `make dotenv` honors caller-set values via setdefault semantics.
|
|
|
|
### Teardown 🧹
|
|
|
|
When you are done, use these commands to stop the stack and clean up the local environment:
|
|
|
|
```bash
|
|
make compose-down
|
|
make environment-teardown
|
|
```
|
|
|
|
#### Teardown Commands 📋
|
|
|
|
| Phase | Command | What it does |
|
|
|---|---|---|
|
|
| Stop stack | `make compose-down` | Stops the local development stack. |
|
|
| Host cleanup | `make environment-teardown` | Reverts local development environment changes where supported. |
|
|
|
|
### Full Development Flow 🔁
|
|
|
|
The repository already contains a modular environment test suite at [scripts/tests/workspace/](../../../scripts/tests/workspace/README.md). The commands from that suite are explained here as the intended end-to-end flow.
|
|
|
|
#### Flow Summary 📋
|
|
|
|
| Step | Command | Purpose in this flow |
|
|
|---|---|---|
|
|
| 1 | `make install` | Installs the dependencies needed before running the local development flow. |
|
|
| 2 | `make environment-bootstrap` | Prepares the host machine for local development. |
|
|
| 3 | `make compose-up` | Starts the development stack. |
|
|
| 4 | `make test` | Runs the main combined validation flow. |
|
|
| 5 | `make compose-deploy mode=reinstall apps=web-app-matomo` | Runs the baseline validation path for one concrete app. For the retry-loop policy, see [Compose Loop](../../agents/action/iteration/compose.md). |
|
|
| 6 | `make network-trust-ca` | Makes the generated local certificates trusted by the host browser. |
|
|
| 7 | `make compose-down` | Stops the running development stack. |
|
|
| 8 | `make environment-teardown` | Cleans up host-side development environment changes. |
|
|
|
|
Use this as a practical reference when you want to understand how local development is expected to work.
|
|
|
|
### Minimal Hardware Resources 💾
|
|
|
|
If you work on a machine with limited CPU, RAM, or disk space, use the guide at [hardware.md](hardware.md).
|
|
The public article with the same topic is [here](https://s.infinito.nexus/minpcdev).
|
|
|
|
For local deploy shortcuts and end-to-end checks, see [testing.md](../actions/testing.md).
|