287 lines
20 KiB
Markdown
287 lines
20 KiB
Markdown
|
|
|
|
# Federated CoreDesktop
|
|
|
|
## Introduction
|
|
|
|
This is *not* a distribution. Most of the heavy-lifting is accomplished by Arch Linux and to that distribution we send much gratitude. Arch Linux is a wonderful toolbox allowing a Linux enthusiast to build real solutions for all sorts of use cases! It allows us to "get on with building" unlike some of the other distributions where we are forced to wait for upstream changes and fixes. Just our opinion!
|
|
|
|
CoreDesktop is simply some scripts to take an install of Arch Linux and the Gnome desktop environment and add some Gnome extensions so that you get a great tiling environment that can be 100% controlled from the keyboard. This combination is especially good for ultrawide monitors where a power of 3 grid is better than a power of 2. And, with Gnome, you get a nice mouse-capable desktop, too.
|
|
|
|
Additionally, CoreDesktop includes a lot of useful software mostly for work at Federated Computer but you may find it useful for you, too. You may want to suggest some missing titles or services. Please do! Or send in a PR.
|
|
|
|
These scripts are based on the initial work of [Typecraft](https://www.youtube.com/@typecraft_dev).
|
|
|
|
## Installing Arch
|
|
|
|
1) Download the ISO for Arch from [this link](https://archlinux.org/download/). You may need to scroll down to find the download links.
|
|
2) Write the ISO file to a USB stick.
|
|
3) Boot from the Arch ISO USB stick. When the ISO has booted, type `archinstall` to get to the simple installer.
|
|
|
|
(Note: if you're on a laptop and/or don't have a wired internet connection, you'll need to set up the wifi card, etc. Here's [the great article](https://wiki.archlinux.org/title/Network_configuration/Wireless) how to do this. But it really boils down to five steps: at the prompt type "iwctl"; then "device list"; then "station wlan0 scan" where "wlan0" is your wifi device; then "station wlan0 get-networks"; then "station wlan0 connect SSID" where you replace "SSID" with the name of your network.)
|
|
|
|
4) You will go through the different options. Mostly choose the defaults.
|
|
5) Video cards: IF YOU HAVE AN NVIDIA GPU, CHOOSE THE PROPRIETARY NVIDIA OPTION. Choose the AMD option for AMD cards. Just works better. We've found Arch is very good maintaining compatability with Nvidia and AMD options.
|
|
6) When asked what type of system your want, the correct choice is "desktop" and the correct desktop environment is "Gnome".
|
|
7) For sound, "pipewire" is strongly recommended for the sound system choice during install. This is known to work really well with Jitsi, Element, and the other Federated Core SaaS applications, if you're using those. This may no longer be required in the newest installations of Arch Linux.
|
|
8) Reboot the system and log in. You should have a working Arch system at this point but without the Coredesktop configurations.
|
|
|
|
You will likely screw up the installation of Arch the first or second time. Don't despair. Keep trying! The logic of the install will ultimately become clear and, frankly, efficient for you. And, besides, you get to know the base Arch install better and better over time.
|
|
|
|
## (A Note About Networking in Arch)
|
|
|
|
You'll need a connection to the internet to successfully install Arch.
|
|
|
|
If you have a wired connection, then your network should "just work" and you can use that to configure your Arch network installation. But if you do not have a wired connection and you have a wifi chip installed in your computer, before installing Arch you'll want to set up the wifi network. You can do that using the too `iwctl`.
|
|
|
|
Type `iwctl` and that will put you into the utility `iwd`.
|
|
|
|
To list the wireless adapters type: `device list`. If your wireless device is "wlan0" (for example) you next type: `station wlan0 scan` to put the wireless chip into scan mode then `station wlan0 get-networks` to find the wireless networks available. The join your wireless network with the command `station wlan0 connect SSID` where SSID is the wireless network name. You can test your network with a ping to some server, etc.
|
|
|
|
When you have the wireless network working (check by doing "ping google.com"), then you can proceed to install Arch.
|
|
|
|
## Installing Federated CoreDesktop
|
|
|
|
When Arch and Gnome have been successfully installed, you log in to the system then...
|
|
|
|
1) Open the "Web" browser then navigate to https://gitea.federated.computer and click "Explore" and "CoreDesktop". Scroll down and you'll find the command to enter to kick off installation.
|
|
|
|
2) Open a terminal, then enter the following command (you copied it from Gitea in step #1):
|
|
|
|
```
|
|
wget -qO- https://gitea.federated.computer/Federated_Computer/coredesktop/raw/branch/main/install.sh | bash
|
|
```
|
|
3) Enter your password when asked, once at the start. Be patient: it takes a while.
|
|
|
|
4) At the end, it offers to run `configure`, which connects to your Federated Computer Core, sets up backups and signs you in to the AI agents (see "Configure" below). If the install brought in a newer kernel, it asks you to reboot first; run `configure` after the reboot.
|
|
|
|
5) If something fails, just run the command again. It skips what's already done.
|
|
|
|
6) Reboot (`sudo reboot now`) when you're done, so that Element can find the encryption keychain, among other things.
|
|
|
|
## Notes about what is installed
|
|
|
|
You will end up with a Gnome system with a three-tile set up (again, great for widescreens). If you want to change the tiling, the icon in the top right of your screen allows you to change your tiling setup however you want. Using the super key (windows key or equivalent) plus the arrow keys, you can move windows around the screen.
|
|
|
|
The scripts are installed in ~/.local/share/coredesktop/
|
|
|
|
The scripts install lots of useful software. There are (4) main ways software is installed: pacman, AUR, Flathub, and mise.
|
|
|
|
### Pacman
|
|
|
|
Pacman installs software from the "packages.conf" file. It installs software such as neovim, tmux, Go, Rust, Docker, Tailscale, Element, LibreOffice, etc. Tell me if you want other tools or submit a pull request.
|
|
|
|
### AUR
|
|
|
|
Yay is installed as is the way AUR packages are installed and maintained. Examples include the Helium Browser and Winboat.
|
|
|
|
### Flathub
|
|
|
|
The file "install-flatpaks.sh" file for Flatpaks.
|
|
|
|
Flatpaks installed include: Chrome, Chromium, Firefox, Brave, Zen, Vivaldi (browsers), Signal, Telegram, Discord, Revolt, FluffyChat (messaging), Thunderbird and Evolution (email), VS Code and VSCodium (VS Code without the Microsoft telemetry), Obsidian and Logseq (notes), Apostrophe (markdown writer), Kdenlive (video editing), OBS (video recording), Audacity (audio editing), Inkscape (vector graphics), Scribus (page layout), Spotify, Jellyfin (media client), Zoom, Remmina and RustDesk (remote desktop), Postman, DBeaver and Beekeeper Studio (database clients), Alpaca and LM Studio (local AI), LocalSend (send files to other devices), Boxes (virtual machines), Impression (write ISOs to USB sticks), Trayscale (Tailscale), Warehouse (manage Flatpaks), Extension Manager (GNOME extensions), qBittorrent, RetroArch and more. See [install-flatpaks.sh](install-flatpaks.sh) for the full list.
|
|
|
|
If you want to install more software from Flathub, simple visit https://flathub.org.
|
|
|
|
### Mise
|
|
|
|
Ruby and Rails are installed using Mise from the file "install-mise-ruby-rails.sh".
|
|
|
|
### Development Tools
|
|
|
|
Lots of development tools including herdr, neovim, tmux, go, hugo, python, rust, rails, ruby, docker and docker compose, etc. Three terminals: console, kitty, ghostty.
|
|
|
|
### Printing and Networking
|
|
|
|
The printing service (cups) is turned on. This may need more work to "just work" with other "coredesktop" machines.
|
|
|
|
mDNS is installed and enabled so the your can find and SSH to your machine on your LAN using {machinename}.local.
|
|
|
|
### Firewall
|
|
|
|
The ufw firewall is on. It blocks incoming connections except SSH (22), mDNS (5353/udp), LocalSend (53317) and anything arriving over Tailscale. ufw-docker is installed too, because ports published by Docker containers otherwise get around ufw. To let a container's port through, use `sudo ufw-docker allow {container} {port}`. To open a port for something else, e.g. a dev server you want to reach from another machine, use `sudo ufw allow {port}/tcp`. `sudo ufw status` shows the current rules.
|
|
|
|
### Shell
|
|
|
|
Your ~/.bashrc sources ~/.local/share/coredesktop/shell/bashrc, which sets up the starship prompt, zoxide (`z {part of a path}` jumps to a directory you've used before), fzf key bindings (Ctrl-R searches history, Ctrl-T inserts a file path), eza for `ls`/`ll`/`la`/`lt`, and the aliases and functions in [shell/](shell/). If you already have ~/.config/starship.toml, your prompt config is used. Anything you add to ~/.bashrc after the CoreDesktop line overrides it.
|
|
|
|
### Snapshots
|
|
|
|
If / is btrfs (the archinstall default), Snapper takes a snapshot of / before every `update` and keeps the last 5. /home is a separate subvolume and isn't included, so rolling back never touches your files. `sudo snapper -c root list` shows the snapshots.
|
|
|
|
These snapshots can't be picked from the boot menu. To roll back after a bad update, boot the Arch ISO and replace the @ subvolume with a snapshot:
|
|
|
|
```
|
|
mount -o subvolid=5 /dev/{root partition} /mnt
|
|
mv /mnt/@ /mnt/@.broken
|
|
btrfs subvolume snapshot /mnt/@.snapshots/{number}/snapshot /mnt/@
|
|
reboot
|
|
```
|
|
|
|
If the disk is encrypted, open it with `cryptsetup open` first and mount the opened device. Once the system works again, free the space the broken root used:
|
|
|
|
```
|
|
sudo mount -o subvolid=5 /dev/{root partition} /mnt
|
|
sudo btrfs subvolume delete /mnt/@.broken
|
|
sudo umount /mnt
|
|
```
|
|
|
|
### GPU drivers
|
|
|
|
The installer adds the Vulkan driver for Intel and AMD GPUs. If there's an NVIDIA GPU and archinstall's proprietary driver wasn't chosen, it installs NVIDIA's driver: the open kernel modules for GTX 16xx / RTX 20xx and newer, or the 580xx legacy driver for older cards back to the GTX 900 series. Reboot afterwards.
|
|
|
|
### System defaults
|
|
|
|
- SSH connections notice a dropped link within a minute instead of hanging (override per host in ~/.ssh/config).
|
|
- Logins allow 10 wrong passwords before locking the account for 2 minutes (Arch's default is 3 tries, then 10 minutes).
|
|
- Shutdown waits at most 10 seconds for a service that won't stop, instead of 90.
|
|
- If memory runs out, systemd-oomd closes the app causing it instead of the whole desktop freezing.
|
|
- Boot no longer waits for the network.
|
|
- Commands run over SSH (`ssh {machine} {command}`) can find tools in ~/.local/bin and mise.
|
|
|
|
## Keep your System Up-to-date
|
|
|
|
From time-to-time, you'll want to update your system. Hopefully you'll do this more than once-a-month.
|
|
|
|
To update the system type into the terminal:
|
|
|
|
```
|
|
update
|
|
```
|
|
|
|
The script pulls the latest CoreDesktop, then runs each step in ~/.local/share/coredesktop/updates.d/ in order. Among other things it:
|
|
|
|
- stops if there's less than 10 GiB free on / (run `UPDATE_FORCE=1 update` to skip the check)
|
|
- snapshots / first, if Snapper is set up (see Snapshots above)
|
|
- updates the Arch keyring, then Arch and GNOME, then AUR packages, Flatpaks, Ruby, the pipx apps CoreDesktop installs, GNOME extensions and firmware
|
|
- warns you not to reboot if the initramfs failed to rebuild
|
|
- runs any one-time migrations, the way existing machines pick up new CoreDesktop setup
|
|
- removes packages that were installed only because something else needed them, and are no longer needed by anything. It lists what it removed. Packages CoreDesktop installs are never removed this way. To stop another package you use directly from being removed, run `sudo pacman -D --asexplicit <package>`
|
|
|
|
If a step fails, the other steps still run, and the failed ones are listed at the end.
|
|
|
|
It is a good idea to reboot after an update especially if you see you have a new Linux kernel installed (and that happens frequently enough for Arch).
|
|
|
|
Note: sometimes, for whatever reason, the update barfs. Take a look at [https://archlinux.org](https://archlinux.org) in the "Latest News" section for fixes.
|
|
|
|
### Refresh your system
|
|
|
|
If you want to pull down "new" additions to Coredesktop, run in the terminal:
|
|
|
|
```
|
|
refresh
|
|
```
|
|
|
|
This will download the latest repo and run through the original installation script adding any "new" applications or services. You should run "update" after running "refresh".
|
|
|
|
### Which version am I running?
|
|
|
|
CoreDesktop is a rolling release, so its version is the date of the latest CoreDesktop change on your machine, followed by that change's id. To see it, run in the terminal:
|
|
|
|
```
|
|
version
|
|
```
|
|
|
|
```
|
|
CoreDesktop 2026.10.22 (c5f0651)
|
|
Kernel 7.2.11-arch1-1
|
|
Last update 2026-10-22 13:43
|
|
```
|
|
|
|
The kernel comes from Arch, so it's shown separately. If a newer kernel is waiting for a reboot, "version" says so. It also tells you if a newer version of CoreDesktop is available.
|
|
|
|
You don't have to check by hand: a few minutes after you log in, and every few hours after that, CoreDesktop checks for a new version and shows a notification if there is one. Click it to run "update" in a terminal, or dismiss it. Once dismissed, you won't be notified again until there's an even newer version.
|
|
|
|
### Sibling projects
|
|
|
|
A sibling project is another git repository that builds on CoreDesktop. To install one, run in the terminal:
|
|
|
|
```
|
|
sibling
|
|
```
|
|
|
|
It asks for the repository's git URL, clones it into ~/.local/share/siblings/, runs the project's "install.sh" (if it has one), and confirms the install. After that, every "update" pulls the latest version of each sibling and runs its "update.sh" (if it has one).
|
|
|
|
Use "sibling list" to see what's installed and "sibling remove {name}" to uninstall one.
|
|
|
|
To make your own repository work as a sibling project, see [skills/sibling-project-format.md](skills/sibling-project-format.md).
|
|
|
|
## Configure
|
|
|
|
Some of what CoreDesktop installs needs you to sign in or make a choice before you can use it. To see what's set up and set up the rest, run in the terminal:
|
|
|
|
```
|
|
configure
|
|
```
|
|
|
|
It covers:
|
|
|
|
- **Your Federated Computer Core.** Give it your Superpanel's address (e.g. https://superpanel.example.com), your Core email, name and password, and it adds Superpanel to your applications, adds your Nextcloud (calendar, contacts and files) and email to GNOME's Online Accounts, and mounts your Nextcloud files at /mnt/example.com ("example.com" in the Files sidebar), and points Element at your Core's Matrix server. For Nextcloud and the files it creates a Nextcloud app password, which you can revoke in Nextcloud under Settings > Security.
|
|
- **Your Core's Tailscale network.** Joins this computer to it through headscale.example.com, so you can reach your other machines on it. Set up your Core first. You sign in through a link it shows you; if this computer is on another Tailscale network, it moves it to your Core's.
|
|
- **Daily backups of your home folder** to your Nextcloud files, in a .backup-{machine name} folder, with restic. Set up your Core first. The backup is encrypted with a passphrase that `configure` shows you once: save it somewhere other than this computer, such as Bitwarden. It keeps 7 daily, 4 weekly and 6 monthly backups, and leaves out caches and things that can be reinstalled. To leave out more, list paths in ~/.config/coredesktop/backup-exclude, one per line. restic reaches Nextcloud directly through rclone with its own Nextcloud app password, so the backup doesn't depend on the /mnt mount. See "Restoring from a backup" below.
|
|
- Signing in to Claude Code, opencode and Hermes Agent and choosing their model providers.
|
|
|
|
To set up one thing, name it, e.g. `configure hermes`; `configure --list` shows the names.
|
|
|
|
### Restoring from a backup
|
|
|
|
To see the backups and get files back:
|
|
|
|
```
|
|
source ~/.local/share/coredesktop/system/backup-env.sh
|
|
restic snapshots
|
|
restic restore latest --target ~/restored --include ~/Documents
|
|
```
|
|
|
|
On a new computer, run `configure core` and `configure backup` first. Then name the old computer's folder, and restic asks for the passphrase you saved:
|
|
|
|
```
|
|
source ~/.local/share/coredesktop/system/backup-env.sh .backup-{old machine name}
|
|
restic snapshots
|
|
```
|
|
|
|
`systemctl --user list-timers coredesktop-backup.timer` shows when the next backup runs, and `journalctl --user -u coredesktop-backup` shows how the last ones went.
|
|
|
|
## Sandboxed AI agents
|
|
|
|
CoreDesktop installs the AI coding agents opencode, Hermes Agent and Claude Code, and runs them in a sandbox. In the sandbox, an agent:
|
|
|
|
- can change files only in the directory you start it from (plus its own settings and a few package caches), so start it from a project directory
|
|
- can't read your SSH keys, password stores, browser profiles, Flatpak apps' data (browsers, Signal, Telegram and the rest), your Nextcloud password, cloud and Git credentials, or the other agents' logins
|
|
- can reach only AI providers and common developer sites: GitHub, Gitea, npm, PyPI, crates.io, RubyGems, the Go module proxy and archlinux.org
|
|
|
|
Typing `opencode`, `hermes` or `hermes-agent` runs it in the sandbox. To run one without it, type `unsandboxed opencode`. Hermes' gateway, the background service that lets you talk to Hermes through Matrix and other messaging apps, runs in the sandbox too, and can reach the Matrix server in Hermes' settings. For other messaging services, add their domains as shown below. Hermes talks to its gateway through a local socket, so its sandbox allows local sockets but hides the ones that would let it act outside the sandbox: your session's D-Bus and SSH agent, Docker, Tailscale, X11, tmux and browsers. Claude Code uses its own built-in sandbox for every command it runs (see `/sandbox` inside Claude).
|
|
|
|
Before using an agent the first time, sign in and choose a model provider with `configure` (see below).
|
|
|
|
If an agent needs a site or folder the sandbox blocks, add it in `~/.config/coredesktop/sandbox/base.json` (for every agent) or `~/.config/coredesktop/sandbox/opencode.json` (for one agent):
|
|
|
|
```json
|
|
{
|
|
"network": { "allowedDomains": ["docs.example.com"] },
|
|
"filesystem": { "allowWrite": ["~/notes"] }
|
|
}
|
|
```
|
|
|
|
The sandbox is Anthropic's [sandbox runtime](https://github.com/anthropics/sandbox-runtime), which uses bubblewrap and socat. The default rules are in [sandbox/config/](sandbox/config/).
|
|
|
|
## Open ports
|
|
|
|
`audit` shows the network ports open on this computer. For each one it shows who can connect to it, after the firewall: only this computer, your Tailscale network, or your LAN. It also shows which service opened the port and why.
|
|
|
|
You can stop a service from there, which also keeps it from starting at boot, or start a stopped one again. `update` leaves the services you stop off. audit won't stop the ones the desktop, Files or the network need. Run it with sudo rights so it can name the services run by root; `audit --list` only shows the ports.
|
|
|
|
## mDNS Networking
|
|
|
|
mDNS lets you reach other machines on your LAN as "machine.local", e.g. `ssh machine.local`. When systemd-resolved is enabled, the installer sets it up with [fixmdns.sh](fixmdns.sh): it turns on Avahi and adds nss-mdns to /etc/nsswitch.conf ahead of systemd-resolved, so the two don't conflict. On a machine without systemd-resolved, run `bash ~/.local/share/coredesktop/fixmdns.sh` yourself. See the [Arch wiki](https://wiki.archlinux.org/title/Avahi#Hostname_resolution) for more.
|
|
|
|
## Contributing
|
|
|
|
This whole "project" is licensed under the MIT License. Want to help make CoreDesktop better? Awesome! We welcome any and all help. Just contribute a PR and we're off to a better CoreDesktop.
|
|
|
|
Changes to install.sh only reach new installs. If existing machines need the change too, also add a migration: a script named `migrations/$(date +%s).sh` that `update` runs once on each machine. It may also run on fresh installs, so make it safe to repeat.
|
|
|
|
## Bonus
|
|
|
|
Bonus: here's a [nice song to listen to while you're installing](https://music.youtube.com/watch?v=y-5o2f9wzmw&si=_z9kcKHRwj-KTs7w).
|