183 lines
4.0 KiB
Markdown
183 lines
4.0 KiB
Markdown
### Role: shell
|
|
|
|
## Description
|
|
Configures shell in one of two modes:
|
|
|
|
- **minimal**: aliases-only (safe for servers; does not overwrite `~/.zshrc`)
|
|
- **full**: installs Oh My Zsh + Powerlevel10k + plugins and deploys a managed `~/.zshrc` (intended for developer machines)
|
|
|
|
## Requirements
|
|
- Ansible 2.9+
|
|
- Debian/Ubuntu systems
|
|
- Users must exist before running this role
|
|
|
|
## Installed Components
|
|
|
|
### Shell Environment
|
|
- **zsh**: Z shell
|
|
- **tmux**: Terminal multiplexer
|
|
- **fzf**: Fuzzy finder
|
|
- **oh-my-zsh / powerlevel10k**: only in `shell_mode=full`
|
|
|
|
### Configuration Files
|
|
- `~/.zsh_aliases_ansible`: Managed aliases file (sourced from `~/.zshrc`)
|
|
- `~/.zshrc`: appended in `minimal` mode; fully managed in `full` mode
|
|
- `~/.p10k.zsh`: only in `shell_mode=full`
|
|
|
|
## Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `shell_users` | `[ansible_user]` | List of users to configure zsh for |
|
|
| `shell_packages` | `['zsh','tmux','fzf']` | Packages installed by the role |
|
|
| `shell_mode` | `minimal` | `minimal` (aliases-only) or `full` (oh-my-zsh + p10k + managed zshrc) |
|
|
| `shell_set_default_shell` | `false` | If true, set login shell to `/usr/bin/zsh` |
|
|
|
|
## Dependencies
|
|
None
|
|
|
|
## Example Playbook
|
|
|
|
### Configure Only Ansible User (Default)
|
|
```yaml
|
|
- hosts: servers
|
|
roles:
|
|
- role: shell
|
|
```
|
|
|
|
### Full Zsh for developer machines
|
|
```yaml
|
|
- hosts: dev
|
|
roles:
|
|
- role: shell
|
|
vars:
|
|
shell_mode: full
|
|
shell_set_default_shell: true
|
|
```
|
|
|
|
### Configure Multiple Users
|
|
```yaml
|
|
- hosts: servers
|
|
roles:
|
|
- role: shell
|
|
shell_users:
|
|
- root
|
|
- ladmin
|
|
- beast
|
|
- user
|
|
```
|
|
|
|
### Host-Specific Configuration
|
|
In `host_vars/server01.yml`:
|
|
```yaml
|
|
shell_users:
|
|
- root
|
|
- myuser
|
|
- developer
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Default (Ansible User Only)
|
|
```bash
|
|
make shell HOST=dev01
|
|
```
|
|
|
|
### Configure Additional Users
|
|
Add to host_vars file:
|
|
```yaml
|
|
# host_vars/devGPU.yml
|
|
shell_users:
|
|
- root
|
|
- beast
|
|
- ladmin
|
|
```
|
|
|
|
Then run:
|
|
```bash
|
|
make dev HOST=devGPU --tags shell
|
|
```
|
|
|
|
## Post-Installation
|
|
|
|
### For Each Configured User
|
|
The aliases are immediately available in new shells. Users can:
|
|
|
|
1. **Reload Configuration**:
|
|
```bash
|
|
source ~/.zshrc
|
|
```
|
|
|
|
2. **View Available Aliases**:
|
|
```bash
|
|
alias # List all aliases
|
|
```
|
|
|
|
## Features
|
|
|
|
### Custom Aliases
|
|
The role installs a small, server-safe alias set in `~/.zsh_aliases_ansible`.
|
|
|
|
## Notes
|
|
|
|
- The role is idempotent - safe to run multiple times
|
|
- Existing `.zshrc` files are **not** overwritten
|
|
- The role skips users that don't exist on the system
|
|
|
|
## Troubleshooting
|
|
|
|
### User Not Found
|
|
If a user in `shell_users` doesn't exist:
|
|
```
|
|
User username not found, skipping shell configuration
|
|
```
|
|
Solution: Ensure the user exists or remove from `shell_users` list.
|
|
|
|
### Oh My Zsh Installation Fails
|
|
If `shell_mode=full`, ensure the host has outbound internet access to fetch the installer and clone git repos.
|
|
|
|
### Powerlevel10k Not Loading
|
|
Only applies to `shell_mode=full`. Verify `~/.p10k.zsh` exists and the theme repo is present under `~/.oh-my-zsh/custom/themes/powerlevel10k`.
|
|
|
|
### Conda Not Initialized
|
|
`shell_mode=full` includes a minimal “initialize conda if present” block. Conda installation is still handled by the `datascience` role.
|
|
|
|
## Integration
|
|
|
|
### With User Role
|
|
The user role should run before the shell role to ensure users exist:
|
|
```yaml
|
|
roles:
|
|
- user
|
|
- shell
|
|
```
|
|
|
|
### With Data Science Role
|
|
Conda initialization is included in `.zshrc`. Run datascience role after shell:
|
|
```yaml
|
|
roles:
|
|
- shell
|
|
- datascience
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- Only an aliases file is managed; no remote scripts/themes are downloaded.
|
|
- Consider limiting which users get shell configuration on production servers
|
|
|
|
## Performance
|
|
|
|
- Installation time: seconds per user (copy + lineinfile)
|
|
- Disk space: negligible
|
|
|
|
## Customization
|
|
|
|
### Adding Custom Aliases
|
|
Edit `roles/shell/files/ansible_aliases.zsh` and re-run the role.
|
|
|
|
### Adding More Plugins
|
|
Out of scope for this role (keep it fast/minimal).
|
|
|
|
### Custom Theme
|
|
Out of scope for this role.
|