ansible

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)

- hosts: servers
  roles:
    - role: shell

Full Zsh for developer machines

- hosts: dev
  roles:
    - role: shell
      vars:
        shell_mode: full
        shell_set_default_shell: true

Configure Multiple Users

- hosts: servers
  roles:
    - role: shell
      shell_users:
        - root
        - ladmin
        - beast
        - user

Host-Specific Configuration

In host_vars/server01.yml:

shell_users:
  - root
  - myuser
  - developer

Usage

Default (Ansible User Only)

make shell HOST=dev01

Configure Additional Users

Add to host_vars file:

# host_vars/devGPU.yml
shell_users:
  - root
  - beast
  - ladmin

Then run:

make dev HOST=devGPU --tags shell

Post-Installation

For Each Configured User

The aliases are immediately available in new shells. Users can:

Reload Configuration:
```
source ~/.zshrc
```
View Available Aliases:
```
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:

roles:
  - user
  - shell

With Data Science Role

Conda initialization is included in .zshrc. Run datascience role after shell:

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.