Installation

This guide covers the installation process for both macOS and Debian-based systems.

Prerequisites

macOS

• macOS 10.15 (Catalina) or later
• Command Line Tools for Xcode (will be installed automatically)
• Internet connection

Debian/Ubuntu

• Debian 11+ or Ubuntu 20.04+
• sudo privileges
• Internet connection

Installation Methods

Quick Install (Recommended)

The quickest way to get started is using the one-line installer:

macOS:

curl -fsSL https://raw.githubusercontent.com/this-is-tobi/dotfiles/main/setup/setup-osx.sh | bash

Debian/Ubuntu:

curl -fsSL https://raw.githubusercontent.com/this-is-tobi/dotfiles/main/setup/setup-debian.sh | bash

Manual Installation

If you prefer to review the scripts before running them:

1. Clone the repository:

git clone https://github.com/this-is-tobi/dotfiles.git
cd dotfiles

2. Run the setup script:

For macOS:

./setup/setup-osx.sh

For Debian/Ubuntu:

./setup/setup-debian.sh

Installation Options

Profiles

Install additional profiles based on your needs using the -p flag:

# Single profile
./setup/setup-osx.sh -p devops

# Multiple profiles (comma-separated)
./setup/setup-osx.sh -p 'devops,secops,js'

# All profiles
./setup/setup-osx.sh -p 'base,ai,devops,go,js,secops'

Available profiles:

• base - Base packages and utilities
• ai - AI and machine learning tools
• devops - DevOps tools (Docker, Kubernetes, Terraform, etc.)
• go - Go development environment
• js - JavaScript/Node.js development environment
• secops - Security tools (scanners, secret management, etc.)
• extras - Extra personal packages (macOS only)

An unknown profile name (e.g. a typo) is rejected immediately with an error listing the valid profiles, rather than being silently ignored.

Lite Mode

For minimal installations with only essential tools, use the -l flag:

./setup/setup-osx.sh -l
./setup/setup-osx.sh -l -p devops  # Lite mode with devops profile

Lite mode installs only packages marked with an "x" in the "Lite mode" column of the package tables.

Dry Run

To preview which profiles and options would be applied without installing anything, use the -n flag:

./setup/setup-osx.sh -n -p 'devops,secops,js'
./setup/setup-debian.sh -n -p 'devops,secops,js'

This prints the resolved settings and exits before any package installation, dotfile copying, or interactive prompts.

Help

Display all available options:

./setup/setup-osx.sh -h
./setup/setup-debian.sh -h

Non-Interactive Mode

The setup scripts are designed to run non-interactively by default, making them safe for automation and CI/CD pipelines.

Teleport Version (DevOps Profile)

Teleport is a Debian/Ubuntu-only, full-mode-only install (it's part of the misc category within the DevOps profile, installed by install_additional_setup, which -l/lite mode skips entirely). It defaults to v18 if not specified:

# Uses default v18
./setup/setup-debian.sh -p devops

# Override with specific version
TELEPORT_VERSION=v17 ./setup/setup-debian.sh -p devops

-l (lite mode) or DEVOPS_CATEGORIES set to anything excluding misc (e.g. DEVOPS_CATEGORIES=k8s) will skip Teleport entirely — in either case, TELEPORT_VERSION has no effect since the install step never runs.

Use Cases

Non-interactive mode is particularly useful for:

• CI/CD pipelines - Automated environment setup
• Docker builds - Installing dotfiles in containers
• Configuration management - Ansible, Terraform provisioning
• Scripted deployments - Batch server setup

Example: Docker

FROM debian:bookworm

# Optional: override default Teleport version (only takes effect in full
# mode, i.e. without -l — see the note above)
ENV TELEPORT_VERSION=v17

RUN apt update && apt install -y curl git sudo && \
    git clone https://github.com/this-is-tobi/dotfiles.git /root/dotfiles && \
    cd /root/dotfiles && \
    ./setup/setup-debian.sh -p devops

For a leaner image that only needs Kubernetes tooling (skipping Teleport, Terraform, Ansible, cloud CLIs, etc. entirely), combine -l with DEVOPS_CATEGORIES instead — see DevOps Profile:

RUN ... && DEVOPS_CATEGORIES=k8s ./setup/setup-debian.sh -l -p devops

What Gets Installed

Core Components

Both platforms install:

• oh-my-zsh - Zsh configuration framework with plugins
• CLI tools - Essential command-line utilities (curl, wget, jq, etc.)
• Git configuration - Custom .gitconfig template
• Shell functions - Custom utility functions
• Completions - Auto-completion for various tools
• GitHub Copilot instructions - AI-assisted development guidelines

Platform-Specific

macOS:

• Homebrew package manager
• Homebrew Cask applications
• macOS-specific configurations

Debian/Ubuntu:

• apt package management for system packages
• mise for portable CLI binaries
• Debian-specific system configurations

Both platforms:

• mise for language runtimes

Post-Installation

1. Restart Your Shell

After installation, restart your shell or source the configuration:

exec zsh
# or
source ~/.zshrc

2. Configure Environment Variables

Edit the environment file to add your API keys and custom settings:

vim ~/.config/dotfiles/env.sh

Example configuration:

# Context7 API key for documentation access
export CONTEXT7_API_KEY="your_api_key_here"

# Add other custom environment variables
# export MY_VAR="value"

3. Review Installed Tools

List all custom functions:

lsfn

Check installed packages:

# macOS
brew list

# Debian
apt list --installed

4. Customize Dotfiles

The dotfiles are installed as templates. Customize them to your needs:

# Edit zsh configuration
vim ~/.zshrc

# Edit git configuration
vim ~/.gitconfig

# Edit VS Code settings
vim ~/.config/Code/User/settings.json

Troubleshooting

Permission Denied

If you encounter permission errors:

chmod +x setup/setup-*.sh

Homebrew Issues (macOS)

If Homebrew installation fails:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

mise Issues

If a tool fails to install, check mise itself first:

mise doctor

Tool downloads resolve versions through the GitHub API, which rate-limits unauthenticated requests. On a shared IP or in CI this surfaces as HTTP 403 and is the most common cause of a failed run — export a token to raise the limit:

export GITHUB_TOKEN=<your-token>

oh-my-zsh Already Installed

If oh-my-zsh is already installed, the script will skip it. To reinstall:

rm -rf ~/.oh-my-zsh
# Run setup script again

Uninstallation

To remove installed configurations:

# Backup first!
./backup/backup-osx.sh  # or backup-debian.sh

# Remove dotfiles
rm -rf ~/.zshrc ~/.gitconfig ~/.config/dotfiles

# Remove oh-my-zsh
rm -rf ~/.oh-my-zsh