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)

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

1. Reload Configuration:

   source ~/.zshrc
   

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