A curated collection of technical references, operational procedures, security practices, and reusable engineering guides for developer workstations and cloud environments.
This repository provides concise and maintainable documentation for knowledge that should remain easy to find, review, and reuse. Each document favors clear reasoning, safe defaults, and commands that can be verified before use.
Documents are organized by knowledge area and then by topic. Every document is self-contained: it states what the subject is, why the procedure matters, how to perform it, and how to verify the result. Cross-references at the end of each document connect related topics and cite upstream documentation.
The material targets macOS workstations running Homebrew-managed toolchains, but most procedures translate directly to Linux hosts. Commands that are specific to a platform are marked as such.
| Area | Scope |
|---|---|
| Cloud | Cloud platforms, identity, temporary credentials, and deployment practices |
| Languages | Runtimes, interpreters, environment isolation, and dependency management |
| Operating systems | macOS administration, developer toolchains, and shell environments |
| Security | Credential storage, secret handling, key management, and commit signing |
| Tooling | Containers, package managers, version control, and developer automation |
Amazon Web Services command-line access, credential resolution, and role assumption.
| Document | Scope |
|---|---|
| CLI installation and configuration | Installing the AWS CLI, verifying the version, and establishing a working configuration |
| Profiles and configuration files | The config and credentials files, profile precedence, and environment overrides |
| Temporary credentials with aws-vault | Storing long-lived keys in the Keychain and issuing short-lived session credentials |
| Role assumption and identity verification | Assuming roles across accounts, multi-factor authentication, and confirming the effective identity |
Python interpreters, isolation, and packaging.
| Document | Scope |
|---|---|
| Interpreters and installation | System versus managed interpreters, version selection, and installation paths |
| Virtual environments | Creating, activating, and maintaining isolated environments |
| Dependency management | Installing, pinning, auditing, and upgrading dependencies reproducibly |
| Project metadata and packaging | Project layout, pyproject.toml, builds, and distribution |
macOS system maintenance and the developer toolchain.
| Document | Scope |
|---|---|
| System updates | Listing, applying, and verifying operating system and security updates |
| Xcode and Command Line Tools | Installing, updating, and repairing the compiler toolchain and SDKs |
| Developer directory and shell environment | Selecting the active developer directory and configuring shell startup files |
Credential storage, secret hygiene, and cryptographic keys.
| Document | Scope |
|---|---|
| macOS Keychain | Storing, retrieving, updating, and deleting secrets with the security command |
| Secret handling in repositories | Preventing, detecting, and remediating secrets committed to version control |
| SSH key management | Generating, protecting, distributing, and rotating SSH key pairs |
| Git commit signing | Signing commits and tags with SSH or GPG keys and verifying signatures |
Containers, package managers, version control, and Node.js.
| Document | Scope |
|---|---|
| Docker installation and runtime | Installing a container runtime, verifying it, and managing its resources |
| Images and containers | Building, inspecting, running, and removing images and containers |
| Volumes and data safety | Persistent storage, bind mounts, backups, and destructive-command safeguards |
| Compose and container security | Multi-service definitions, secret injection, and hardening defaults |
| Homebrew package operations | Installing, upgrading, inspecting, and pinning formulae and casks |
| Homebrew maintenance and reproducibility | Diagnostics, cleanup, tap trust, and reproducing a workstation with a Brewfile |
| Git configuration and credentials | Identity scoping, configuration precedence, and credential helpers |
| Node.js runtime management | Installing and switching runtime versions and pinning them per project |
| Node.js dependency management | Lockfiles, reproducible installs, auditing, and upgrade strategy |
Documents follow a two-level structure: a knowledge area, then a topic directory when the area contains more than one closely related document.
docs/<area>/<topic>/<document-name>.md
Current layout:
docs/
cloud/aws/
languages/python/
operating-systems/macos/
security/credentials/
security/keys/
tooling/docker/
tooling/git/
tooling/homebrew/
tooling/nodejs/
Filenames are lowercase, hyphen-separated, and semantic. They describe the subject rather than the tool version or the date of writing.
- Use formal, objective, technical English.
- Open every document with a
# Titlefollowed by an## Overviewsection. - Explain the purpose and the risk of a command before presenting it.
- Annotate every fenced code block with its language.
- Use angle-bracket placeholders such as
<profile-name>instead of real credentials, account identifiers, hostnames, or environment-specific values. - Distinguish verified behavior from recommendations and local conventions.
- Keep procedures reproducible and update them when their dependencies change.
- Close every document with a
## Related Documentationsection that links sibling documents and cites upstream sources. - Link every new document from this index.
This repository must never contain passwords, API keys, tokens, private keys, recovery codes, unredacted configuration files, or screenshots containing sensitive information.
Examples are documentation only. Review every command and replace placeholders with values appropriate for the target environment before execution. Commands that delete data, rewrite history, or modify system state are marked as destructive in the documents that present them.
Released under the MIT License. See LICENSE.