|
1 | | -machine-setup |
2 | | -============= |
3 | | - |
4 | | -Sets up a machine environment from a clean install. |
5 | | - |
6 | | -I end up on new machines all the time and need to reinstall the same things |
7 | | -over again, copy settings files, etc. This repo is my solution. Everything |
8 | | -here is my personal files and preferences, so you may not want to use them |
9 | | -(though I think my Vim setup is pretty nice!). That being said, you may still |
10 | | -find this repo useful to co-opt for your own purposes or as an example of |
11 | | -various things (like a great [.vimrc](resources/vim/.vimrc) file!). |
12 | | - |
13 | | -To run it, you need to get the repository over to the machine, most of which |
14 | | -come with `git` preinstalled: |
15 | | - |
16 | | -``` |
17 | | -git clone https://github.com/jeremyephron/machine-setup |
18 | | -``` |
19 | | - |
20 | | -Navigate to the repository: |
21 | | - |
22 | | -``` |
23 | | -cd machine-setup |
24 | | -``` |
25 | | - |
26 | | -Run the setup script: |
27 | | - |
28 | | -``` |
29 | | -./setup.sh |
30 | | -``` |
31 | | - |
32 | | -Source your bashrc and bash profile (either `~/.profile` on Debian/Ubuntu or |
33 | | -`~/.bash_profile` on MacOS/CentOS/Fedora/Red Hat; this command covers both): |
34 | | - |
35 | | -``` |
36 | | -source ~/.bashrc |
37 | | -(test -r ~/.bash_profile && source ~/.bash_profile) || source ~/.profile |
38 | | -``` |
39 | | - |
40 | | -Now, you can delete the repository, and you're good to go: |
41 | | - |
42 | | -``` |
43 | | -cd .. && rm -rf machine-setup |
44 | | -``` |
45 | | - |
46 | | -Configuring the Setup |
47 | | ---------------------- |
48 | | - |
49 | | -This setup script installs a lot of stuff that I may not want all the time. |
50 | | -For this reason you can disable specific components or enable only the |
51 | | -components you need. |
52 | | - |
53 | | -If I wanted to avoid installing LaTeX for instance, I could run: |
54 | | - |
55 | | -``` |
56 | | -DISABLE_LATEX=1 ./setup.sh |
57 | | -``` |
58 | | - |
59 | | -If I just wanted to do some quick editing, maybe I only need my Vim files and |
60 | | -Homebrew set up. So I can run: |
61 | | - |
62 | | -``` |
63 | | -ENABLE=1 ENABLE_HOMEBREW=1 ENABLE_VIM=1 ./setup.sh |
64 | | -``` |
65 | | - |
66 | | -where `ENABLE=1` tells the script to only run components that are explicitly |
67 | | -enabled, and `ENABLE_VIM=1` enables the Vim component. |
68 | | - |
69 | | -Alternatively, you can run the setup in interactive mode, where it will ask |
70 | | -you to confirm whether each component should run: |
71 | | - |
72 | | -``` |
73 | | -INTERACTIVE=1 ./setup.sh |
74 | | -``` |
75 | | - |
76 | | -Repository Overview |
77 | | --------------------- |
78 | | - |
79 | | -Here's an overview of important files or directories: |
80 | | - |
81 | | -- [setup.sh](setup.sh): the main setup script |
82 | | - |
83 | | -- [resources](resources): directory containing any files that need to copied |
84 | | - |
85 | | -- [bash_scripts](bash_scripts): directory containing the defined behavior for |
86 | | -each of the components |
87 | | - |
88 | | -Components |
89 | | ----------- |
90 | | - |
91 | | -### Homebrew |
92 | | - |
93 | | -[Homebrew](https://brew.sh/) is my favorite package manager for Mac or Linux, |
94 | | -and is required to install many of the other components. |
95 | | - |
96 | | -### Vim |
97 | | - |
98 | | -[Vim](https://www.vim.org/) is my goto editor, and it will install the latest |
99 | | -version with `brew`. Additionally, it configures a |
100 | | -[.vimrc](resources/vim/.vimrc) file along with a colorscheme and other |
101 | | -vim settings files viewable in [](resources/vim/). |
102 | | - |
103 | | -### FZF |
104 | | - |
105 | | -[FZF](https://github.com/junegunn/fzf) is a fuzzy file searcher that |
106 | | -dramatically enhances your command line experience, and the Vim component |
107 | | -includes it as a plugin (separate from this component). |
108 | | - |
109 | | -### tree |
110 | | - |
111 | | -Just your standard `tree` command to recursively list directories. |
112 | | - |
113 | | -### Git |
114 | | - |
115 | | -I prefer having the latest version of [Git](https://git-scm.com/) installed |
116 | | -with `brew`. |
117 | | - |
118 | | -### nnn |
119 | | - |
120 | | -[nnn](https://github.com/jarun/nnn) is a very powerful terminal file manager |
121 | | -that helps you get around more efficiently. |
122 | | - |
123 | | -### LateX |
124 | | - |
125 | | -[LaTeX](https://www.latex-project.org/) is a typesetting system mostly used |
126 | | -for academic and scientific work. This component installs the |
127 | | -[Tex Live](https://www.tug.org/texlive/) distribution on Linux and |
128 | | -[MacTeX](https://www.tug.org/mactex/) on MacOS. |
129 | | - |
130 | | -### Python |
131 | | - |
132 | | -Installs the latest version of [Python](https://www.python.org/) with `brew`. |
133 | | -Also installs [`pyenv`](https://github.com/pyenv/pyenv), which I use for |
134 | | -Python version management. |
135 | | - |
136 | | -### NodeJS |
137 | | - |
138 | | -Installs [NodeJS](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/) for |
139 | | -package management. |
140 | | - |
141 | | -### Java |
142 | | - |
143 | | -Installs [OpenJDK](https://openjdk.java.net/). |
144 | | - |
145 | | -### Rust |
146 | | - |
147 | | -Installs [rustup](https://rustup.rs/) with `brew`, and then installs |
148 | | -[Rust](https://www.rust-lang.org/) with `rustup`. |
149 | | - |
150 | | -### Boost |
151 | | - |
152 | | -The [Boost](https://www.boost.org/) C++ libraries are a great extension to the |
153 | | -STL. |
154 | | - |
155 | | -### Python Packages |
156 | | - |
157 | | -Installs various Python packages that I like to have installed globally on my |
158 | | -system, including: |
159 | | - |
160 | | -- `setuptools` |
161 | | -- `twine` |
162 | | -- `numpy` |
163 | | -- `scikit-learn` |
164 | | -- `matplotlib` |
165 | | -- `pandas` |
166 | | -- `jupyter` |
167 | | -- `requests` |
168 | | -- `pillow` |
169 | | -- `beautifulsoup4` |
| 1 | +# Jeremy's machine setup |
| 2 | + |
| 3 | +This repository turns a fresh Apple silicon Mac or Ubuntu 24.04+ machine into |
| 4 | +Jeremy's working environment. It also converges an existing machine safely: |
| 5 | +preview first, install missing pieces without blanket upgrades, and keep every |
| 6 | +removal in a separate confirmed cleanup workflow. |
| 7 | + |
| 8 | +The fast path delivers Bash, Git/SSH, Neovim, tmux, the preferred command-line |
| 9 | +tools, managed configuration, and applicable macOS preferences. A full profile |
| 10 | +continues with the selected language runtimes, infrastructure tools, desktop |
| 11 | +apps, and LaTeX. The target is a useful core in well under 20 minutes; app |
| 12 | +downloads and TeX can continue after that depending on the network. |
| 13 | + |
| 14 | +## Start a new machine |
| 15 | + |
| 16 | +After the OS account, network, and Bitwarden are ready: |
| 17 | + |
| 18 | +```bash |
| 19 | +mkdir -p "$HOME/src/personal" |
| 20 | +git clone https://github.com/jeremyephron/machine-setup.git "$HOME/src/personal/machine-setup" |
| 21 | +cd "$HOME/src/personal/machine-setup" |
| 22 | +./setup.sh apply --core-only |
| 23 | +./setup.sh doctor --core-only |
| 24 | +./setup.sh apply |
| 25 | +./setup.sh doctor |
| 26 | +``` |
| 27 | + |
| 28 | +The first run asks for a machine profile and local-only identity values. The |
| 29 | +selected profile is saved, so later commands can omit `--profile`. The first two |
| 30 | +commands establish and verify the fast terminal/editor baseline; the last two |
| 31 | +install and verify the full profile. Re-running `apply` is expected and safe. |
| 32 | + |
| 33 | +On an existing machine, begin with a read-only preview: |
| 34 | + |
| 35 | +```bash |
| 36 | +./setup.sh plan |
| 37 | +``` |
| 38 | + |
| 39 | +If the machine has no saved profile yet, the command asks you to select one. |
| 40 | + |
| 41 | +## Commands |
| 42 | + |
| 43 | +| Command | Purpose | Changes data? | |
| 44 | +| --- | --- | --- | |
| 45 | +| `plan` | Show the profile, package gaps, and chezmoi diff when initialized | No | |
| 46 | +| `apply` | Install missing items and preview/apply managed-file changes | Yes | |
| 47 | +| `doctor` | Check the machine and list manual follow-ups | No | |
| 48 | +| `update` | Explicitly upgrade packages and refresh verified locks | Yes | |
| 49 | +| `identities` | Reuse or generate per-account SSH keys and guide GPG setup | Yes, prompted | |
| 50 | +| `cleanup` | Review optional cleanup candidates and confirm each action | Yes, separately confirmed | |
| 51 | + |
| 52 | +Useful flags are `--profile NAME`, `--core-only`, `--skip-desktop`, `--dry-run`, |
| 53 | +and `--yes`. A dry run is equivalent to the read-only plan. `--yes` never |
| 54 | +bypasses destructive cleanup confirmations. |
| 55 | + |
| 56 | +## Profiles |
| 57 | + |
| 58 | +| Profile | Intended machine | Included layers | |
| 59 | +| --- | --- | --- | |
| 60 | +| `personal-mac-laptop` | Personal Apple silicon Mac | Core, development, infrastructure, desktop, LaTeX, macOS preferences | |
| 61 | +| `work-mac-laptop` | Work Apple silicon Mac | Core, development, infrastructure, desktop, LaTeX, macOS preferences | |
| 62 | +| `work-mac-server` | UI-capable, often-headless Mac mini | Core, development, infrastructure, desktop, LaTeX, macOS preferences | |
| 63 | +| `work-linux-server` | Ubuntu 24.04+ server | Core, development, infrastructure | |
| 64 | +| `personal-linux-laptop` | x86-64 Ubuntu 24.04+ desktop | Core, development, infrastructure, desktop, LaTeX | |
| 65 | +| `minimal-remote` | Root-enabled Ubuntu host | Core only | |
| 66 | +| `minimal-remote-no-root` | Restricted Linux host | Verified user-local core subset | |
| 67 | + |
| 68 | +Full UI profiles target the same workflows, but their application packages |
| 69 | +differ where an app is platform-specific. Web equivalents and manual omissions |
| 70 | +remain visible in the finish checklist. |
| 71 | +Ubuntu ARM64 remains supported by the server and remote profiles; its proprietary |
| 72 | +desktop app set is not represented as equivalent to x86-64. |
| 73 | + |
| 74 | +## Important behavior |
| 75 | + |
| 76 | +- [chezmoi](https://www.chezmoi.io/) owns dotfiles and templates. Machine-local |
| 77 | + names, emails, GPG fingerprints, SSH key paths, and proxy endpoints live only |
| 78 | + in its local config. |
| 79 | +- Homebrew owns most cross-platform packages; Ubuntu `apt` owns prerequisites |
| 80 | + and services. Normal `apply` passes Homebrew's no-upgrade mode. |
| 81 | +- [mise](https://mise.jdx.dev/) selects Python 3.13, current Node LTS, and current |
| 82 | + Java LTS. Its checked-in lock records URLs and checksums for Apple silicon, |
| 83 | + Linux x86-64, and Linux ARM64. |
| 84 | +- Rust uses rustup stable. Project files can override any language version. |
| 85 | +- Python projects stay clean. `ipy`/`pyscratch` opens a separate scientific |
| 86 | + environment with Jupyter, NumPy, SciPy, pandas, Polars, Matplotlib, scikit-learn, |
| 87 | + scikit-image, Pillow, Requests, and Beautiful Soup. |
| 88 | +- Git has no fallback identity. Repositories under `~/src/personal` use the |
| 89 | + personal account; `~/src/work` and the locally named company folder use work; |
| 90 | + `~/src/scratch` requires an explicit choice. The company folder name is kept |
| 91 | + only in the local chezmoi config. |
| 92 | +- Standalone release archives are version-pinned and checksum-verified; signed |
| 93 | + package managers and vendor repositories manage the rest. |
| 94 | +- Secrets, private keys, VPN settings, account sessions, and employer-specific |
| 95 | + data are never committed. |
| 96 | + |
| 97 | +See [the component review](docs/components.md), |
| 98 | +[existing-machine guide](docs/existing-machines.md), |
| 99 | +[manual finish checklist](docs/manual-steps.md), and |
| 100 | +[maintenance notes](docs/maintenance.md). |
0 commit comments