ansible/roles/shell/README.md

### Role: shell

## Description
Configures modern shell environment with zsh, Oh My Zsh, Powerlevel10k theme, and useful plugins. Can be configured for multiple users on the same host.

## Requirements
- Ansible 2.9+
- Debian/Ubuntu systems
- Users must exist before running this role

## Installed Components

### Shell Environment
- **zsh**: Z shell
- **Oh My Zsh**: Zsh configuration framework
- **Powerlevel10k**: Modern, feature-rich theme
- **tmux**: Terminal multiplexer
- **fzf**: Fuzzy finder

### Zsh Plugins
- **zsh-syntax-highlighting**: Syntax highlighting for commands
- **zsh-autosuggestions**: Fish-like autosuggestions

### Configuration Files
- `.zshrc`: Custom zsh configuration with conda support
- `.p10k.zsh`: Powerlevel10k theme configuration

## Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `shell_users` | `[ansible_user]` | List of users to configure zsh for |
| `zsh_plugins` | See defaults/main.yml | List of zsh plugins to install |

## Dependencies
None

## Example Playbook

### Configure Only Ansible User (Default)
```yaml
- hosts: servers
  roles:
    - role: shell
```

### 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 shell configuration is immediately active. Users can:

1. **Customize Powerlevel10k**:
   ```bash
   p10k configure
   ```

2. **Reload Configuration**:
   ```bash
   source ~/.zshrc
   ```

3. **View Available Aliases**:
   ```bash
   alias  # List all aliases
   ```

## Features

### Custom Aliases
The `.zshrc` includes aliases for:
- Git operations (`gs`, `ga`, `gc`, etc.)
- Docker (`dps`, `dex`, `dlogs`)
- System (`ll`, `la`, `update`, `sysinfo`)
- Networking (`ports`, `myip`)
- Development (`serve`, `mkcd`)
- Data Science (`jup`, `conda-list`, `r-studio`)

### Conda Integration
If Anaconda is installed (via datascience role), conda is automatically initialized in zsh.

### Root User Support
Includes special aliases for root users (IDEs with `--no-sandbox` flags).

## Notes

- Zsh is set as the default shell for all configured users
- Oh My Zsh is installed in each user's home directory
- The role is idempotent - safe to run multiple times
- Existing `.zshrc` files are overwritten
- Users must log out and back in for shell changes to take effect
- 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
Check user has a valid home directory and write permissions.

### Powerlevel10k Not Loading
Verify the theme is cloned:
```bash
ls ~/.oh-my-zsh/custom/themes/powerlevel10k
```

### Conda Not Initialized
The datascience role must be run to install Anaconda. The shell role only adds the initialization code to `.zshrc`.

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

- The `.zshrc` is deployed from a template - review before deploying to production
- Root aliases include `--no-sandbox` flags for IDEs (required for root but less secure)
- Consider limiting which users get shell configuration on production servers

## Performance

- Installation time: ~2-3 minutes per user
- Disk space: ~10MB per user (Oh My Zsh + plugins + theme)
- First shell launch: ~1-2 seconds (Powerlevel10k initialization)
- Subsequent launches: <0.5 seconds

## Customization

### Adding Custom Aliases
Edit `roles/shell/files/.zshrc` and add your aliases.

### Adding More Plugins
Update `roles/shell/defaults/main.yml`:
```yaml
zsh_plugins:
  - name: "my-plugin"
    repo: "https://github.com/user/my-plugin.git"
```

### Custom Theme
Replace Powerlevel10k in tasks if desired, or users can run `p10k configure` to customize.