CognitiveSystems Deployment

A pip-installable deployment app for the CognitiveSystems Docker stack.

cognitivesystems renders a docker-compose.yml + .env for each service from a catalog source (private, lsio, or a local custom overlay) plus an install profile that supplies machine-specific paths, network, ports, and timezone; it then drives docker compose. Catalog entries are source-qualified (source/name) and are fetched from their git sources rather than bundled in this package. Drive it from the web dashboard or the CLI. Rendering works on any OS; deploying needs Linux + Docker (run it on the server, or in WSL). See Catalog sources.

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 dashboard ships as a core dependency
sudo cognitivesystems                 # launch the dashboard; deploy actions need root

cognitivesystems (no subcommand) opens the web dashboard on 127.0.0.1:8800 — a browser GUI for the whole app (install/update/uninstall, live deploy log, Docker/network/host admin). cognitivesystems web is the explicit form. See docs/dashboard.md.

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 / 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
│   ├── 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, web API, variants, profiles, …)
└── docs/                  # install-guide, migration-guide, dashboard, services, networking, configuration, system-admin

Deployment modes

--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

The available services are dynamic: they come from your enabled catalog sources and are shown as source-qualified entries in the dashboard. Full details: docs/services.md · Catalog sources · Port model: docs/networking-and-ports.md

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