dotfiles/README.md

# dotfiles

## Generic TODOs

* Would be great to have a real people-agnostic base, separated from my own customization. Right now, base configuration still have personal path and stuff, making it unusable as-is for other people.
* Have a command to cancel stuff if case something goes bad, want to restore base system, etc
* Automatically enable systemd units 

## What is this, Chosto ?

Basically, a way to bootstrap and keep track of my machines' configuration, that can realistically be used as a base for other people.

## Context and content

I used a lot Debian/Ubuntu with Gnome. So a full Desktop Manager with a stacking Windows Manager.
A friend of mine showed me i3, a great and customizable tiling Windows Manager (i.e. no windows stack, just divide the scren and take all empty space).

With some customization and additionnal component (in this repo), I managed to get a functional and pleasant yet lightweight environment. While initially I used low footprint software like `netctl` for networks, I gave up and choose heavier but simpler option like NetworkManager.

So basically, what I like about this setup is that there is no "useless" menu bar anywhere and no border. Just windows with gaps between them when multiple windows are on the same screen and keyboard shortcuts.

In brief this is the classic Arch/i3 combo with :

* A wonderful theming for most of installed software with [Catppuccin Latte](https://github.com/catppuccin/catppuccin):wq
* [Polybar](https://github.com/jaagr/polybar/), a great replacement for i3-bar with easy custom plugins and [system tray](https://specifications.freedesktop.org/systemtray-spec/systemtray-spec-0.3.html)
* A notification daemon (urgency-aware), [Dunst](https://github.com/dunst-project/dunst), controlled by shortcuts (but possibly with mouse)
* [Rofi](https://github.com/DaveDavenport/rofi), a full-customizable app launcher
* Automatic login (drives are encrypted)
* Automatic backups
* A fancy lock screen, with optional hibernation, either triggered by hotkey or when there is no activity for X minutes
* ZSH with Oh My ZSH
* Mappings to control ALSA volume from dedicated keyboards buttons, to play/plause players compatible with MPRIS D-Bus Interface spec
* Do-not-disturb mode
* Screenshots (area or windows), with saving or uploading to a Lychee server ([custom script here](.config/i3/scripts/screenshot.py))
* A curated list of software for daily usage (browser, mail client, messaging, network manager, password manager etc)
* Fonts I like, used in i3, polybar, etc

## Screenshots

#TODO

## Requirements

* A working [Arch installation](https://wiki.archlinux.org/title/installation_guide)
* Login with a `sudoer` user
* [yay](https://github.com/Jguer/yay) AUR wrapper (better check your [mirrors](https://wiki.archlinux.org/title/Mirrors) too)
* Python 3 and Pip
* Git
* SSH keys to pull and push from Git repositories

## Installation

Please note : on my system `XDG_CONFIG_HOME` is empty and default to `$HOME/.config`.

### Clone the repository

* Clone in bare repository : `git clone --bare https://git.chosto.me/Chosto/dotfiles.git $HOME/.cfg`. A bare repository does not have a working tree (basically it is just `.git` content). So we avoid conflicts with another git repository.
* Create a working tree outside `.cfg` : `git --git-dir=$HOME/.cfg/ --work-tree=$HOME checkout`.

Credits to [this article](https://developer.atlassian.com/blog/2016/02/best-way-to-store-dotfiles-git-bare-repo/) for the trick.

### Configure for your system

#### Polybar

The bottom bar will work for every machine.

However, depending on your machine you may want slightly different modules loaded on the top bar, e.g. battery for laptop. Available modules are listed in [.config/polybar/config_common](.config/polybar/config_common). You also may want to adjust bars' height and DPI. 

This can be done in `~/.config/polybar/conf.d/<env>` (see [explanation for env](#managing-divergences-between-environments)). 

If you want to test this setup, it will probably work with the `laptop` environnment. You can try these fallback values :

```ini
[variables]
dpi = 110
height = 40
top_left = powermenu system-uptime-pretty player-mpris
top_center = xwindow
top_right = system-usb-udev alsa date
```

The bottom bar also reports disk usage, which cannot be configured generically. You can set the partitions you want to track in [config/polybar/scripts/filesystem.data](config/polybar/scripts/filesystem.data) with the following format :

```sh
# Each mount point (parts) will be associated with the icon 
# (icons) having the same array index.
# You can add as many mount point as you want.
icons=( )
parts=(/ /home)
```

#### Wallpaper

You can put an optional wallpaper in `~/.local/share/backgrounds/wallpaper.jpg`.

#### Autologin

Adjust your login in [.config/systemd/getty@tty1.service.d/autologin.conf](.config/systemd/getty@tty1.service.d/autologin.conf).

#### Default user directories

Configure in [.config/user-dirs.dirs](./config/user-dirs.dirs).

#### Backups

Adjust backup script and timer in [.config/systemd](.config/systemd/)
#### Keybinding and started programs

Well... keybindings and programs started automatically are documented in [./.config/i3/config_common](.config/i3/config_common), but you probably want to change almost everything in that file because it is very specific to my setup.

Just note the existence of :
* A film mode (or do-not-disturb), which disable locking and notifications
* A [screenshot custom script](#screenshots)

### Get the system ready

```sh
INIT=1 ~/.init_config.sh [<env>]
```

This will install all needed software and configuration. If you want to re-use my setup, I highly recommand **not to pass `env`**, which are specific overrides for my hardware. You should provide you own adaptations, see [explanations section](#explanations).

In actual setup `env` can be :
* `desk` is currently adjusted for my home setup, i.e. two screens, a keyboard with media keys and [JACK Audio Connection Kit](https://wiki.archlinux.org/title/JACK_Audio_Connection_Kit).
* `laptop` is adjusted for a basic, single 15' screen laptop, with a simple keyboard.

You can now reboot.

### Install Git Hook

You want to add files named `post-merge` **and** `post-commit` in `~/.cfg/hooks` with contains :

```sh
#!/bin/sh

exec env WM_RESTART=1 ~/.init_config.sh <env>
```

And then `chmod +x ~/.cfg/hooks/{post-merge,post-commit}`.
`WM_RESTART` controls whether `i3`, `polybar` and `picom` are restarted.

That way, each time you commit or pull, changes are applied automagically, including configuration deletion detection.

### Git alias

[.zshrc](.zshrc) provides a `config` alias that you can use for manipulating the repository, e.g.

```sh
config add -u
config commit
config push
```

## Explanations

### Managing divergences between environments

This repository is used on several machines, called *environements* and defined at the beginning of [the init script](./.init_config.sh). In my example I have a desktop and a laptop, and envs are called `desk` or `laptop`.

Sometimes, you want a configuration file to be present only in a specific environment. Just add `.<env>` extension to this file and the init script will create symlinks without `.<env>` if running on a matching environment.

Other times, you have a base configuration for all environment with specific additions par-environment. This is called **merging**. The following scheme is used :
```
<config_subdir>
  |__config_common
  |__config.d
     |__[desk]
     |__[laptop]
```

In that case, the script will create a `<config_subdir>/config` file, which contains the concatenation of `config_common` and `config.d/<env>`, the later being optional. Filenames and path are hardcoded for now.

If an `above` file is found in `config.d`, the per-environment configuration will be prepended to the base configuration. This is useful for e.g. setting base variables.

### Configuration outside XDG_CONFIG_HOME, e.g. /etc

Some configuration files reside in `/etc` directory, but I want to keep track of them.

To do so, you need to add *a special text file* named `dest`. In this file, write the destination path. Then, copy the configuration files that you want to track and add them to the repository.

You can combine with `.<env>` extensions or config merging for specific configuration : only the "final files" will be copied, e.g.

```
<config_subdir>
  |__dest = /etc/foo
  |__subfolder
     |__bar.desk
```

At the end, you will have a `/etc/foo/subfolder/bar` file, *iff* the environment is `desk`.

If `INIT` variable is set, files are copied anyway. Otherwise they are copied only if they have changed since the latest commit. The script also ensures that deleted files upstream are also deleted in destination paths.

### Bootstrap

The folder `$XDG_CONFIG_HOME/boostrap` is a special folder used to help launching a fresh system. It uses the [merging system](#managing-divergence-between-environments) to list the Arch packages to install (including AUR ones) in `yay` folder.

These packages are intented to provide reasonable defaults so the configuration just works out-of-the-box. 

These packages are not to specific too my usage but still include messaging app for example, you can remove them if you want. 

### Screenshots

#TODO : move it on another repo

A small script inside [.config/i3/scripts](.config/i3/scripts) uses `maim` to take screenshots.

Then, a flag can either save locally the image or upload it (now, only on a Lychee server using the API).

`~/.config/i3/scripts/config.py` should contains credentials, adapted from [.config/i3/scripts/config.py.example](.config/i3/scripts/config.py.example).

In either case, the link or path is copied to clipboard and a notification is triggered.