cognitivesystems 0.0.3

Catalog-driven Docker homeserver deployer: per-service compose renderer + terminal UI.

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

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

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.

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:

# 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 for the mount layout and localdev caveats. Re-run init --profile <name> to switch profiles.

Reinstall an existing service

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)

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

OS administration (Linux)

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.

---

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 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 · Port model: 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