/dotfiles-m1

Computer setup and settings. Apple Silicon ready.

Primary LanguageShellMIT LicenseMIT

Dotfiles

Brendon Smith (br3ndonland)

Table of Contents

Installation

Dotfiles are application configuration and settings files. They frequently begin with a dot, hence the name. This dotfiles repository is meant to be installed by bootstrap.sh.

bootstrap.sh is a shell script to automate setup of a new macOS or Linux development machine. It is idempotent, meaning it can be run repeatedly on the same system. To set up a new machine, simply open a terminal and run the following command:

STRAP_GIT_EMAIL="you@example.com" STRAP_GIT_NAME="Your Name" STRAP_GITHUB_USER="username" \
  /usr/bin/env bash -c "$(curl -fsSL https://raw.githubusercontent.com/br3ndonland/dotfiles/HEAD/bootstrap.sh)"

The following environment variables can be used to configure bootstrap.sh, and should be either set before with export, or inline within the command to run the script:

  • STRAP_GIT_EMAIL: email address to use for Git configuration. Will error and exit if not set.
  • STRAP_GIT_NAME: name to use for Git configuration. Will error and exit if not set.
  • STRAP_GITHUB_USER: username on GitHub or other remote from which dotfiles repo will be cloned. Defaults to my GitHub username, so you should set this if you're not me.
  • STRAP_DOTFILES_URL: URL from which the dotfiles repo will be cloned. Defaults to https://github.com/$STRAP_GITHUB_USER/dotfiles, but any Git-compatible URL can be used, so long as it is accessible at the time the script runs.
  • STRAP_DOTFILES_BRANCH: Git branch to check out after cloning dotfiles repo. Defaults to main.

bootstrap.sh will set up macOS and Homebrew, run scripts in the scripts/ directory, and install Homebrew packages and casks from the Brewfile.

A Brewfile is a list of Homebrew packages and casks (applications) that can be installed in a batch by Homebrew Bundle. The Brewfile can even be used to install Mac App Store apps with the mas CLI. Note that you must sign in to the App Store ahead of time for mas to work.

Why?

  • Make developer environments automated and disposable. Disposability is an important concept in infrastructure-as-code DevOps, serverless computing, CI/CD, and more recently, in-browser development environments. Why aren't developers applying automation and disposability to their own computers? With an automated disposable developer environment, setup of a new machine is fast and easy. This approach is also liberating - I can purchase a new computer (or wipe an existing one), run bootstrap.sh, and be up and running again in no time.
  • Know when and why settings change. I not only know what tools and settings I'm using, but when and why I chose the tools and settings. This has been particularly important for VSCode, because settings change (and break) frequently, and it helps to record troubleshooting info in the Git log.
  • Learn new skills. I learn skills, like shell scripting, that are useful and don't go out of date quickly. I wouldn't know shell as well if I didn't work on my developer environment. I learn these skills by tinkering a little bit at a time, in an unstructured way. It's time I might not otherwise be writing code.

Hardware

macOS

  • macOS setup is automated with macos.sh.

  • Karabiner Elements is used for keymapping.

    • Settings are stored in .config/karabiner/karabiner.json. Note that Karabiner will auto-format the JSON with four spaces. To avoid changing the formatting with the Prettier autoformatter, I added karabiner.json to .prettierignore.

    • Simple modifications:

      From key To key
      caps_lock escape
      escape caps_lock

    • Complex modifications:

      • Launch Terminal with Cmd+Escape
      • See karabiner.json for more.

    • Devices

      • Disable built-in keyboard when external keyboard is connected

Homebrew package management

  • Homebrew is a package manager that includes Homebrew-Cask to manage other macOS applications.

  • See the Homebrew docs for further info.

  • My list of Homebrew packages and casks is available in my homebrew-brewfile repo, and engineered for use with strap.

  • The Brewfile works with Homebrew Bundle to manage all Homebrew packages and casks together.

  • Key Brew Bundle commands:

    # Install everything in the Brewfile
brew bundle install --global
# Check for programs listed in Brewfile
brew bundle check --global
# Remove any Homebrew packages and casks not in Brewfile
brew bundle cleanup --force --global

Shell

Text editors

VSCode desktop

I write code with VSCodium, an alternate build of Microsoft Visual Studio Code (VSCode) that is free of proprietary features and telemetry. To work on servers via SSH, I use Pony SSH.

I previously configured VSCode and VSCodium using the Settings Sync extension. I now have my settings, keybindings, and extensions stored here in my dotfiles repo. Extensions can be installed by running vscode-extensions.sh along with the name of the editor, like vscode-extensions.sh codium. The shell script was quite easy to write. I based it on npm-globals.sh, and used the VSCode extension CLI.

VSCode browser

codespaces

I have tried GitHub's cloud-hosted VSCode, called Codespaces. So far, I don't like it because:

  • Keybindings conflict with browser keybindings. The command palette may not be able to be opened with the usual keybindings, because Cmd+shift+p is already in use by the browser. This was partially addressed by the VSCode extension, which allows remote development from outside the browser.
  • Lag. There's lag between when a character is typed and when it appears. This can be very bothersome.
  • Files. It's unclear if or how persistent file storage is available. Local filesystem access is limited.
  • GPG commit signing has some limitations. GitHub offers commit signing with GPG, but private keys must be in GitHub's custody.
  • Customization is complicated.
    • Codespaces doesn't automatically clone or run these dotfiles. They claim that codespaces will automatically clone your dotfiles and run bootstrap.sh, but the repo is not cloned to ~/.dotfiles, and bootstrap.sh is not running, even after enabling the "Automatically install dotfiles" setting in user preferences.
    • Codespaces can't read VSCode settings from dotfiles. The docs explain, "Currently, Codespaces does not support personalizing the User settings for the Visual Studio Code editor with your dotfiles repository." The separate Settings Sync service is required to sync settings.
    • Extensions have to be managed separately from VSCode desktop. There is a "github.codespaces.defaultExtensions" setting that requires its own list of extensions, and it's unclear if Codespaces can install extensions from VSIX (like Dracula Pro).
    • Codespaces may not be able to install and use custom fonts (like Dank Mono). Font capabilities may be limited by the browser.
    • For further customization, Codespaces supports "dev containers," which are created with special Dockerfiles in each project. This adds further complication and maintenance overhead.
  • Codespaces pricing requires enterprises to set up separate spending limits, and is not specified for public repos on free plans. Do you want to pay for your text editor by the minute?

code-server

  • code-server is an open-source alternative to codespaces.

  • I set up code-server on a Linux cloud server. I prefer to use DigitalOcean, following their recommended initial setup guide for "droplets" (VMs):

    • Set up SSH agent forwarding on local machine to avoid having to deposit SSH private keys on droplet
    • Add SSH public key when creating droplet
    • Add a user data script like linux-userdata.sh

  • Installation and setup on the server:

    curl -fsSL https://code-server.dev/install.sh | sh
sudo systemctl enable --now code-server@$USER

  • Server configuration file: note that user-data-dir must be an absolute path if running with the systemctl background service.

    bind-addr: 127.0.0.1:8080
auth: none
password: false
cert: false
user-data-dir: /home/brendon/.dotfiles/vscode

  • Local machine

    • Forward port from server by running ssh -N -L 8080:127.0.0.1:8080 code-server on the local machine.
    • Open http://localhost:8080 in a browser and you should see VSCode!
    • Multiple workspaces can be opened by passing the ?workspace= query parameter in the URL. Each browser tab can have a workspace open.
    • Proxy ports back to local machine with the /proxy endpoint. For example, to hit an API endpoint running on port 1025 on the server, curl :8080/proxy/1025. As explained in the VSCode docs, if developing on Linux, note that non-root users may not be able to expose ports less than 1024. The port is set to 1025 in the debugger config for this reason.

  • Extensions:

    • code-server has its own extension marketplace that is created by scraping GitHub.
    • You can also install extensions with the CLI: code-server --install-extension.

  • Settings

    • If the shell doesn't look right: Command Palette -> Terminal: Select Default Shell
    • The browser may grab some VSCode keybindings. I prefer to use Safari, because it grabs the least shortcuts.
    • code-server can't be used as a Git editor, as far as I can tell. It can open text files from the command-line, but the --wait switch is not recognized.
    • The clipboard doesn't completely work. See cdr/code-server#1106.
    • The font can't yet be customized directly. See cdr/code-server#1374.
    • You can change the color theme, but you may need to re-select the theme each time you open a browser tab.

Fonts

Dank Mono is my programming font of choice. The rounded characters are eminently readable, the italics are elegant, and the ligatures are intuitive. Recursive Mono, Fira Code, and Ubuntu Mono are decent free alternatives.

Language-specific setup

JavaScript

  • node is a JavaScript runtime used to run JavaScript outside of a web browser.

  • npm is a package manager written in node.js, included when node is installed.

    • It's difficult to keep track of global npm packages. There's no easy way to do it with the usual package.json. As Isaac Schlueter commented in 2012,

      Yeah, we're never going to do this.

    • Instead, packages can be installed with Homebrew, or with npm-globals.sh.
    • npm-check can be used to manage global packages after install, with npm-check -ug. If not using npm-check, a list of global npm packages can be seen after installation with npm list -g --depth=0.

  • I use the Prettier autoformatter and the Prettier VSCode extension to format my web code, including JavaScript and Vue.js. Prettier is an extremely helpful productivity tool, and I highly recommend it. Autoformatters save time and prevent bikeshedding.

  • ESLint notes:

    • Compared with Prettier, ESLint formats less code languages, requires complicated setup, and doesn't work well when installed globally. I previously attempted to use a global ESLint installation with the VSCode ESLint extension, but was getting errors about plugins. As the ESLint docs explain:

      It is also possible to install ESLint globally rather than locally (using npm install eslint --global). However, this is not recommended, and any plugins or shareable configs that you use must be installed locally in either case.

    • The errors persist even after specifying the path to global npm packages:

      // VSCode settings.json
{
  "eslint.nodePath": "/usr/local/lib/node_modules"
}

    • If ESLint and plugins are installed in the project directory, the following settings can be added to the VSCode settings.json, for use with the VSCode ESLint extension and eslint-plugin-vue. I typically don't use ESLint to auto-fix files, because Pretter is preferred.

      // VSCode settings.json
{
  "eslint.autoFixOnSave": false,
  "eslint.enable": true,
  "eslint.validate": ["javascript", "javascriptreact", "vue"]
}

    • I do still retain a global .eslintrc in my dotfiles repo, because it is a useful template for sensible defaults.

  • In the past, I also used JavaScript Standard Style (aka StandardJS). Standard Style has also reportedly been favored by Brendan Eich (creator of JavaScript) and Sir Tim Berners-Lee (creator of the World Wide Web). Prettier provides a similar code style, but with more features, so I use Prettier instead.

Python

  • I format Python code with Black.
    • VSCode provides built-in support for Black. I set VSCode to autoformat on save.
    • Black is still considered a pre-release.
    • If you prefer the less-decisive PEP 8 format, I recommend autopep8 for autoformatting. VSCode also has built-in Python formatting support for autopep8.
  • See my template-python repo for useful tooling and additional sensible defaults.

PGP

  • I use Gnu Privacy Guard (GPG, the free implementation of Pretty Good Privacy (PGP)), Keybase, and ProtonMail to encrypt and share messages, passwords, and other sensitive info.
  • PGP vs SSL: SSL/TLS/HTTPS encrypts data in transit, but the storage provider like Dropbox, Google, or Slack can still read it. Communications which are end-to-end PGP encrypted can only be read by the sender or recipient, never the provider.

GPG

GPG is an implementation of OpenPGP.

Installation

  • Install gnupg:
    • macOS: brew install gnupg
    • Ubuntu Linux: sudo apt-get install gnupg
    • Manually: Download from GnuPG
  • Install pinentry:
    • macOS: brew install pinentry (terminal) or brew install pinentry-mac (app from GPGTools suite that enables use of macOS keychain and GUI apps like VSCode)
    • Ubuntu Linux: apt install pinentry
    • Manually: On macOS, Apple's command-line tools (xcode-select) should have the build prerequisites. Download libgpg-error, libassuan, and pinentry, then build from source and install in order (libgpg-error, then libassuan, then pinentry): 
      cd /path/to/libgpg-error
./configure; make; sudo make install
cd /path/to/libassuan
./configure; make; sudo make install
cd /path/to/pinentry
./configure; make; sudo make install
  • Set the pinentry program:
    • ~/.gnupg/gpg-agent.conf: pinentry-program /opt/homebrew/bin/pinentry
    • The path apparently has to be absolute, so it may vary by system.
    • See the GPG agent options docs for more.
  • Export the GPG_TTY environment variable: export GPG_TTY=$(tty) (can add to shell profile to automatically export). Note that this is not the same thing as export GPG_TTY=$TTY, which may raise cryptic Inappropriate ioctl for device errors.
  • Ensure proper permissions are set on GPG config files: 
    chmod 700 ~/.gnupg
chmod 600 ~/.gnupg/gpg.conf
  • See the GPG configuration docs for more.

GPG and YubiKey

Resources:

To use a GPG key on a YubiKey with a new computer, plug in the YubiKey, check the status, and fetch the public keys.

~
❯ gpg --card-status

~
❯ gpg --card-edit

gpg/card> admin
Admin commands are allowed

gpg/card> url
URL to retrieve public key: https://github.com/<YOUR_GITHUB_USERNAME>.gpg

gpg/card> fetch

gpg/card> quit

Key generation

  • Run gpg --full-generate-key from the command line to generate a key. Respond to the command-line prompts. The maximum key size of 4096 is recommended.
  • View keys with gpg --list-secret-keys.
  • Run gpg --send-keys <keynumber> to share the public key with the GPG database. It takes about 10 minutes for the key to show up in the GPG database.

Key import and export

  • Import a GPG key from a file: gpg --import /path/to/privatekey.asc
  • Export your GPG public key:
    • Copy to clipboard (for pasting into GitHub/GitLab): gpg --armor --export | pbcopy
    • Export to a file: gpg --armor --export > public.gpg

Sending messages

  • Locate another user's key in the global database with gpg --search-keys <email>.
  • Encrypting communications
    • Encrypt a message with echo "Hello, World!" | gpg --encrypt --armor --recipient "<email>". Optionally, save the encrypted message in a .gpg file.
    • If the message was saved in a file, send the file over email, Slack, or any other medium.
    • Decrypt the message with gpg --decrypt.
      • If copying the encrypted text directly, include it in quotes: echo "BIG LONG GPG STRING" | gpg --decrypt.
      • If reading a file, include the filename when decrypting: gpg --decrypt message.gpg.
      • Decrypted output can be autosaved to a new file: gpg --decrypt message.gpg --output file.txt.

Signing Git commits with GPG

  • See Pro Git: Signing your work.
  • Install and configure pinentry as described above.
  • Configure Git to use GPG and your key for commits, using .gitconfig:
    • Set signingkey: git config --global user.signingkey 16digit_PGPkeyid the 16 digit PGP key id is the partial 16 digit number listed on the sec line). 
      [user]
name = your name
email = you@email.com
signingkey = 16digit_PGPkeyid
    • Turn on gpgsign: 
      [commit]
gpgsign = true

General

  • Restart the agent: gpgconf --kill gpg-agent or gpgconf --kill all. See the GPG docs on invoking gpg-agent.
  • Verify GPG signing capabilities: echo "test" | gpg --clearsign
  • Trust GPG keys using the GPG TTY interface:
    • If you see gpg: WARNING: This key is not certified with a trusted signature! when examining signed Git commits with git log --show-signature, you may want to trust the keys.
    • Enter the GPG key editor from the command line with gpg --edit-key <PGPkeyid>.
    • Set trust level for the key by typing trust, hitting enter, and entering a trust level.
    • See the GPG docs for more info.
  • GitHub GPG instructions
  • GitLab GPG instructions
  • If working on a server, you can use ssh agent forwarding to access your SSH and GPG keys without having to copy them.

Keybase

UPDATE: Keybase was acquired by Zoom, and its future is uncertain.

Useful features

Keybase PGP

Background
  • Keybase solves the key identity problem.
    • Even if you have someone's public PGP key, you can't verify it actually came from them unless you exchange it in person.
    • Keybase provides a unified identity for verification of PGP keys. Each device gets its own private key, and they share identity.
    • It was previously challenging to move PGP keys among devices, but now it can be accomplished simply by signing in to Keybase.
  • Following someone is a way of verifying their cryptographic identity, not a way of subscribing to updates from the person like social media. I think calling this "following" is confusing. It's really more like verifying.
  • Keybase uses the NaCl (salt) library for encryption, which turned out to be a great choice. It's been stable and has avoided vulnerabilities. They also used Go to build many of the features.
  • The Keybase database is represented as a merkle tree. See Keybase docs: server security and Wikipedia.
  • Keybase doesn't directly run on blockchain, but they do push the Keybase merkle root to the Bitcoin blockchain for verification.
  • The Software Engineering Daily podcast episode with Max Krohn from 2017-10-24 has more helpful explanation.
Info

  • To see available commands, run keybase help pgp or see the command-line docs.

  • Manage GPG/PGP keys in Keybase from the command line with keybase pgp.

  • List keys with keybase pgp list.

  • Generate a new PGP key with keybase pgp gen.

    • If you already have a key, add the --multi flag, like keybase pgp gen --multi.

    • You will be prompted with several options. I set a password on my key to keep it secure. Storing the private key on the keybase.io servers is a contentious option, because it hypothetically could put the key at risk. However, I agree with this comment: if you don't trust Keybase, don't use Keybase. From what I understand, if you select Push an encrypted copy of your new secret key to the Keybase.io server? [Y/n] Y during keybase pgp gen, it will have the same ultimate effect as keybase pgp push-private. Here are the important options for key management:

      # Generate a PGP key (Keybase will automatically export it to GPG)
keybase pgp gen
# Sync PGP key with Keybase using Keybase servers
keybase pgp push-private 16digit_PGPkeyid
# Export PGP key from Keybase to GPG using Keybase servers
keybase pgp pull-private 16digit_PGPkeyid
# Manual export of public key from Keybase to GitHub
keybase pgp export -q key_id | pbcopy  # then go to GitHub settings and paste
# Manual export of public key from Keybase to GPG
keybase pgp export -q 16digit_PGPkeyid | gpg --import
# Manual export of private key to GPG
keybase pgp export -q 16digit_PGPkeyid --secret | gpg --allow-secret-key-import --import

    • If none of the Keybase methods work, try GPG. On the source computer where the GPG private keys are stored, export to a synced directory:

      mkdir -p /path/to/.keys
gpg -a --export > /path/to/.keys/pubkeys.asc
gpg -a --export-secret-keys > /path/to/.keys/privatekeys.asc
# import from the synced directory on the destination computer:
gpg --import /path/to/.keys/privatekeys.asc

Keybase chat

Keybase chat looks and feels like Slack, but has several advantages.

Keybase crypto

Keybase provides useful cryptographic tools for PGP encrypting and decrypting files. One common use case is storing credentials in encrypted files. Here's how to improve security when configuring Docker for use with GitHub Packages, by storing the Personal Access Token (PAT) in an encrypted file:

# create PAT on GitHub and copy to clipboard

# transfer PAT from clipboard to encrypted file
pbpaste | keybase encrypt -o pat-ghcr.asc $YOUR_USERNAME

# decrypt and log in
keybase decrypt -i pat-ghcr.asc | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

# can also use keybase pgp encrypt and keybase pgp decrypt, but must export PGP key

Keybase Git

  • Keybase allows users and teams to create and store end-to-end encrypted Git repositories. See the Keybase Git docs and Keybase Git blog post.

  • Treat Keybase Git repos as remotes (like GitHub repos). They can be cloned, pushed, and pulled, as you would do for GitHub repos.

    git remote add keybase keybase://$PUBLIC_OR_PRIVATE/$USERNAME/$REPONAME
git push keybase

  • As of Keybase 5.1.0, Git LFS is also enabled.

  • Keybase can't yet be used to sign Git commits, as described above. The best method, as described here, is to export your PGP key from Keybase to GPG, and then sign Git commits with GPG. Eventually, I would like to set Keybase as the signing program in my ~/.gitconfig and skip the export to GPG.

    • .gitconfig for GPG

      ...
[commit]
gpgsign = true
[gpg]
program = gpg
...

    • .gitconfig for Keybase?

      ...
[commit]
pgpsign = true
[pgp]
program = keybase
...

  • There has been some debate about the need to sign Git commits at all. Linus Torvalds has recommended the use of git tag -s to sign with tags instead. The Keybase developers sign releases with tags, but don't always sign commits to the Keybase source code. However, in order to sign tags, you still need to set up commit signing, so why not just sign commits also? Whether you sign all commits or just tags, Keybase should improve this feature.

ProtonMail

I use ProtonMail for PGP-encrypted email.

SSH

Key generation

To generate an SSH key:

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_"$(id -un)"

If you have a FIDO2 security key that supports discoverable credentials (formerly known as resident keys), such as a YubiKey, you can generate an SSH key that is stored directly on the FIDO2 hardware device.

You'll need libfido2 and OpenSSH version 8.2 or later.

brew install libfido2 openssh

Next, generate a key with the -O resident option. You can additionally set a PIN on the YubiKey, which requires the YubiKey Manager CLI or GUI, and require PIN verification for use of the SSH key, with the -O verify-required option. In this scenario, the SSH key itself does not need a password. The password is replaced by the YubiKey and its PIN.

ssh-keygen -t ed25519-sk -O resident -O verify-required -C "your_email@example.com" -f ~/.ssh/id_ed25519_"$(id -un)"

Connecting to GitHub

See the GitHub docs on connecting to GitHub with SSH.

GitHub supports use of SSH keys from FIDO2 security key hardware devices like YubiKeys. See the GitHub docs, GitHub blog, and Yubico blog.

SSH agent forwarding

If working on a server, you can use ssh agent forwarding to access your SSH and GPG keys without having to copy them.

Host yourserver.com
  ForwardAgent yes

General productivity

Media

Science

(Back to top)