ansible/roles/shell

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)

- hosts: servers
  roles:
    - role: shell

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

1. Customize Powerlevel10k:

   p10k configure
   

2. Reload Configuration:

   source ~/.zshrc
   

3. View Available Aliases:

   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:

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:

roles:
  - user
  - shell

With Data Science Role

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

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:

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.