dotfiles/README.md

# Dotfiles

## How to Use

First, clone the repository:

```sh
git clone https://gitea.tomastm.com/tomas.mirchev/dotfiles.git ~/.dotfiles && cd ~/.dotfiles
```

The `setup` script will automatically update the remote repository URL. However, if you are configuring the dotfiles manually, make sure to change it after adding your SSH key:

```sh
git remote set-url origin git@gitea.tomastm.com:tomas.mirchev/dotfiles.git
git remote -v
```

The `manage.py` script allows you to link configurations, install packages, and set up environments. To view available arguments, use:

```sh
manage.py -h
manage.py <link|install|setup> -h
```

### Common Commands:

- `manage.py link <environment> [--copy] [-f|--force] [-p|--package]`
- `manage.py install <environment> [-p|--package]`
- `manage.py setup <environment> [--extra]`

You can create multiple environments, following this structure:

- `config/<environment>`
- `config.json` (add `<environment>` to the JSON file)
- `setups/<environment>`
- Any additional scripts can be placed in `scripts/<script>`, following the naming convention `<env>-<script>`.

## Environments

Although you can specify any environment using `manage.py`, the recommended workflow follows this structure:

### MacOS (`macos`)

> **Setup command:** `manage.py setup macos`

Since macOS is the host machine, it should use minimal applications and configurations. Whenever possible, install applications via Homebrew.

Before formatting your machine, back up installed formulas and casks:

```sh
scripts/macos-brew_backup.sh
```

This backup will be restored automatically when setting up `macos`.

#### Essential Applications:

- **LinearMouse**: Invert scrolling, adjust scrolling by pixels, and fix pointer acceleration.
- **Karabiner**: Configure keybindings and modifier keys.
- **Rectangle**: Window tiling.
- **Window-Tagger**: Custom window manager ([repository](https://gitea.tomastm.com/tomas.mirchev/window-tagger)).
- **Ghostty**: Terminal emulator.

System settings cannot be automatically backed up. Refer to `obsidian#MacSettings.md` for manual adjustments.

#### UTM (Virtual Machines)

Development should occur inside virtual machines. UTM is preferred due to its open-source nature and support for both QEMU and Apple Hypervisor.

> **Note:** When installing ISOs, ensure the correct architecture is selected.

For Debian-based setups, avoid setting a `root` password to enable automatic `sudo` installation and add your user to the sudo group.

#### DNS Configuration

Communication between the host and virtual machines happens via local IPs set by UTM DHCP. To simplify this process, use `dnsmasq` (installed via `manage.py`).

##### 1. Verify `dnsmasq` is Running

```sh
pgrep dnsmasq  # Should return a PID if running
```

##### 2. Determine the Default Gateway

On **macOS (host):**

```sh
ifconfig | grep 192
```

On the **VM** (in "Shared Network" mode):

```sh
ip r
```

Typically, the **gateway IP** is `192.168.64.1`. If different, update the next steps accordingly.

##### 3. Edit `dnsmasq.conf`

```sh
sudo vim /opt/homebrew/etc/dnsmasq.conf
```

Add:

```ini
# Define local domains
address=/personal.utm.local/192.168.64.2
address=/university.utm.local/192.168.64.3
address=/personal.workstation.lan/192.168.50.2

# Listening addresses (include gateway IP)
listen-address=127.0.0.1,192.168.64.1
```

##### 4. Configure macOS to Use `dnsmasq`

```sh
sudo mkdir -p /etc/resolver
sudo vim /etc/resolver/local
sudo vim /etc/resolver/lan
```

Add:

```plaintext
nameserver 127.0.0.1
```

Alternatively:

```sh
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/local
```

##### 5. Restart `dnsmasq` and Flush DNS Cache

```sh
sudo brew services restart dnsmasq
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
```

##### Notes

- `dnsmasq` requires manual removal on Brew upgrades or uninstallation:

```sh
sudo rm -rf /opt/homebrew/Cellar/dnsmasq/*/sbin
sudo rm -rf /opt/homebrew/opt/dnsmasq
sudo rm -rf /opt/homebrew/var/homebrew/linked/dnsmasq
```

### Linux VM (`linux-vm`)

> **Setup command:** `manage.py setup linux-vm --extra "<hostname>"`

After running the setup script, follow any additional manual steps it outputs.

The most critical step is authenticating with the registry:

```sh
docker login registry.tomastm.com
```

### Linux Dev (`linux-dev`)

This environment does not use a `setup` command, as it is configured via `Dockerfile`. However, `install` and `link` commands are available.

Use `link --copy` to avoid redundant configurations inside images, reducing final image size.

A base image (`base-debian`) contains essential utilities. Additional images exist for specific tools, such as `node` and `python`. View all images at: [Dev Containers](https://gitea.tomastm.com/tomas.mirchev/dev-containers).

Each project should run its own container instance, enabling seamless project switching. Code remains on a mounted volume from the Linux VM.

Containers persist until manually stopped, allowing `tmux` sessions to remain active.

For convenience, use the `dev` script located in `~/bin` (automatically added to `PATH`).

```sh
dev -i <image> <name>

# Example:
dev -i node myapp
```

This creates a container named `node-myapp` (`<image>-<name>`).

All images support both `arm64` and `amd64` architectures, automatically detected during execution.

---

## Miscellaneous

### Building NeoVim

NeoVim is mirrored to Gitea to build `.deb` packages for releases. Follow these steps:

```sh
git clone git@gitea.tomastm.com:tomas.mirchev/neovim.git
cd neovim
git checkout tags/<tag>
make CMAKE_BUILD_TYPE=RelWithDebInfo
cd build
cpack -G DEB
```

This builds for the host machine's architecture. The package should follow this format:

```
nvim-linux-$(dpkg --print-architecture).deb
```

Create a new release in the mirrored repository and attach the `.deb` file.

### Proxmox

UTM is the preferred VM solution, but Proxmox can be used for homelab setups.

To fix `apt update/upgrade` issues:

1. Go to "Datacenter" → "workstation" → "Repositories".
2. Disable both enterprise sources.
3. Add a new repository with "No-Subscription".
4. Refresh "Updates" and proceed.