Puckadots v5.0

Consistent, powerful terminal environment across hosts.

Puckadots is a modular dotfiles framework designed for multi-distro Linux environments (Debian, Fedora, Arch, Alpine, Synology). It separates public configuration (tools, aliases, functions) from private data (SSH keys, secrets, host-specific configs) using a "Companion Repo" architecture.

🚀 Quick Start

Prerequisite: You must have your dotfiles.env file hosted securely.

Deploy to a new host with one command:

mkdir -p ~/.config/dotfiles && wget -O ~/.config/dotfiles/dotfiles.env https://your-server.com/dotfiles.env && wget -qO - https://raw.githubusercontent.com/puckawayjeff/dotfiles/main/join.sh | bash

This will:

1. Verify dotfiles.env exists.
2. Install git (if missing).
3. Download and decrypt your SSH keys.
4. Clone your private sshsync repo and this public repo.
5. Install tools and symlink configs.

---

🔒 Private Setup Guide (Required)

Puckadots requires a private companion repository (sshsync) to function.

1. Create Private Repository

Create a Private GitHub repository named sshsync with an ssh.conf file inside it (this becomes your ~/.ssh/config).

2. Package SSH Keys

sshpack "your-strong-password"

3. Host the Archive

Upload ssh-keys.tar.gz.enc to a secure web server downloadable via wget.

4. Create dotfiles.env

Never commit this to a public repo.

SSHSYNC_REPO_URL="git@github.com:yourusername/sshsync.git"
SSH_KEYS_ARCHIVE_URL="https://your-server.com/secure/ssh-keys.tar.gz.enc"
SSH_KEYS_ARCHIVE_PASSWORD="your-strong-password"
GIT_USER_NAME="Your Name"
GIT_USER_EMAIL="you@example.com"

Place at ~/.config/dotfiles/dotfiles.env on any new machine before running join.sh.

---

📂 Architecture & Structure

dotfiles/
├── config/                    # Public configurations
│   ├── zsh/                   # Modular Zsh configs
│   │   └── zshenv.conf        # SSH non-interactive support
│   ├── fastfetch/             # Fastfetch layouts
│   ├── starship/              # Starship prompt theme
│   ├── ghostty/               # Ghostty terminal config
│   ├── tmux/                  # Tmux config
│   ├── micro/                 # Micro editor settings
│   ├── eza/                   # Eza theme
│   ├── pandoc/                # Pandoc CSS for markdown rendering
│   ├── symlinks.conf          # Core symlink definitions
│   ├── help.dat               # Data source for dothelp
│   └── keys.dat               # Data source for dotkeys
├── docs/                      # Documentation
├── lib/                       # Library functions
│   ├── os.sh                  # OS abstraction layer
│   ├── terminal.sh            # Tool installers
│   ├── utils.sh               # Colors, icons, logging helpers
│   ├── update-system.sh       # System update script
│   └── motd.sh                # Login message
├── setup/                     # Optional tool installers
├── join.sh                    # Bootstrap script
└── sync.sh                    # Configuration applicator

Symlink Logic:

• Public: Mapped via dotfiles/config/symlinks.conf.
• Private: Mapped via sshsync/symlinks.conf.
• add-dotfile automatically adds to the Private repo.

---

🔧 Automatically Installed Tools

These tools are installed automatically by sync.sh and lib/terminal.sh on every host:

Core Utilities (via system package manager)

Package	Purpose
curl, wget	HTTP clients
git	Version control
sudo	Privilege escalation
unzip	Archive extraction
rsync	File synchronization
tree	Directory visualization
bat	Syntax-highlighted cat
p7zip	7-Zip archive support
rename	Bulk file renaming

Terminal Tools (installed with fallbacks)

Tool	Purpose	Install Method
Zsh	Default shell	Package manager
FZF	Fuzzy finder	Package manager / source
Zoxide	Smart directory jumping	Package manager / curl
fd	Fast file finder	Package manager
direnv	Per-directory env vars	Package manager / curl
ripgrep	Fast content search	Package manager / release
Eza	Modern ls replacement	GPG repo (apt) / release
Fastfetch	System info display	Package manager / source build
Starship	Cross-shell prompt	Install script
FiraCode Nerd Font	Icon-capable font	GitHub release
Noto Color Emoji	Emoji rendering	Package manager
Tmux	Terminal multiplexer	Package manager
Micro	Terminal text editor	Install script / package manager

Optional Tools (via dotsetup)

Tool	Command	Purpose
Foot	dotsetup foot	Wayland terminal + cage compositor
Glow	dotsetup glow	Terminal markdown renderer
NVM	dotsetup nvm	Node.js version manager
Syncthing	dotsetup syncthing	Decentralized file sync
Passwordless Sudo	sudo dotsetup passwordless-sudo	Toggle sudo password requirement

Zsh Plugins (via Zinit)

zsh-completions, zsh-autosuggestions, history-search-multi-word, fzf-tab, fast-syntax-highlighting, git (OMZ), docker (OMZ), extract (OMZ), command-not-found (OMZ), colored-man-pages (OMZ), copypath (OMZ), copyfile (OMZ), git-open, zsh-help, printdocker, zsh-activate-py-environment, zsh-you-should-use

---

🛠️ Commands & Functions

Dotfiles Management

Command	Description
dotpull	Pull latest changes & reload shell
dotpush <msg>	Commit & push dotfiles changes
sshpush <msg>	Push SSH config changes
sshpull	Pull SSH config changes
sshpack [pass]	Package SSH keys (encrypted)
add-dotfile <path>	Add file to private repo & symlink
dotversion	Show version & git info
maintain	Full update sequence
dotsetup [tool]	Run/list setup scripts

System Utilities

Command	Description
updatep	System update in tmux (apt/dnf/pacman)
paths	Check PATH entry validity
mkd <dir>	Create directory & cd into it
dotpack <dir> [fmt]	Create archive (tar.gz/zip/7z)

Docker Compose Helpers

Command	Description
dclist	List available docker stacks in /opt/stacks
dcbounce [stack]	Docker compose down & up -d
dcrestart [stack]	Docker compose restart

Navigation & Search

Command	Description
cd <dir>	Smart navigation with zoxide fallback
j <partial>	Jump to directory (zoxide)
fcd [start]	Fuzzy directory change with tree preview
fne [query]	Find text in files & open in editor
y	Yazi file manager (cd on exit)
ll, la, lt	Enhanced ls with eza
ff	Run fastfetch

Markdown Tools

Command	Description
mdv <file>	Render markdown in browser
mdh <file>	Convert markdown to HTML file

Help & Reference

Command	Description
dothelp	Show all commands & functions
dotkeys	Show keyboard shortcuts

---

⌨️ Aliases

Standard

Alias	Expands To
grep	grep --color=auto
bat	batcat --color=auto

ls/eza (conditional — falls back to plain ls if eza not installed)

Alias	With Eza	Without Eza
ls	eza --color=auto --group-directories-first	ls --color=auto
ll	eza --icons -lag --git	ls -alh
la	eza --icons -a	ls -A
l	eza --icons -1	ls -CF
lt	eza --icons --tree --level=2	—

Fastfetch (conditional)

Alias	Expands To
ff	fastfetch
neofetch	fastfetch -c neofetch
screenfetch	fastfetch -c screenfetch

Python

Alias	Expands To
link-pyenv	link_py_environment
unlink-pyenv	unlink_py_environment

---

🏠 Host-Specific Configuration

Puckadots supports per-host customization via ~/.zshrc.local. This file is:

• Sourced last in .zshrc (after all shared config)
• Not tracked by git — unique to each machine
• The right place for: host-specific aliases, PATH additions, tool configs, device-specific functions

Example: ~/.zshrc.local on a workstation with ADB/scrcpy

# Android phone mirroring (ADB over Tailscale)
if command -v adb >/dev/null 2>&1; then
    alias phone-connect='adb connect puckapixel-pro:5555'
    alias phone-disconnect='adb disconnect puckapixel-pro:5555'
fi

if command -v scrcpy >/dev/null 2>&1; then
    mirror-phone() {
        adb connect puckapixel-pro:5555 2>/dev/null
        scrcpy -s puckapixel-pro:5555 --window-title "Pixel Pro" "$@"
    }
    alias mirror-phone-off='mirror-phone --turn-screen-off'
fi

---

📜 License

CC Attribution-NonCommercial 4.0 International