Work Environment Deployment¶

This guide covers deploying dotfiles to professional work servers, corporate infrastructure, and shared environments where security, compliance, and separation of concerns are critical.

Deployment Modes for Work¶

Recommended: Dotfiles Only Mode¶

The safest approach for professional environments applies only configuration files without installing packages or tools.

What Gets Applied¶

✅ Deployed: - .zshrc, .bashrc - Shell configuration - .gitconfig - Git settings (⚠️ see Git Identity below) - .aliases - Command shortcuts - .tmux.conf - Tmux configuration - .config/nvim/ - Neovim configuration - Other dotfiles (dot_* files)

❌ Skipped: - System packages (no apt/pacman installs) - Mise tool installation - Encrypted secrets (encrypted_dot_secrets.age) - Setup scripts (run_once_*)

Deployment Steps¶

# 1. Install chezmoi to user directory (no sudo required)
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

# 2. Apply dotfiles only (skip system setup and secrets)
chezmoi init --apply jerdaw/dotfiles \
  --exclude "run_once_*" \
  --exclude encrypted

Alternative: Manual Clone First¶

For maximum control and audit trail:

# 1. Clone to your user directory
git clone https://github.com/jerdaw/dotfiles.git ~/.dotfiles-source

# 2. Install chezmoi
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

# 3. Initialize from local source (not GitHub URL)
chezmoi init --source ~/.dotfiles-source

# 4. Review what will be applied
chezmoi diff

# 5. Apply dotfiles
chezmoi apply --exclude "run_once_*" --exclude encrypted

Critical Work Environment Considerations¶

1. Git Identity Override¶

The dotfiles repo prompts for your name/email during setup. Work commits must use your work email, not personal.

After applying dotfiles, override globally:

# Set work identity (overrides dotfiles config)
git config --global user.email "you@company.com"
git config --global user.name "Your Name"

Or create a work-specific config:

# ~/.gitconfig-work
[user]
    email = you@company.com
    name = Your Name
[include]
    path = ~/.gitconfig-dotfiles

# Then in ~/.gitconfig
[include]
    path = ~/.gitconfig-work

Verify:

git config --global user.email
# Should output: you@company.com

2. Secrets Isolation¶

Your .zshrc sources ~/.secrets which may contain personal API keys (OpenAI, Anthropic, GitHub personal tokens).

Solution: Create Empty Secrets File

# Prevent sourcing errors, but no personal secrets
echo "# Work server - no personal secrets" > ~/.secrets
chmod 600 ~/.secrets

Or exclude entirely:

# During chezmoi apply
chezmoi apply --exclude encrypted --exclude dot_secrets

3. Personal References in Configs¶

Review these files before deploying to work:

4. Corporate Network Restrictions¶

Work environments may restrict:

• Outbound HTTPS to github.com, mise.run, get.chezmoi.io
• Proxy authentication required
• Package mirrors (internal Artifactory/Nexus)

If network restricted:

1. Download chezmoi binary manually:

   # From another machine or through proxy
   curl -Lo chezmoi.tar.gz https://github.com/twpayne/chezmoi/releases/latest/download/chezmoi_linux_amd64.tar.gz
   tar xzf chezmoi.tar.gz
   mv chezmoi ~/.local/bin/
   

2. Clone dotfiles via corporate proxy:

   git config --global http.proxy http://proxy.company.com:8080
   git clone https://github.com/jerdaw/dotfiles.git ~/.dotfiles-source
   

Compliance & Security Checklist¶

Before deploying to work infrastructure:

• Policy Review: IT/Security approved personal dotfiles deployment
• Code Audit: Reviewed all scripts and configs for policy violations
• Git Identity: Configured work email for commits
• Secrets Excluded: No personal API keys in work environment
• Audit Trail: Acceptable to have personal GitHub username in logs
• License Check: All tools/scripts use work-appropriate licenses
• Network Access: Can reach required URLs (or downloaded manually)
• Sudo Requirements: Deployment method doesn't require root (if restricted)

Work vs Personal Separation Strategies¶

Strategy 1: Hostname Detection¶

Automatically adjust configs based on hostname:

# In .chezmoi.toml.tmpl
{{ $is_work := false }}
{{ if contains "corp" .chezmoi.hostname }}
{{   $is_work = true }}
{{ end }}
{{ if contains "work-" .chezmoi.hostname }}
{{   $is_work = true }}
{{ end }}
    is_work = {{ $is_work }}

Then in templates:

# dot_gitconfig.tmpl
[user]
{{ if .is_work }}
    email = you@company.com
{{ else }}
    email = you@personal.com
{{ end }}
    name = Your Name

Strategy 2: Separate Branch¶

Create a sanitized branch for work environments:

# Create work branch
git checkout -b work

# Remove personal configs
rm encrypted_dot_secrets.age
echo "# Work-safe aliases only" > dot_aliases

# Sanitize git config
# Edit dot_gitconfig.tmpl to hardcode work email

git add -A
git commit -m "Sanitize for work environments"
git push origin work

# On work servers
chezmoi init --apply jerdaw/dotfiles --branch work

Strategy 3: Environment Variables¶

Use environment variable flags:

# On work server, before applying
export DOTFILES_WORK_MODE=1

# In templates, check this variable
{{ if env "DOTFILES_WORK_MODE" }}
  # Work-specific config
{{ else }}
  # Personal config
{{ end }}

Server Mode (With Root Access)¶

If you control the server (personal VPS, dev VM) and have sudo:

git clone https://github.com/jerdaw/dotfiles.git ~/repos/dotfiles
cd ~/repos/dotfiles

# Install server-safe tools (excludes desktop/GUI tools)
./scripts/bootstrap --server --yes

What Server Mode Excludes¶

These desktop-only tools are not installed in server mode:

Installed in Server Mode¶

✅ Core utilities: bat, eza, ripgrep, fd, fzf, zoxide, jq ✅ Development: Node, Python, Go (via mise) ✅ Git tools: delta, tig (git-extras available on Debian/Ubuntu baseline) ✅ Editor: Neovim with full plugin suite ✅ Shell: Zsh with optimized plugins

See mise-server.toml for the complete list.

Docker/Container Deployment¶

For ephemeral environments or CI/CD:

FROM ubuntu:24.04

# Install minimal dependencies
RUN apt-get update && apt-get install -y \
    curl git zsh ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Install chezmoi
RUN sh -c "$(curl -fsLS get.chezmoi.io)" -- -b /usr/local/bin

# Apply dotfiles (no packages, no secrets)
RUN chezmoi init --apply jerdaw/dotfiles \
    --exclude "run_once_*" \
    --exclude encrypted

# Set shell
CMD ["zsh"]

See examples/Dockerfile for multi-stage builds and optimized examples.

Common Pitfalls¶

❌ Pitfall 1: Personal Aliases Leak to Work¶

Problem: dot_aliases contains personal shortcuts like:

alias work-vpn="sudo openvpn ~/personal/client.ovpn"
alias backup-photos="rsync -av ~/Photos user@nas:/backups"

Fix: Review and sanitize aliases before work deployment, or use hostname detection:

# In dot_aliases
{{ if not .is_work }}
alias backup-photos="rsync -av ~/Photos user@nas:/backups"
{{ end }}

❌ Pitfall 2: Personal GitHub Token in Work Shell¶

Problem: ~/.secrets contains GITHUB_TOKEN=ghp_personal... which gets loaded in work shells.

Fix: Use work-specific secrets file:

# ~/.secrets (work server)
# No personal tokens here!
export GITHUB_TOKEN="ghp_work_token"  # Work PAT only

❌ Pitfall 3: Git Commits Use Personal Email¶

Problem: After deploying dotfiles, git config user.email shows personal email. Work commits attributed to you personally.

Fix: Always override after deployment:

git config --global user.email "you@company.com"
# Verify
git log --author="$(git config user.name)" --pretty=format:"%ae" | head -1

❌ Pitfall 4: Sudo Required but Not Available¶

Problem: Attempting full/server mode on shared server where you lack sudo.

Fix: Use "Dotfiles Only" mode (no sudo required):

chezmoi init --apply jerdaw/dotfiles \
  --exclude "run_once_*" \
  --exclude encrypted

Verification¶

After deployment, verify the setup:

# 1. Check key files exist
[ -f ~/.zshrc ] && echo "✅ zshrc" || echo "❌ zshrc MISSING"
[ -f ~/.gitconfig ] && echo "✅ gitconfig" || echo "❌ gitconfig MISSING"
[ -f ~/.aliases ] && echo "✅ aliases" || echo "❌ aliases MISSING"

# 2. Verify git identity (CRITICAL for work)
git config --global user.email
# Expected: you@company.com

# 3. Check for personal secrets (should be empty or excluded)
if [ -f ~/.secrets ]; then
    if grep -q "OPENAI_API_KEY\|ANTHROPIC_API_KEY" ~/.secrets 2>/dev/null; then
        echo "⚠️  WARNING: Personal API keys found in work environment!"
    else
        echo "✅ Secrets file exists but contains no personal keys"
    fi
else
    echo "✅ No secrets file (good for work)"
fi

# 4. Test shell loads without errors
zsh -c "echo '✅ Shell loads successfully'"

Troubleshooting¶

Template Errors During Apply¶

Error: template: ...: undefined variable

Fix: Chezmoi needs variables set during init. Use --promptDefaults for non-interactive:

chezmoi init --apply jerdaw/dotfiles \
  --exclude "run_once_*" \
  --exclude encrypted \
  --promptDefaults

Permission Denied on Shared Servers¶

Error: cannot write to /usr/local/bin

Fix: Install chezmoi to user directory:

sh -c "$(curl -fsLS get.chezmoi.io)" -- -b "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"

Shell Not Changing to Zsh¶

chsh: PAM: Authentication failure

Fix: Shared servers often restrict chsh. Options:

1. SSH config (client-side):

   # ~/.ssh/config on your laptop
   Host work-server
       RequestTTY yes
       RemoteCommand zsh -l
   

2. Exec from .bashrc (server-side):

   echo 'exec zsh' >> ~/.bashrc
   

3. Skip shell change:

   DOTFILES_SKIP_CHSH=1 mise run install
   

Corporate Proxy Blocking Downloads¶

Fix: Configure git/curl to use proxy:

# Git proxy
git config --global http.proxy http://proxy.company.com:8080
git config --global https.proxy http://proxy.company.com:8080

# Curl proxy (for chezmoi installer)
export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080

# Then retry
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin

Quick Reference¶

Safest Work Deployment (One-liner)¶

sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin && \
  ~/.local/bin/chezmoi init --apply jerdaw/dotfiles \
    --exclude "run_once_*" \
    --exclude encrypted && \
  git config --global user.email "you@work.com"

Minimal Manual Deployment¶

# 1. Clone
git clone https://github.com/jerdaw/dotfiles.git ~/.dotfiles

# 2. Copy only what you need
cp ~/.dotfiles/dot_zshrc ~/.zshrc
cp ~/.dotfiles/dot_aliases ~/.aliases
cp ~/.dotfiles/dot_gitconfig.tmpl ~/.gitconfig

# 3. Edit to remove personal references
vim ~/.gitconfig  # Set work email
vim ~/.aliases    # Remove personal shortcuts

# 4. Test
zsh

Related Documentation¶

• Server Deployment - Technical deployment modes
• Secrets Management - Handling sensitive data
• Customization - Personalizing configurations
• Troubleshooting - General issues

FAQ¶

Q: Is it safe to use my personal dotfiles on work servers?¶

A: It depends on your company policy and what's in your dotfiles. Key considerations:

• Policy: Some companies prohibit external code on corporate infrastructure
• Secrets: Ensure no personal API keys leak to work environment
• Attribution: Work commits must use work email, not personal
• Audit: Your personal GitHub username will appear in deployment logs

Recommendation: Use "Dotfiles Only" mode and override git identity.

Q: Can I use the same dotfiles repo for both work and personal?¶

A: Yes, using one of these strategies:

1. Hostname detection - Automatically switch config based on server name
2. Separate branches - main for personal, work for sanitized configs
3. Environment variables - Set DOTFILES_WORK_MODE=1 before deployment

See Work vs Personal Separation.

Q: What if my company blocks GitHub?¶

A: Options:

1. Internal mirror: Ask IT to mirror your dotfiles repo internally
2. Manual copy: Clone from home, transfer via SCP/rsync
3. USB transfer: Clone to USB drive, copy to work server

Q: Do I need sudo to deploy dotfiles?¶

A: No, "Dotfiles Only" mode requires no root access. Only tool installation modes (full/server) need sudo.

Q: Can I deploy to Windows work machines?¶

A: Not directly. Options:

1. WSL2: Deploy to Windows Subsystem for Linux (if IT allows)
2. PowerShell profile: Manually adapt configs to PowerShell
3. Git Bash: Limited dotfiles support via Git Bash

See Windows & WSL Guide.

Q: How do I update dotfiles on work servers?¶

# Pull latest changes
chezmoi update

# Or manually
cd ~/.local/share/chezmoi
git pull
chezmoi apply

Q: What if IT requires code review before deployment?¶

1. Fork to a work-controlled GitHub org
2. Submit PR with sanitized configs
3. After approval, deploy from work fork:

   chezmoi init --apply work-org/dotfiles