Metadata-Version: 2.4
Name: cognitivesystems
Version: 0.0.10
Summary: Catalog-driven Docker homeserver deployer: per-service compose renderer + terminal UI.
Project-URL: Homepage, https://github.com/automationnexus/CognitiveSystems
Project-URL: Source, https://github.com/automationnexus/CognitiveSystems
Author: Tahasanul Abraham
License-Expression: MIT
Keywords: compose,deploy,docker,homeserver,self-hosted
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.9
Requires-Dist: pyyaml>=6
Requires-Dist: textual>=0.60
Provides-Extra: dev
Requires-Dist: httpx>=0.26; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: web
Requires-Dist: docker<8,>=7; extra == 'web'
Requires-Dist: fastapi>=0.115; extra == 'web'
Requires-Dist: itsdangerous>=2.2; extra == 'web'
Requires-Dist: pydantic>=2; extra == 'web'
Requires-Dist: python-multipart>=0.0.9; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'web'
Description-Content-Type: text/markdown

# CognitiveSystems Deployment

A pip-installable deployment app for the CognitiveSystems Docker stack.
One package, 42 services — no per-service `git clone` at deploy time.

`cognitivesystems` renders a `docker-compose.yml` + `.env` for each service from
per-service definitions (`services/<name>/service.yml`) plus an **install profile**
that supplies the values specific to your machine (paths, network, ports, timezone),
then drives `docker compose`. Drive it from the **web dashboard**, the **terminal UI**,
or the CLI. Rendering works on any OS; **deploying needs Linux + Docker** (run it on the
server, or in WSL).

---

## Install

```bash
pip install cognitivesystems          # from PyPI
# or, from a clone (for development):
git clone https://github.com/automationnexus/CognitiveSystems.git
cd CognitiveSystems && pip install -e .
```

Requires **Python 3.9+**; deploying additionally needs **Docker + compose v2** on a
Linux host (the app checks and tells you what's missing).

---

## Quick start

```bash
pip install "cognitivesystems[web]"   # include the web dashboard (optional extra)
sudo cognitivesystems                 # launch the dashboard (or the TUI); deploy actions need root
```

With the `[web]` extra, `cognitivesystems` opens the **web dashboard** on `127.0.0.1:8800` — a
browser GUI that does everything the TUI does. Disable the dashboard with `dashboard.enabled: false` in
`state.json` to get the **terminal UI** instead (or run `cognitivesystems tui`). See [docs/dashboard.md](docs/dashboard.md).

The TUI lists every service (`✓` = installed) with a live deploy-log pane. Keys:
**`i`** install · **`u`** update · **`x`** uninstall · **`c`** configure · **`s`** service ·
**`g`** config · **`k`** secrets · **`d`** docker · **`n`** network · **`a`** apps · **`h`** host ·
**`r`** refresh · **`q`** quit (arrows/mouse to select). Great over SSH on the server.

Or use the CLI:

```bash
# 1. pick an install profile (system-specific paths/network/ports/timezone)
cognitivesystems init --profile homeserver   # NFS-backed homeserver (default)
cognitivesystems init --profile localdev     # laptop / VM

# 2. set credentials (prompt; Enter = auto-generate a strong value). No defaults ship.
cognitivesystems configure                   # mode/domain + admin password, LE email,
                                              # Cloudflare DNS token, per-service overrides

# 3. install services (Linux + Docker; needs root for docker/chown)
sudo cognitivesystems install traefik portainer plex uploadarr \
    --mode public --domain example.com --auto-update --wildcard

# 4. update / list / uninstall
sudo cognitivesystems update                  # all installed
sudo cognitivesystems update traefik plex     # specific services
cognitivesystems list                         # catalog (* = installed)
sudo cognitivesystems uninstall plex          # remove service + working dir
sudo cognitivesystems uninstall plex --purge  # also delete the data dir
```

`homeserver` expects two NFS mounts to exist first — `/home/data` and
`/mnt/homeserver`. See [docs/services.md](docs/services.md#install-profiles) for the
mount layout and `localdev` caveats. Re-run `init --profile <name>` to switch profiles.

### Reinstall an existing service

```bash
sudo cognitivesystems install plex --force          # uninstall then install (keeps data dir)
sudo cognitivesystems install plex --force --purge  # same, but also drops the data dir
```

Without `--force`, installing an already-installed service is a no-op.

### Render only (any OS)

```bash
cognitivesystems render plex --out ./out      # write docker-compose.yml + .env, no deploy
```

### OS administration (Linux)

```bash
sudo cognitivesystems system ssh-keygen --bits=8192 --install-to=admin,operator
sudo cognitivesystems system change-password --target=root --password='…' --enable-root-ssh
sudo cognitivesystems system media-user create
```

See [docs/system-admin.md](docs/system-admin.md).

---

## Repository layout

```
.
├── pyproject.toml         # package metadata (hatchling); entry point `cognitivesystems`
├── frontend/              # React + Vite dashboard SPA (built into the wheel at package time)
├── src/cognitivesystems/  # the app
│   ├── cli.py             # CLI: list / render / init / install / update / uninstall / system / tui / web
│   ├── render.py          # renderer: catalog + state -> docker-compose.yml + .env
│   ├── catalog.py state.py config.py deploy.py hooks.py system.py
│   ├── core/              # shared capability registry, job runner, Docker client, per-area ops
│   ├── tui/               # Textual terminal UI (app + per-area screens)
│   ├── web/               # FastAPI dashboard backend (serves the built SPA + JSON/WS API)
│   └── data/              # catalog bundled into the wheel (services + profiles)
├── services/
│   ├── install_order.yml  # infra precedence (db/proxy come up first)
│   └── <name>/
│       ├── service.yml    # one service definition per folder
│       └── sidecars/      # optional static files (e.g. the qbittorrent webhook script)
├── profiles/              # install profiles: homeserver.yml, localdev.yml
├── tests/                 # pytest (render parity, GUI⇄TUI parity, variants, profiles, …)
└── docs/                  # install-guide, migration-guide, dashboard, services, networking, configuration, system-admin
```

---

## Deployment modes

| Mode | Flag | TLS | Use case |
|---|---|---|---|
| Public | `--mode public` | Let's Encrypt TLS-ALPN-01, one cert per subdomain | Internet-facing server |
| Public + Wildcard | `--mode public --wildcard` | Cloudflare DNS-01, single `*.<domain>` cert | Internet-facing, one cert for all |
| Private | `--mode private` | None | LAN access via IP or hostname |
| Local | `--mode local` | None | Single machine, `localhost` only |

`--wildcard` needs `--cf-token` (a scoped Cloudflare DNS-edit API token). Healthchecks
are not configured by the installer; use each image's built-in `HEALTHCHECK` if needed.

---

## Automatic install ordering

You never order services manually — infra installs first, in a fixed order:
`traefik → mariadb → mysql → mongodb → mqtt-broker`. Everything else follows.

---

## State & profile

Persisted under `/home/installation_cognitivesystems/state.json` (override with
`CS_STATE_DIR`):

- **Runtime config** — mode, domain, passwords, installed services. Saved as you install.
- **`.site`** — the system-specific values from your chosen install profile.

Re-running `update` re-renders every installed service from saved state. To change
domain / passwords / TLS mode: edit `state.json`, then `update`. To change profile
values (paths, ports, network): edit `profiles/<name>.yml` and re-run `init`.
See [docs/configuration.md](docs/configuration.md) for the schema.

### Host file layout after install (homeserver defaults)

```
~/cognitivesystems/state/state.json              # default state file (--state to override)
/home/<service>/{docker-compose.yml,.env}         # per-service working dir (install_root)
/home/data/<ServiceDisplayName>/                  # persistent app data (config_root)
```

Data directories are never removed by `uninstall`; pass `--purge` to delete them too.
Paths resolve from `state.json` `.site.paths` after `init --profile <name>`.

---

## Services

42 services. Full details: [docs/services.md](docs/services.md) · Port model: [docs/networking-and-ports.md](docs/networking-and-ports.md)

| Category | Services |
|---|---|
| Core infra | Traefik, Portainer, WatchTower, WG-Easy, CrontabUI |
| Databases | MariaDB, MySQL, MongoDB, MQTT-Broker |
| Media | Plex, Radarr, Sonarr, Prowlarr, Jackett, Bazarr, Tautulli, Stash, Whisparr, Threadfin, Seerr |
| Download | Qbittorrent, CrossSeed, Autobrr, Rarrnomore, FlareSolverr, Byparr |
| Files / Comms | SFTPGo, SnappyMail, Stalwart, Vaultwarden, Paperless |
| Dev / Tools | Code-Server, OpenWebUI, Profilarr, Maintainerr, Heimdall, Wizarr, AdGuard, BetterDesk, Firefox, Chrome |
| Custom | Uploadarr |

---

## Contributing

Development happens on the `dev` branch, which carries the developer documentation
(architecture, catalog reference, how to add a service, the test framework):

→ [DEVELOPMENT.md on the `dev` branch](https://github.com/automationnexus/CognitiveSystems/blob/dev/DEVELOPMENT.md)

<!-- dev-ci-verify -->

<!-- nightly-e2e-verify -->

<!-- final-nightly-verify -->
