Deployment

This section covers deployment and hosting configuration for the Z8 Team Management System.

Overview

Z8 consists of multiple runtime roles and supporting applications. For operators, the important distinction is less about the repo layout and more about which process owns which responsibility.

Runtime Roles

Typical production deployments include:

• one or more web app instances serving the main product
• at least one worker instance connected to the same database, object storage, and Valkey/Redis infrastructure
• a one-shot migration run during deploys before new web or worker pods take traffic
• optional seed/bootstrap execution when an environment needs baseline data

The repository supports these roles with dedicated Dockerfiles: docker/Dockerfile.webapp, docker/Dockerfile.worker, docker/Dockerfile.migration, and docker/Dockerfile.db-seed.

Workspace Commands

Common build commands from the repo root use pnpm:

pnpm --filter webapp build
pnpm --filter docs build
pnpm build:docs

Desktop packaging uses the desktop workspace directly:

pnpm --dir apps/desktop run build
pnpm --dir apps/desktop run tauri build

Environment Variables

The web app requires environment-backed system configuration for:

• PostgreSQL connectivity
• Better Auth secrets and base URL behavior
• S3-compatible object storage
• Valkey/Redis queue infrastructure
• optional billing, email, bot protection, and other platform services

Organization-specific credentials should be entered through organization settings. System secrets remain environment-backed.

Web Application

Docker Deployment

Build the web app image from the explicit Dockerfile:

docker build -f docker/Dockerfile.webapp -t z8-webapp:latest .
docker run -p 3000:3000 z8-webapp:latest

Database And Migrations

Z8 uses PostgreSQL with Drizzle ORM. Auth/schema generation and migrations use pnpm:

pnpm --dir apps/webapp run auth:migrate

If you need baseline seed data after migrations:

pnpm --dir apps/webapp run db:seed

One-shot operational images are built separately:

docker build -f docker/Dockerfile.migration -t z8-migration:latest .
docker build -f docker/Dockerfile.db-seed -t z8-db-seed:latest .

Storage

S3-compatible object storage is required for file uploads, generated exports, and attachments.

S3_BUCKET=your-bucket
S3_REGION=eu-central-1
S3_ACCESS_KEY_ID=<access-key>
S3_SECRET_ACCESS_KEY=<secret-key>
S3_ENDPOINT=https://s3.amazonaws.com
S3_PUBLIC_URL=https://cdn.your-domain.com

S3_PUBLIC_URL should resolve to the public base URL used when the app needs to serve or reference stored assets. For local development and some self-hosted setups, Z8 can target compatible providers such as RustFS, MinIO, R2, or similar S3-compatible services.

Queue Infrastructure

Z8 uses Valkey/Redis-compatible infrastructure for:

• BullMQ worker queues
• retries for exports and webhooks
• rate limiting
• selected realtime coordination paths

VALKEY_HOST=localhost
VALKEY_PORT=6379
VALKEY_PASSWORD=<optional-password>

Worker Process Deployment

For background job processing, deploy a separate worker process. The worker runs BullMQ jobs and repeatable cron-style jobs, so it should be treated as a first-class runtime, not an optional sidecar.

Worker Configuration

Example local command:

pnpm --dir apps/webapp exec tsx src/worker.ts

Important worker inputs include:

• VALKEY_HOST, VALKEY_PORT, and optional VALKEY_PASSWORD
• WORKER_CONCURRENCY
• ENABLE_CRON_JOBS
• the same database and storage configuration used by the web app

Docker Compose Shape

services:
  webapp:
    build:
      context: .
      dockerfile: docker/Dockerfile.webapp

  worker:
    build:
      context: .
      dockerfile: docker/Dockerfile.worker

  migration:
    build:
      context: .
      dockerfile: docker/Dockerfile.migration

Scheduled Work

Scheduled work is registered in the worker and executed through BullMQ repeatable jobs. Common responsibilities include:

Desktop App Distribution

The desktop app is a distributed Tauri client rather than a server runtime. Build it separately from the web deployment pipeline and publish platform installers as needed.

Monitoring

Production monitoring should cover:

• web health and readiness
• worker health and queue depth
• database connectivity and migration status
• object-storage availability
• webhook and export failure rates

Additional Resources

• Technical Docs - Development setup and architecture
• Admin Guide - Product configuration after deployment