# ZimaOS-Specific Server Environment Notes

## Package Manager Reality
ZimaOS **has no package manager** (`apt`, `pacman`, `apk`, `dnf` — all absent). It is a custom Linux distribution built for NAS/self-hosting, derived from IceWhale's CasaOS ecosystem.

**Version observed:** ZimaOS v1.6.1 on ZimaCube hardware

## What this means for tool installation
- Cannot install system libraries (libatk, libgtk, libcups, etc.) via package manager
- Cannot rely on `apt-get` for anything — the command does not exist
- Must use one of:
  - Pre-built static binaries (e.g. yt-dlp, Himalaya via direct download)
  - Docker containers (the primary deployment mechanism on CasaOS/ZimaOS)
  - Manual shared-library placement (fragile, avoid if possible)

## Python setup pattern
`--user` pip install often fails because `~/.local` defaults to `/DATA/.local` which is root-owned. Always use explicit `PYTHONUSERBASE`:

```bash
PYTHONUSERBASE=/DATA/AppData/hermes/.local python3 get-pip.py --user
PYTHONUSERBASE=/DATA/AppData/hermes/.local /DATA/AppData/hermes/.local/bin/pip install <pkg>
```

## Docker access
Docker daemon is present (version 27.5.1) but user `az-a` is **not** in the `docker` group by default. Either:
1. `sudo usermod -aG docker az-a` (requires re-login)
2. Grant explicit sudo for `docker` command in sudoers

Without either, `docker ps` fails with:
```
permission denied while trying to connect to Docker daemon socket
```

## CasaOS app discovery
Apps are deployed under `/DATA/.casaos/apps/`. Container names are auto-generated (e.g. `adoring_elina`, `breathtaking_maryann`). List with:
```bash
ls /DATA/.casaos/apps/
```

## Multi-Drive Layout

ZimaOS on the user's system has at least two distinct storage locations:
- `/DATA/apps/…` — CasaOS application data (system SSD)
- `/DATA/.media/HDD_1TB/…` — large secondary HDD mounted for media and personal projects

**Rule of thumb:** Always search **both** locations before concluding a file does not exist.

## Sudoers notes
The user is in the `wheel` group, but `wheel` typically requires a password on this system. For passwordless sudo, either:
1. Add `Defaults:az-a !authenticate` to the specific sudoers drop-in
2. Or main `/etc/sudoers` must be edited with visudo (only root can do this)

## Common library gaps (that break Playwright Chromium)
Missing on a clean ZimaOS install:
- `libatk-1.0.so.0`
- `libatk-bridge-2.0`
- `libcups2`
- `libxcomposite`
- `libxdamage`
- `libxrandr2`
- `libasound2`

**Present:**
- `libdrm`, `libgbm`, `libnss3`, `libnspr4`

Therefore: Playwright's bundled Chromium **will always fail on ZimaOS** unless run inside a Docker container that provides the missing libraries.

## Recommended approach for browser automation
See `headless-browser-automation` skill. The Docker route is the only reliable path on ZimaOS.