Principles
These principles guide changes to the workstation setup documentation and automation.
Reproducibility
A new team member should be able to rebuild a workstation from documented steps, committed Ansible roles, and clearly marked manual actions. Prefer commands that can be rerun safely.
Open-source orientation
Prefer open-source tools and documented system packages where they meet the lab need. Use external proprietary services only when they are an explicit requirement and document the manual account or GUI setup they need.
Security and least surprise
Do not silently overwrite user configuration, disable security features, or handle private keys automatically. Make risky or manual steps visible, explain why they are needed, and provide verification commands where possible.
Simplicity
Keep roles focused, commands copy-pasteable, and documentation short enough to follow during an actual setup. Avoid speculative sections and long duplicate reference tables.
Layered ownership
Keep configuration useful to all or most lab workstations in this shared baseline. Personal overlays may depend on the shared infrastructure, but the shared repository must remain complete and usable without them. The topmost layer owns the final audit.
Documentation as configuration
Documentation is part of the setup. When a role, tag, command, or manual step changes, update the corresponding page so that the website remains an accurate workstation manual.