94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# Build, Compilation & Testing Guide
|
|||
|
|
|
||
|
|
This guide outlines compilation commands, linter checks, test suite execution, and Docker container packaging.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Production Web Compilation
|
||
|
|
|
||
|
|
DataStack uses Next.js 15 App Router configured for **Standalone Output** (`output: "standalone"` in `next.config.ts`), which bundles only the required Node.js runtime files into `.next/standalone`.
|
||
|
|
|
||
|
|
### Compiling the Application:
|
||
|
|
```bash
|
||
|
|
npm run build
|
||
|
|
```
|
||
|
|
|
||
|
|
### Build Verification Checklist:
|
||
|
|
- Compiles TypeScript without type errors (`tsc --noEmit`).
|
||
|
|
- Generates serverless routes and static assets under `.next/`.
|
||
|
|
- Prepares standalone bundle under `.next/standalone/server.js`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Code Quality & Linting
|
||
|
|
|
||
|
|
DataStack uses ESLint 9 with `eslint-config-next`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run lint
|
||
|
|
```
|
||
|
|
|
||
|
|
Ensure this command exits cleanly (`code: 0`) with zero warnings or errors prior to committing code or opening a pull request.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Automated Test Suites
|
||
|
|
|
||
|
|
DataStack includes comprehensive, fast-executing automated test suites verifying security, synchronization, storage durability, PWA compliance, and deployment health.
|
||
|
|
|
||
|
|
### Running TypeScript Integration & Unit Tests
|
||
|
|
Run the test runner using `npx --yes tsx --test`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Run all core test suites
|
||
|
|
npx --yes tsx --test tests/phase01-auth.test.ts \
|
||
|
|
tests/phase02-sync.test.ts \
|
||
|
|
tests/phase03-storage-buffer.test.ts \
|
||
|
|
tests/phase06-pwa-landing.test.ts \
|
||
|
|
tests/phase07-deployment.test.ts
|
||
|
|
```
|
||
|
|
|
||
|
|
#### What These Tests Verify:
|
||
|
|
- **`phase01-auth.test.ts`**: Secret fail-closed checks, `tokenVersion` session invalidation, brute-force IP throttling, client token redaction, and CSRF Origin validation.
|
||
|
|
- **`phase02-sync.test.ts`**: Port 3000 ↔ Port 4000 internal secret authentication, settings propagation, instant client revocation, and JWT rotation disconnection.
|
||
|
|
- **`phase03-storage-buffer.test.ts`**: Redis AOF durability, distributed flush locking, cooperative partition `.lock` files, streaming row counting, and filtered CSV export.
|
||
|
|
- **`phase06-pwa-landing.test.ts`**: Web App Manifest validity, Service Worker registration, and navigation integrity.
|
||
|
|
- **`phase07-deployment.test.ts`**: Docker Compose configuration, Redis AOF persistence, Nginx `/health` proxying, deterministic lockfile parity, startup ownership checks, and unhydrated-DB auto-prune guards.
|
||
|
|
|
||
|
|
### Running Python SDK Unit Tests
|
||
|
|
```bash
|
||
|
|
python3 -m unittest tests/phase05_sdk_test.py
|
||
|
|
```
|
||
|
|
Verifies Python SDK WebSocket streaming, Heartbeat HTTP fallback, disk spooling (`.datastack_spool/`), and `.csv`/`.json` file streaming.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Docker Container Builds
|
||
|
|
|
||
|
|
To test production containerization locally:
|
||
|
|
|
||
|
|
### 1. Build the Web Container (Port 3000)
|
||
|
|
```bash
|
||
|
|
docker build -f docker/Dockerfile.web -t datastack-web:latest .
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Build the Ingestion Container (Port 4000)
|
||
|
|
```bash
|
||
|
|
docker build -f docker/Dockerfile.server -t datastack-ingestion:latest .
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Build the Nginx Proxy Container (Port 80)
|
||
|
|
```bash
|
||
|
|
docker build -f docker/Dockerfile.proxy -t datastack-proxy:latest .
|
||
|
|
```
|
||
|
|
|
||
|
|
### 4. Build & Run the Entire Stack with Compose
|
||
|
|
```bash
|
||
|
|
docker compose -f docker/docker-compose.yml build
|
||
|
|
docker compose -f docker/docker-compose.yml up -d
|
||
|
|
```
|
||
|
|
Verify container health with:
|
||
|
|
```bash
|
||
|
|
docker compose -f docker/docker-compose.yml ps
|
||
|
|
```
|
||
|
|
All containers (`web`, `ingestion`, `proxy`, `postgres`, `redis`) should display `(healthy)`.
|