ilia
c3e6caf9e8
All checks were successful
CI / skip-ci-check (push) Successful in 1m18s
CI / lint-and-test (push) Successful in 1m23s
CI / ansible-validation (push) Successful in 3m2s
CI / secret-scanning (push) Successful in 1m19s
CI / dependency-scan (push) Successful in 1m24s
CI / sast-scan (push) Successful in 2m32s
CI / license-check (push) Successful in 1m23s
CI / vault-check (push) Successful in 2m22s
CI / playbook-test (push) Successful in 2m25s
CI / container-scan (push) Successful in 1m51s
CI / sonar-analysis (push) Successful in 2m32s
CI / workflow-summary (push) Successful in 1m17s
### Summary
This PR refactors the playbook layout to reduce duplication and make host intent clearer (servers vs workstations), splits monitoring by host type, and restores full Zsh setup for developers while keeping servers aliases-only.
### Key changes
- **New playbooks**
- `playbooks/servers.yml`: baseline for server-class hosts (no desktop apps)
- `playbooks/workstations.yml`: baseline for dev/desktop/local + **desktop apps only on `desktop` group**
- **Monitoring split**
- `roles/monitoring_server`: server monitoring + intrusion prevention (includes `fail2ban`, sysstat)
- `roles/monitoring_desktop`: desktop-oriented monitoring tooling
- Updated playbooks to use the correct monitoring role per host type
- **Shell role: server-safe + developer-friendly**
- `roles/shell` now supports two modes:
- `shell_mode: minimal` (default): aliases-only, does not overwrite `.zshrc`
- `shell_mode: full`: installs Oh My Zsh + Powerlevel10k + plugins and deploys a managed `.zshrc`
- `playbooks/development.yml` and `playbooks/workstations.yml` use `shell_mode: full`
- `playbooks/servers.yml` remains **aliases-only**
- **Applications**
- Applications role runs only on `desktop` group (via `workstations.yml`)
- Removed Brave installs/repo management
- Added **CopyQ** to desktop apps (`applications_desktop_packages`)
- **Docs + architecture**
- Added canonical doc tree under `project-docs/` (overview/architecture/standards/workflow/decisions)
- Consolidated architecture docs: `docs/reference/architecture.md` is now a pointer to `project-docs/architecture.md`
- Fixed broken doc links by adding the missing referenced pages under `docs/`
### Behavior changes (important)
- Desktop GUI apps install **only** on the `desktop` inventory group (not on servers, not on dev VMs unless they are in `desktop`).
- Dev/workstation Zsh is now provisioned in **full mode** (managed `.zshrc` + p10k).
### How to test (local CI parity)
```bash
make test
npm test
```
Optional dry runs (interactive sudo may be required):
```bash
make check
make check-local
```
### Rollout guidance
- Apply to a single host first:
- Workstations: `make workstations HOST=<devhost>`
- Servers: `make servers HOST=<serverhost>`
- Then expand to group runs.
Reviewed-on: #4
183 lines
6.2 KiB
Markdown
183 lines
6.2 KiB
Markdown
# Makefile Commands Reference
|
|
|
|
Complete reference for all available `make` commands in the Ansible project.
|
|
|
|
## Core Commands
|
|
|
|
### Setup & Testing
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `help` | Show all available commands | `make help` |
|
|
| `bootstrap` | Install required collections and dependencies | `make bootstrap` |
|
|
| `test` | Run all tests (lint + syntax check) | `make test` |
|
|
| `test-syntax` | Run syntax check only | `make test-syntax` |
|
|
| `lint` | Run ansible-lint on playbooks and roles | `make lint` |
|
|
| `check` | Dry-run the development playbook | `make check` |
|
|
| `check-local` | Dry-run the local playbook | `make check-local` |
|
|
|
|
### Deployment
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `apply` | Run development playbook on all dev hosts | `make apply` |
|
|
| `local` | Run local playbook on localhost | `make local` |
|
|
| `dev` | Run on specific host | `make dev HOST=dev01` |
|
|
| `quick` | Quick test and check before applying | `make quick` |
|
|
|
|
## Feature-Specific Commands
|
|
|
|
### System Maintenance
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `maintenance` | Run system maintenance | `make maintenance [GROUP=dev] [HOST=dev01]` |
|
|
| | | Options: `SERIAL=1 CHECK=true VERBOSE=true` |
|
|
| `maintenance-dev` | Run maintenance on dev group | `make maintenance-dev` |
|
|
| `maintenance-all` | Run maintenance on all hosts | `make maintenance-all` |
|
|
| `maintenance-check` | Dry-run maintenance | `make maintenance-check [GROUP=dev]` |
|
|
| `maintenance-verbose` | Maintenance with verbose output | `make maintenance-verbose [GROUP=dev]` |
|
|
|
|
### Security & Networking
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `security` | Run only security-related roles | `make security` |
|
|
| `tailscale` | Install Tailscale on all machines | `make tailscale` |
|
|
| `tailscale-check` | Check Tailscale installation (dry-run) | `make tailscale-check` |
|
|
| `tailscale-dev` | Install Tailscale on dev machines only | `make tailscale-dev` |
|
|
| `tailscale-status` | Check Tailscale status on all machines | `make tailscale-status` |
|
|
|
|
### Applications & Tools
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `docker` | Install/configure Docker only | `make docker` |
|
|
| `shell` | Configure shell only | `make shell` |
|
|
| `apps` | Install applications only | `make apps` |
|
|
| `monitoring` | Install monitoring tools | `make monitoring` |
|
|
|
|
## Infrastructure Management
|
|
|
|
### VM & Host Management
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `create-vm` | Create Ansible controller VM on Proxmox | `make create-vm` |
|
|
| `proxmox-info` | Show Proxmox guest info (LXC/VM) | `make proxmox-info [PROJECT=projectA] [ALL=true] [TYPE=lxc/qemu/all]` |
|
|
| `app-provision` | Provision app project guests on Proxmox | `make app-provision PROJECT=projectA` |
|
|
| `app-configure` | Configure OS + app on project guests | `make app-configure PROJECT=projectA` |
|
|
| `app` | Provision + configure app project guests | `make app PROJECT=projectA` |
|
|
| `ping` | Ping hosts with colored output | `make ping [GROUP=dev] [HOST=dev01]` |
|
|
| `facts` | Gather facts from all hosts | `make facts` |
|
|
| `test-connectivity` | Test network and SSH access | `make test-connectivity` |
|
|
| `show-current` | Show current host (auto-excluded) | `make show-current` |
|
|
|
|
### SSH & Vault Management
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `copy-ssh-key` | Copy SSH key to specific host | `make copy-ssh-key HOST=giteaVM` |
|
|
| `create-vault` | Create encrypted vault file | `make create-vault` |
|
|
| `edit-vault` | Edit encrypted host vars | `make edit-vault HOST=dev01` |
|
|
| `edit-group-vault` | Edit encrypted group vars (production inventory) | `make edit-group-vault` |
|
|
|
|
## Utility Commands
|
|
|
|
### Debugging & Cleanup
|
|
| Command | Description | Usage |
|
|
| --------- | ------------- | ------- |
|
|
| `debug` | Run with debug output enabled | `make debug` |
|
|
| `verbose` | Run with verbose output | `make verbose` |
|
|
| `clean` | Clean up ansible artifacts | `make clean` |
|
|
|
|
## Command Options
|
|
|
|
### Common Variables
|
|
Many commands accept these optional variables:
|
|
|
|
| Variable | Description | Example |
|
|
| ---------- | ------------- | --------- |
|
|
| `HOST` | Target specific host | `HOST=dev01` |
|
|
| `GROUP` | Target specific group | `GROUP=dev` |
|
|
| `CHECK` | Run in check mode (dry-run) | `CHECK=true` |
|
|
| `VERBOSE` | Enable verbose output | `VERBOSE=true` |
|
|
| `SERIAL` | Run on hosts one at a time | `SERIAL=1` |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Deploy to specific host
|
|
make dev HOST=bottom
|
|
|
|
# Maintenance with options
|
|
make maintenance GROUP=dev SERIAL=1 CHECK=true
|
|
|
|
# Test connectivity to specific group
|
|
make ping GROUP=gitea
|
|
|
|
# Edit vault for specific host
|
|
make edit-vault HOST=portainerVM
|
|
|
|
# Dry-run on production
|
|
make check GROUP=prod
|
|
```
|
|
|
|
## Workflow Examples
|
|
|
|
### Initial Setup
|
|
```bash
|
|
make bootstrap
|
|
make create-vault
|
|
make test
|
|
make check
|
|
make apply
|
|
```
|
|
|
|
### Adding New Host
|
|
```bash
|
|
make copy-ssh-key HOST=newhost
|
|
make edit-vault HOST=newhost
|
|
make dev HOST=newhost
|
|
```
|
|
|
|
### System Maintenance
|
|
```bash
|
|
make maintenance-check
|
|
make maintenance GROUP=dev
|
|
make maintenance-all
|
|
```
|
|
|
|
### Feature Deployment
|
|
```bash
|
|
# Deploy specific features
|
|
make docker
|
|
make tailscale
|
|
make monitoring
|
|
```
|
|
|
|
### Troubleshooting
|
|
```bash
|
|
make test-connectivity
|
|
make facts
|
|
make ping GROUP=dev
|
|
make debug
|
|
```
|
|
|
|
## Tips & Best Practices
|
|
|
|
1. **Always test first**: Use `check` commands before applying changes
|
|
2. **Use groups**: Target specific groups instead of all hosts
|
|
3. **Verbose for debugging**: Add `VERBOSE=true` when troubleshooting
|
|
4. **Serial for safety**: Use `SERIAL=1` for critical changes
|
|
5. **Check mode**: Use `CHECK=true` to preview changes
|
|
|
|
## Environment Variables
|
|
|
|
The Makefile respects these environment variables:
|
|
|
|
| Variable | Description | Default |
|
|
| ---------- | ------------- | --------- |
|
|
| `ANSIBLE_CONFIG` | Ansible configuration file | `./ansible.cfg` |
|
|
| `ANSIBLE_VAULT_PASSWORD_FILE` | Vault password file | `~/.ansible-vault-pass` |
|
|
| `ANSIBLE_HOST_KEY_CHECKING` | SSH host key checking | `False` |
|
|
|
|
## Getting Help
|
|
|
|
- Run `make help` to see all available commands
|
|
- Commands with `##` comments appear in help output
|
|
- Check individual role documentation in `roles/*/README.md`
|
|
- Review playbook files for available tags |