33 · Installation & upgrades

This chapter is the operator's reference for spinning up a fresh KW Group platform install or upgrading an existing one.

Fresh install

Run on a clean Ubuntu 22.04 / 24.04 host:

sudo bash /root/kw-portal/install.sh

The installer is interactive. It asks:

1. Install dir — default /opt.
2. Data dir — default /opt/data. Holds MariaDB, MinIO, Traefik certs.
3. Environment — prod (compiled bundles, ~300 MB RSS for the portal) or dev (live-reload, ~2 GB RSS).
4. Ingress — HTTP only / Let's Encrypt / Cloudflare Tunnel.
5. Domain — only when ingress is HTTPS-style.
6. Seed demo data? — yes/no. Defaults to yes; safe to re-run the seed later.

What it does, in order:

1. Installs Docker, Node 18, pnpm 9.
2. Copies /root/kw-portal/src/ → install dir, and creates the data-dir layout (mariadb/, redis/, minio/, traefik/).
3. Generates secrets — JWT_SECRET, SERVICE_SECRET, NEXTAUTH_SECRET, the MariaDB root + app passwords, and the MinIO access key + secret — and writes /opt/.env. It also patches the MariaDB passwords into infra/docker-compose.dev.yml.
4. Boots the infra containers (MariaDB, Redis, MinIO, NATS) and waits for MariaDB to be healthy.
5. pnpm install to fetch node_modules.
6. prisma db push (--accept-data-loss --skip-generate) to push the live schema, then prisma generate. (Migrations exist under packages/db/prisma/migrations/ for upgrade paths but a greenfield install uses push so ordering doesn't matter.)
7. Seeds if you said yes — 1 org + 4 users + KB articles + 3 ticket types with 16 statuses + 2 disabled helpdesk-rule examples + sample tickets/contacts/assets + 3 watchdog targets.
8. Builds auth-service, every Fastify service, and the portal — in prod mode only. (dev mode skips the pre-build and only builds auth-service, which is NestJS.)
9. Copies the start-all.sh / stop-all.sh / watchdog.sh templates into /opt/run/ and starts all services via /opt/run/start-all.sh.
10. Installs a 1-minute crontab watchdog so a dead service auto-restarts.
11. Wires Traefik or Cloudflared if you picked HTTPS / tunnel.
12. Writes /opt/passwords.md (chmod 600) with the seeded demo login and the generated infra secrets.

📷 Screenshot placeholder: screenshots/installer-prompts.png

When done, the demo login is admin@kwgroup.demo / demo-kwgroup-2026. Visit /admin/license to see the auto-issued trial.

What the seed gives you

After answering "yes" to the seed prompt, a fresh install has:

⚠️ Caution. The two seeded helpdesk-rule examples are disabled so a fresh install never sends an unintended customer email. Review the templated body, then toggle them on.

Upgrading an existing install

For an in-place upgrade against an existing /opt/:

1. Pull the latest source into /root/kw-portal/.
2. Sync changed source: rsync -a /root/kw-portal/src/ /opt/ (skip node_modules and .next/).
3. Run any new migrations:

   cd /opt/packages/db
   set -a && source /opt/.env && set +a
   for m in prisma/migrations/2026*; do
     docker exec -i kwgroup-dev-mariadb-1 mariadb \
       -ukwgroup -p"$DB_USER_PW" kwgroup_platform < "$m/migration.sql" || true
   done
   pnpm prisma generate
   

4. pnpm install to pick up new packages.
5. Rebuild affected services:

   for svc in helpdesk-service auth-service portal …; do
     pnpm --filter @kwg/$svc build
   done
   

6. Restart with /opt/run/start-all.sh — it kills whatever's on each port before relaunching.
7. Re-run the seed if you want new defaults: pnpm --filter @kwg/seed seed. It's idempotent.
8. From /admin/kb click 📥 Sync platform user guide to refresh the in-platform KB chapters.

Bringing the docs into the KB

The user-guide .md files live at /opt/docs/user-guide/. Click 📥 Sync platform user guide at /admin/kb to import them as KB articles under the Platform user guide category. See chapter 30.

File layout after install

/opt/                       # install root
├── .env                    # secrets + service URLs (chmod 600)
├── passwords.md            # generated secrets summary (chmod 600)
├── apps/                   # 21 backend services + portal + chat-widget
├── packages/               # shared libs (db, design-system, config, …)
├── infra/                  # docker-compose files
├── docs/
│   └── user-guide/         # this guide
├── scripts/
│   ├── bootstrap.sh        # dev bring-up helper
│   ├── migrate-tenant/     # tenant migration tool
│   └── seed/               # demo data seeder
└── run/
    ├── start-all.sh        # idempotent boot
    ├── stop-all.sh
    └── watchdog.sh         # 1-min cron tick

/opt/data/                  # persistent state — DB, uploads, certs
├── mariadb/
├── minio/
├── redis/
└── traefik/

See also

• Deployment — production hardening, backups
• Platform health — health checks + status page
• KB import — pulling docs into the in-platform KB
• Helpdesk rules — toggling on the seeded rule examples