ansible/roles/shell/README.md

### 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.