# TraceBoard Suite

Congratulations on receiving the TraceBoard Suite! This package contains everything you need to deploy the full TraceBoard ecosystem: requirements management (TraceBoard), compliance document generation (TraceDocs), and test execution tracking (TraceTest).

## Package Contents

| File | Description |
|---|---|
| `docker-compose.yml` | Docker Compose configuration for all services |
| `traceboard`, `tracedocs`, `tracetest` images | Backend images pulled automatically from the registry by `docker compose up -d` |
| `suite-shell-dist/` | Pre-built frontend static files served by nginx |
| `.env.example` | Environment variable template (copy to `.env`) |
| `traceboard.license.sample` | Sample license file (for testing) |
| `user-manual.pdf` | User manual |
| `README.md` | This file |

## Quick Start

### 1. License

Place your license file named `traceboard.license` in this directory. Your TraceBoard representative will provide this file. The public key used to verify the license is baked into the backend image - no additional key files are required.

### 2. Load Docker Images (offline distribution)

If you received the **offline package**, load the bundled images into Docker
with the included helper script:

```bash
./load-images.sh        # Linux / macOS
```
```bat
load-images.bat         # Windows
```

(The helper runs `docker load -i` for every `*.tar` file in the folder.)

If your images are hosted on a registry, skip this step — `docker compose` will pull them automatically.

### 3. Start the Suite

First, configure your environment:

```bash
cp .env.example .env
# Edit .env: set JWT_SECRET_KEY, database passwords, and LLM keys
```

Then start the stack:

```bash
docker compose up -d
```

The suite will start in the background. PostgreSQL and Redis data is persisted in Docker volumes.

### 4. Access the Applications

The suite is served through a single entry point (nginx on port 80):

| Application | URL | Description |
|---|---|---|
| **TraceBoard** | http://localhost/board | Requirements management, baselines, test planning |
| **TraceDocs** | http://localhost/docs | Compliance document generation |
| **TraceTest** | http://localhost/test | Test execution tracking and coverage |

Default credentials (if applicable) are provided by your TraceBoard representative.

### 5. Stop the Suite

```bash
docker compose down
```

## Data Management

### Persistence

PostgreSQL data is stored in a Docker volume named `pgdata`. This volume persists across restarts.

### Backup

To back up the database:
```bash
docker compose exec db pg_dump -U traceboard traceboard > backup.sql
```

### Full Reset

To remove all data and start fresh:
```bash
docker compose down -v
```

## Configuration

Edit `docker-compose.yml` to customize the deployment. Key environment variables:

### Database
| Variable | Default | Description |
|---|---|---|
| `POSTGRES_USER` | `traceboard` | PostgreSQL user |
| `POSTGRES_PASSWORD` | `traceboard` | PostgreSQL password |
| `POSTGRES_DB` | `traceboard` | Database name |

### Security
| Variable | Default | Description |
|---|---|---|
| `JWT_SECRET_KEY` | (auto-generated) | Secret key for JWT tokens |

### LLM Integration (TraceDocs AI features)
| Variable | Default | Description |
|---|---|---|
| `LLM_API_URL` | — | LLM API endpoint (e.g., `https://api.mistral.ai/v1`) |
| `LLM_API_KEY` | — | API key for LLM service |
| `LLM_MODEL` | — | Model name (e.g., `ministral-14b-2512`) |

### Applying Changes

After editing `docker-compose.yml`:
```bash
docker compose up -d
```

## Troubleshooting

### Ports already in use

If ports 8000, 8001, 8002, or 5432 are already in use, edit the `ports:` section in `docker-compose.yml`. For example, to map TraceBoard to port 9000:
```yaml
ports:
  - "9000:8000"
```

### Database connection errors

Ensure the database service is healthy:
```bash
docker compose ps db
```

Wait for the health check to show `healthy`, then restart the backends:
```bash
docker compose restart traceboard-backend tracedocs-backend tracetest-backend
```

### License validation errors

- Verify `traceboard.license` exists in the same directory as `docker-compose.yml`.
- Ensure the license file is valid JSON with a correct RSA signature.

## Upgrading

To upgrade to a new version:

1. Stop the running suite: `docker compose down`
2. Back up your data (see Backup above).
3. Extract the new release package.
4. Load new Docker images: `docker load -i traceboard-*.tar`
5. Copy your `traceboard.license` into the new directory.
6. Start: `docker compose up -d`

The database volume (`pgdata`) will be reused automatically.

## System Requirements

| Resource | Minimum | Recommended |
|---|---|---|
| Docker Engine | 20.10+ | 24.0+ |
| Docker Compose | v2 | v2 |
| RAM | 4 GB | 8 GB |
| Disk | 10 GB | 20 GB |
| CPU | 2 cores | 4 cores |

## Support

For support, contact your TraceBoard representative or refer to the documentation included with your license.

## Rebuilding this package (vendor only)

Customers do **not** need to build anything — this folder is the finished delivery
package. Maintainers can regenerate both customer ZIPs from the monorepo with:

```bash
# Windows (PowerShell) — run from delivery-package/
.\build-delivery-package.ps1                     # online  -> delivery-package-online.zip
.\build-delivery-package.ps1 -Offline            # offline -> delivery-package-offline.zip
.\build-delivery-package.ps1 -Offline -Version 1.1.1

# Linux / macOS
./build-delivery-package.sh                      # online  -> delivery-package-online.zip
./build-delivery-package.sh --offline            # offline -> delivery-package-offline.zip
./build-delivery-package.sh -v 1.1.1
```

The script:

1. Runs `pnpm install` at the monorepo root (this is a pnpm workspace; the
   suite-shell app lives at `apps/suite-shell` and depends on the
   `@traceboard-suite/*` workspace packages).
2. Builds the frontend with `pnpm build --filter ./apps/suite-shell`
   (Vite output: `apps/suite-shell/dist/`).
3. Copies the build **contents** into `suite-shell-dist/` (overwriting).
4. Verifies `index.html` + `assets/` are present.
5. **Online** creates `delivery-package-online.zip` (repo root) containing
   `docker-compose.yml`, `nginx.conf`, `.env.example`,
   `traceboard.license.sample`, `README.md`, `user-manual.pdf` and
   `suite-shell-dist/`. Images are pulled from the registry, so no `.tar`
   files are included. The `docker-compose.yml` is the **transformed** compose
   from `release/traceboard-suite-<version>/` (registry-prefixed image tags
   such as `ghcr.io/.../traceboard:<version>`), so `docker compose up -d`
   pulls the backend images from the registry. Pass `-Version <version>` (or
   `-v <version>`) so the script knows which release folder to use.
6. **Offline** (`-Offline` / `--offline`) additionally builds
   `delivery-package-offline/` and creates `delivery-package-offline.zip`
   (repo root) containing the same files **plus** the `traceboard-*.tar`,
   `tracedocs-*.tar` and `tracetest-*.tar` image archives, the
   `load-images.sh` / `load-images.bat` one-command loaders and a
   `README-OFFLINE.md`. Its `docker-compose.yml` is the **local-tag transform**
   from `release/traceboard-suite-<version>/docker-compose.local.yml` (tags such
   as `traceboard:<version>`) so the tags match what the loader scripts load from
   the bundled `.tar` files. The `.tar` files are
   copied from `release/traceboard-suite-<version>/` (created by `release.ps1` /
   `release.sh`); if they are missing there, the script falls back to
   `docker save` of the locally tagged images.

Backend images are otherwise not shipped as `.tar` files — `docker compose up
-d` pulls them from the registry. `traceboard.license.sample` is created
automatically if missing.
