viasite-ansible.zsh

Tested Environments

This software has been tested on:

• Ubuntu 20.04
• Ubuntu 22.04
• Ubuntu 24.04
• MacOS 14.4

Older versions tested include:

• Ubuntu 18.04
• MacOS 10.12
• CentOS 8

For instructions on upgrading from viasite-ansible.zsh versions 1.x or 2.x to 3.0, see below.

Simple Installation

If you are using Ubuntu or Debian and are not familiar with Ansible, you can run the following command on your target machine:

curl https://raw.githubusercontent.com/viasite-ansible/ansible-role-zsh/master/install.sh | bash

This will install Pip3, Ansible, and set up Zsh for both the root user and the current user.

MacOS Simple Installation

Requirements: Homebrew and Python. This script will ask for your password. You can run:

curl https://raw.githubusercontent.com/viasite-ansible/ansible-role-zsh/master/install-macos.sh | bash

This will install Ansible and configure Zsh for your user and optionally for the root user as well.

Then follow the instructions to configure your terminal application.

Components Included

• Zsh
• Antigen
• Oh-My-Zsh
• Powerlevel9k Theme
• Zsh Autosuggestions
• Zsh Syntax Highlighting
• Auto-update Antigen Plugin
• Fzf Widgets
• Fzf Marks

Features

• Customize the Powerlevel9k theme prompt colors and segments.
• Tested default colors with Solarized Dark and default gray in Putty.
• Add custom prompt elements using YAML files.
• Custom Zsh configuration using ~/.zshrc.local or /etc/zshrc.local.
• Load scripts from /etc/profile.d.
• Install only useful plugins according to your machine's environment (e.g., Docker is only installed if Docker is present).

Demo

Here's a short demo video showcasing the installation and usage:

And a demo of color schemes:

Midnight Commander with Solarized Dark Theme

If you are using the Solarized Dark theme with Midnight Commander, you can install a special skin and set zsh_mc_solarized_skin: yes.

Testing in Vagrant

You can test the functionality of this role in a Vagrant environment before installing it on your actual machine. Just run vagrant up, and then vagrant ssh to enter the virtual machine.

Note: You cannot install Vagrant on a VPS like Digital Ocean or in Docker; use a local machine instead. Download and install Vagrant according to your operating system.

Installation on Actual Machine

For a simple installation, follow the instructions above.

Manual Installation Steps

1. Install Ansible: Follow the Ansible installation guide. For Ubuntu, run:

   sudo apt update
   sudo apt install python3-pip -y
   sudo pip3 install ansible
   

2. Download the Role:

   ansible-galaxy install viasite-ansible.zsh --force
   

3. Create a Playbook (or use the provided playbook.yml):

   - hosts: all
     vars:
       zsh_antigen_bundles_extras:
         - nvm
         - joel-porquet/zsh-dircolors-solarized
       zsh_autosuggestions_bind_key: "^U"
     roles:
       - viasite-ansible.zsh
   

4. Run the Playbook:

   ansible-playbook -i "localhost," -c local -K playbook.yml
   

For installing Zsh for the root user on macOS, manually install the necessary packages:

brew install zsh git wget

If you want to set up Zsh for additional users, define the zsh_user variable.

For Playbook:

- hosts: all
  roles:
    - { role: viasite-ansible.zsh, zsh_user: otheruser }
    - { role: viasite-ansible.zsh, zsh_user: thirduser }

For Command Line:

ansible-playbook -i hosts zsh.yml -e zsh_user=otheruser

5. Install Fzf (without shell extensions): You can download binaries or run brew install fzf for macOS.

Note: I do not use tmux-fzf and have not tested its functionality.

Shared Multi-user Installation

If you have many users on the host, you might want to manage a single shared configuration for all users, rather than numerous individual setups.

This method has some limitations:

• Users have read-only access to the shared Zsh config.
• Users cannot disable globally enabled bundles.
• Possible permission issues with cache writing.
• Potential problems with themes from Oh-My-Zsh.

To install a shared configuration, set zsh_shared: yes. It will be placed in /usr/share/zsh-config, which can then be included in user configurations.

Install for All Users

Set zsh_source_for_all_users: yes

source /usr/share/zsh-config/.zshrc

This setup allows custom configurations for specific users as needed.

Configuration

Do not edit ~/.zshrc! Instead, add any custom configurations to ~/.zshrc.local (for individual users) or /etc/zshrc.local (for global settings). The .zshrc.local file will not be modified by Ansible.

Configure Terminal Application

1. Download Fonts: Get Powerline fonts and install your preferred font. You can see examples here.

2. Set Color Scheme: Personally, I like the Solarized Dark theme, using Droid Sans Mono on iTerm and DejaVu Sans Mono on Putty.

   For iTerm:

   • Go to Profiles -> Text -> Change Font and select the font "for Powerline".
   • Navigate to Profiles -> Colors -> Color Presets and choose Solarized Dark.

   For Putty:

   • Go to Settings -> Window -> Appearance -> Font settings. You can download Solarized Dark for Putty.

   For Gnome Terminal: Gnome Terminal has built-in Solarized Dark. Be sure to select both the background color scheme and the palette.

Hotkeys

You can find hotkey definitions in the defaults/main.yml, under zsh_hotkeys.

Example hotkey definitions:

- { hotkey: '^r', action: 'fzf-history' }
# with dependency of a bundle
- { hotkey: '`', action: autosuggest-accept, bundle: zsh-users/zsh-autosuggestions }

Feel free to add your custom hotkeys using the zsh_hotkeys_extras variable without replacing the existing hotkeys:

zsh_hotkeys_extras:
  - { hotkey: '^[^[[D', action: backward-word } # alt+left
  - { hotkey: '^[^[[C', action: forward-word } # alt+right
  - { hotkey: '^[,', action: copy-earlier-word } # ctrl+,

Aliases

You can define command aliases easily:

zsh_aliases:
  - { alias: 'dfh', action: 'df -h | grep -v docker' }
# without replacing default aliases
- zsh_aliases_extra:
  - { alias: 'dfh', action: 'df -h | grep -v docker', bundle: }

Common Hotkeys from Plugins:

• → - accept an autosuggestion
• Ctrl+Z - send the current application to the background
• Ctrl+G - jump to a bookmarked directory
• Ctrl+R - view command history
• Ctrl+@ - display all fzf widgets

Configure Bundles

You can view default bundles in defaults/main.yml. If you want to keep these but add your bundles, use the zsh_antigen_bundles_extras variable. If you want to remove some default bundles, use zsh_antigen_bundles.

Valid formats include:

- docker # an Oh-My-Zsh plugin
- zsh-users/zsh-autosuggestions # a GitHub plugin
- zsh-users/[email protected] # a specific version
- ~/projects/zsh/my-plugin --no-local-clone # a local plugin

Conditions for Bundles

You can use command and when conditions to control bundle loading:

1. Command Conditions:

- { name: docker, command: docker }
- name: docker-compose
  command: docker-compose

Bundles will load only if their commands exist on the system.

2. When Conditions:

- name: zsh-users/zsh-syntax-highlighting
  when: "{{ zsh_version is version_compare('4.3.17', '>=') }}"

This will load only if the Zsh version is compatible.

Custom Code

You can add any custom scripts in the variables zsh_custom_before and zsh_custom_after:

• zsh_custom_before executes before loading Antigen.
• zsh_custom_after executes before loading the local .zshrc.local.

Upgrading

Version 3.0 of viasite-ansible.zsh introduces Antigen v2.0, which is not backward compatible with version 1.x. If you have issues after the upgrade, run antigen reset.

Downgrade to v1

If you experience problems, you can revert to Antigen v1, though version 2 is significantly faster.

For Zsh 4.x Users

If you are using an older Zsh version (4.x), add this line in your playbook to downgrade to Antigen v1:

zsh_antigen_version: v1.4.1

Known Issues

Error with su username

If you encounter errors when using su username, you can read about it in the Antigen GitHub issue. The recommended approach is to use su - username instead.

Alternatively, use the built-in alias suser for switching users smoothly.

If you prefer to fix it, add this line to ~/.zshrc.local:

alias su='su -'

But be cautious, as this may break existing scripts using the su command.