78 lines
5.1 KiB
Markdown
78 lines
5.1 KiB
Markdown
Installs the bare necessities to turn a newly minted Arch Linux server into something useful.
|
|
|
|
```
|
|
wget -qO- https://gitea.young.computer/david/MiniServer/raw/branch/main/install.sh | bash
|
|
```
|
|
|
|
## Keep your server up to date
|
|
|
|
```
|
|
update
|
|
```
|
|
|
|
This pulls the latest MiniServer into `~/.local/share/MiniServer`, then runs each step in `updates.d/` in order: the Arch keyring and system packages (plus any packages newly added to `packages.conf`), one-time migrations, AUR packages, pm2, Cockpit, Claude Code, sibling projects, the agent sandbox and Hermes Agent, the firewall, cache cleanup, and a reboot check. If a step fails, the others still run and the failed ones are listed at the end.
|
|
|
|
`update` won't start with less than 10 GiB free on `/`, since running out part way through can leave the system half-upgraded. `UPDATE_FORCE=1 update` skips that check.
|
|
|
|
A change that existing servers need to catch up on (something `install.sh` now does differently) goes in `migrations/$(date +%s).sh`. Each migration runs once per server, on the next `update`.
|
|
|
|
`version` shows which MiniServer commit this server is on, whether a newer one is available, and when it last updated.
|
|
|
|
## Refresh
|
|
|
|
```
|
|
refresh
|
|
```
|
|
|
|
Re-runs `install.sh` to pick up anything new in the installer (services, config). Run `update` afterwards.
|
|
|
|
## Shell
|
|
|
|
MiniServer hooks [shell/bashrc](shell/bashrc) into `~/.bashrc`: a starship prompt, `z` to jump to directories you've visited (zoxide), fzf key bindings (Ctrl-R history, Ctrl-T files, Alt-C directories), larger shared history, and the aliases and functions in [shell/aliases](shell/aliases) and [shell/functions](shell/functions). Anything in `~/.bashrc` after that line overrides it, and your own `~/.config/starship.toml` replaces MiniServer's prompt.
|
|
|
|
## AI agents
|
|
|
|
MiniServer installs Claude Code, opencode and Hermes Agent. To sign in to them, and to mount your Federated Computer Core's Nextcloud files at `/mnt/<domain>`:
|
|
|
|
```
|
|
configure
|
|
```
|
|
|
|
It lists what still needs setting up. `configure <item>` sets up one item, and `configure --list` shows their names.
|
|
|
|
The Nextcloud mount is made by root at the first use after each boot, owned by you. It uses a Nextcloud app password (revocable under Settings > Security in Nextcloud), kept in `/etc/davfs2/secrets`, which only root can read.
|
|
|
|
### Sandbox
|
|
|
|
opencode and Hermes run inside Anthropic's sandbox runtime (`srt`), which uses bubblewrap. An agent can write only to the directory it was started in (plus `/tmp` and package caches), can't read credentials such as `~/.ssh`, `~/.gnupg` or other agents' sign-ins, and can reach only the domains in [sandbox/config/](sandbox/config/). Start an agent from a project directory, not from `~`. Claude Code can't run inside `srt`, because bubblewrap sandboxes can't be nested, so MiniServer turns on Claude Code's own sandbox with the same domain list instead.
|
|
|
|
This works because `shell/bashrc` puts `sandbox/bin` first on `PATH`, so typing `opencode` or `hermes` runs the sandboxed version. `unsandboxed <agent>` runs the agent without the sandbox. To allow more, add files in the same format as the ones in `sandbox/config/` to `~/.config/miniserver/sandbox/`: `base.json` for every agent or `<agent>.json` for one. Lists in your files add to MiniServer's.
|
|
|
|
If Hermes' gateway service (`hermes-gateway.service`) is installed, it runs in the sandbox too. MiniServer turns on lingering for your user so the gateway keeps running when nobody is logged in.
|
|
|
|
## Sibling projects
|
|
|
|
A sibling project is another git repository that builds on MiniServer. To install one:
|
|
|
|
```
|
|
sibling
|
|
```
|
|
|
|
It asks for the repository's git URL, clones it into `~/.local/share/siblings/`, and runs the project's `install.sh` (if it has one). After that, every `update` pulls 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). For full control over how it updates, see [skills/sibling-project-updates.md](skills/sibling-project-updates.md).
|
|
|
|
## Firewall
|
|
|
|
firewalld blocks incoming connections except for the services and ports listed in [firewall.conf](firewall.conf) and in each sibling project's own `firewall.conf`. Each `update` opens anything newly listed, and closes ports MiniServer opened that nothing lists any more, for example after `sibling remove`. Rules you add yourself with `firewall-cmd` are left alone.
|
|
|
|
To see what's actually open:
|
|
|
|
```
|
|
audit
|
|
```
|
|
|
|
It lists every port something on the server is listening on, whatever installed it, along with who can reach it (this machine only, the LAN, Tailscale or containers) and the service behind it. Each port the LAN can reach is marked with the `firewall.conf` that asks for it, or `[in no firewall.conf]` if it was opened some other way. Ports Docker containers publish are shown as reachable whatever firewalld says, because Docker opens them itself. You can stop or start the services from the list; one you stop stays off, through `update` and `refresh` too, until you start it again in `audit`. `audit --list` only shows the ports.
|