Skip to content

Commit 50643d4

Browse files
dev-damidev-dami
committed
docs: sync docs with v0.7.1 features and fix table styling
- Update all docs with audit-output, preflight config features - Fix table checkerboard effect by setting consistent background - Sync README with latest feature set
1 parent fd127df commit 50643d4

File tree

7 files changed

+257
-47
lines changed

7 files changed

+257
-47
lines changed

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,13 @@ Ignite runs JavaScript/TypeScript code in **secure, isolated Docker containers**
5151

5252
| Metric | Value |
5353
|--------|-------|
54-
| **Runtimes** | Bun, Node |
54+
| **Runtimes** | Bun (default), Node, Deno, QuickJS |
5555
| **Base Images** | Alpine (minimal) |
5656
| **Platforms** | Linux x64/ARM64, macOS x64/ARM64 |
5757
| **Dependencies** | Docker only |
5858

59+
Note: Bun is the default runtime. Other runtimes are supported but increase the security attack surface; use them only when required and review service code and dependencies carefully.
60+
5961
<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="rainbow" width="100%">
6062

6163
## Install

‎docs/api.md‎

Lines changed: 206 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Complete reference for Ignite CLI commands and HTTP API endpoints.
1010
- [ignite preflight](#ignite-preflight)
1111
- [ignite serve](#ignite-serve)
1212
- [ignite report](#ignite-report)
13+
- [ignite lock](#ignite-lock)
14+
- [ignite env](#ignite-env)
1315
- [HTTP API](#http-api)
1416
- [Health Check](#get-health)
1517
- [List Services](#get-services)
@@ -41,17 +43,26 @@ ignite init <name> [options]
4143

4244
| Option | Default | Description |
4345
|--------|---------|-------------|
44-
| `--runtime <runtime>` | `bun` | Runtime: `bun` or `node` |
45-
| `--template <template>` | `default` | Template to use |
46+
| `--runtime <runtime>` | `bun` | Runtime: `bun`, `node`, `deno`, `quickjs` (with optional version: `bun@1.2`) |
47+
| `--path <path>` | `./<name>` | Custom path for the service directory |
4648

4749
**Examples:**
4850

4951
```bash
50-
# Create Bun service
52+
# Create Bun service (default)
5153
ignite init my-service
5254

5355
# Create Node.js service
5456
ignite init my-service --runtime node
57+
58+
# Create with specific version
59+
ignite init my-service --runtime node@20
60+
61+
# Create Deno service
62+
ignite init my-service --runtime deno
63+
64+
# Create QuickJS service (fast cold start)
65+
ignite init my-service --runtime quickjs
5566
```
5667

5768
**Generated Files:**
@@ -84,9 +95,11 @@ ignite run <path> [options]
8495
| Option | Default | Description |
8596
|--------|---------|-------------|
8697
| `--input <json>` | `{}` | Input data as JSON string |
98+
| `--runtime <runtime>` | (from service.yaml) | Override runtime (e.g., `node@20`, `bun@1.2`) |
8799
| `--skip-preflight` | `false` | Skip safety checks |
88100
| `--json` | `false` | Output results as JSON |
89101
| `--audit` | `false` | Run with security audit (blocks network, read-only filesystem) |
102+
| `--audit-output <file>` | - | Write security audit to a JSON file |
90103

91104
**Examples:**
92105

@@ -97,6 +110,9 @@ ignite run ./my-service
97110
# With input data
98111
ignite run ./my-service --input '{"name": "World"}'
99112

113+
# Override runtime version
114+
ignite run ./my-service --runtime node@22
115+
100116
# Skip preflight (development only)
101117
ignite run ./my-service --skip-preflight
102118

@@ -136,6 +152,8 @@ Filesystem
136152
✗ Security Status: 2 VIOLATION(S) BLOCKED
137153
```
138154

155+
When `--json` is used with `--audit`, the JSON output includes a `securityAudit` field.
156+
139157
**Output:**
140158

141159
```
@@ -271,6 +289,141 @@ ignite report ./my-service --format json --output report.json
271289

272290
---
273291

292+
### ignite lock
293+
294+
Create or update environment manifest (`ignite.lock`) for reproducible builds.
295+
296+
```bash
297+
ignite lock <path> [options]
298+
```
299+
300+
**Arguments:**
301+
302+
| Argument | Description |
303+
|----------|-------------|
304+
| `path` | Path to service directory |
305+
306+
**Options:**
307+
308+
| Option | Default | Description |
309+
|--------|---------|-------------|
310+
| `--update` | `false` | Update existing manifest |
311+
| `--check` | `false` | Check for drift without modifying |
312+
313+
**Examples:**
314+
315+
```bash
316+
# Create ignite.lock
317+
ignite lock ./my-service
318+
319+
# Update existing manifest
320+
ignite lock ./my-service --update
321+
322+
# Check for environment drift (CI/CD)
323+
ignite lock ./my-service --check
324+
```
325+
326+
**Generated File (`ignite.lock`):**
327+
328+
```yaml
329+
version: "1.0"
330+
runtime:
331+
name: bun
332+
version: "1.3"
333+
lockfile: bun.lockb
334+
checksums:
335+
package.json: sha256:abc123...
336+
bun.lockb: sha256:def456...
337+
createdAt: "2024-01-15T10:30:00.000Z"
338+
```
339+
340+
**Exit Codes:**
341+
342+
| Code | Meaning |
343+
|------|---------|
344+
| 0 | Success / No drift detected |
345+
| 1 | Drift detected (with `--check`) |
346+
347+
---
348+
349+
### ignite env
350+
351+
Display environment information and available runtimes.
352+
353+
```bash
354+
ignite env [path] [options]
355+
```
356+
357+
**Arguments:**
358+
359+
| Argument | Description |
360+
|----------|-------------|
361+
| `path` | Path to service directory (optional) |
362+
363+
**Options:**
364+
365+
| Option | Default | Description |
366+
|--------|---------|-------------|
367+
| `--runtimes` | `false` | List all supported runtimes |
368+
369+
**Examples:**
370+
371+
```bash
372+
# Show service environment info
373+
ignite env ./my-service
374+
375+
# List all available runtimes
376+
ignite env --runtimes
377+
```
378+
379+
**Output (service info):**
380+
381+
```
382+
Service: my-service
383+
Runtime: bun@1.3
384+
385+
Environment: Locked
386+
Runtime: bun@1.3
387+
Locked at: 2024-01-15T10:30:00.000Z
388+
Lockfile: bun.lockb
389+
390+
✓ Environment matches manifest
391+
```
392+
393+
**Output (runtimes list):**
394+
395+
```
396+
Supported Runtimes:
397+
398+
bun
399+
Default entry: index.ts
400+
Extensions: .ts, .js, .tsx, .jsx
401+
Versions: 1.0, 1.1, 1.2, 1.3 (default: 1.3)
402+
403+
node
404+
Default entry: index.js
405+
Extensions: .js, .mjs, .cjs
406+
Versions: 18, 20, 22 (default: 20)
407+
408+
deno
409+
Default entry: index.ts
410+
Extensions: .ts, .js, .tsx, .jsx
411+
Versions: 1.40, 1.41, 1.42, 2.0 (default: 2.0)
412+
413+
quickjs
414+
Default entry: index.js
415+
Extensions: .js
416+
Versions: latest (default: latest)
417+
418+
Usage examples:
419+
service.yaml: runtime: bun
420+
service.yaml: runtime: bun@1.2
421+
service.yaml: runtime: node@20
422+
ignite run . --runtime node@22
423+
```
424+
425+
---
426+
274427
## HTTP API
275428
276429
Base URL: `http://localhost:3000` (default)
@@ -424,14 +577,17 @@ Execute a service.
424577
"data": [1, 2, 3],
425578
"operation": "sum"
426579
},
427-
"skipPreflight": false
580+
"skipPreflight": false,
581+
"audit": true
428582
}
429583
```
430584

431585
| Field | Type | Required | Description |
432586
|-------|------|----------|-------------|
433587
| `input` | object | No | Input data passed to service |
434588
| `skipPreflight` | boolean | No | Skip safety checks |
589+
| `skipBuild` | boolean | No | Skip image build if already built |
590+
| `audit` | boolean | No | Run with security audit |
435591

436592
**Response:**
437593

@@ -447,6 +603,8 @@ Execute a service.
447603
}
448604
```
449605

606+
When `audit` is true, the response includes `securityAudit`.
607+
450608
**Errors:**
451609

452610
| Status | Description |
@@ -477,24 +635,66 @@ Execute a service.
477635
service:
478636
# Required fields
479637
name: string # Service identifier (alphanumeric, hyphens)
480-
runtime: string # "bun" or "node"
638+
runtime: string # Runtime with optional version (see below)
481639
entry: string # Entry file path
482640

483641
# Optional fields
484642
memoryMb: number # Memory limit (default: 128)
643+
cpuLimit: number # CPU limit in cores (default: 1)
485644
timeoutMs: number # Timeout (default: 30000)
486645
env: object # Environment variables
487646
dependencies: array # Explicit dependencies (auto-detected by default)
647+
648+
preflight:
649+
memory:
650+
baseMb: number # Base memory estimate (default: 50)
651+
perDependencyMb: number # Memory per dependency (default: 2)
652+
warnRatio: number # Warning threshold ratio (default: 1)
653+
failRatio: number # Failure threshold ratio (default: 0.8)
654+
dependencies:
655+
warnCount: number # Warn if dependency count exceeds (default: 100)
656+
infoCount: number # Info threshold for moderate count (default: 50)
657+
image:
658+
warnMb: number # Image size warn threshold (default: 500)
659+
failMb: number # Image size fail threshold (default: 1000)
660+
timeout:
661+
minMs: number # Minimum timeout (default: 100)
662+
maxMs: number # Maximum recommended timeout (default: 30000)
663+
coldStartBufferMs: number # Cold start buffer (default: 500)
664+
```
665+
666+
**Supported Runtimes:**
667+
668+
| Runtime | Versions | Default Entry | Notes |
669+
|---------|----------|---------------|-------|
670+
| `bun` | 1.0, 1.1, 1.2, 1.3 | index.ts | TypeScript native, fastest |
671+
| `node` | 18, 20, 22 | index.js | Node.js compatibility |
672+
| `deno` | 1.40, 1.41, 1.42, 2.0 | index.ts | Secure by default |
673+
| `quickjs` | latest | index.js | Ultra-fast cold start (~10ms) |
674+
675+
Security note: Bun is the default runtime. Using other runtimes increases the attack surface; only use them when required and keep runtime versions pinned.
676+
677+
**Runtime Version Syntax:**
678+
679+
```yaml
680+
# Use default version
681+
runtime: bun
682+
683+
# Specify version
684+
runtime: bun@1.2
685+
runtime: node@20
686+
runtime: deno@2.0
488687
```
489688

490689
**Full Example:**
491690

492691
```yaml
493692
service:
494693
name: my-service
495-
runtime: bun
694+
runtime: bun@1.3
496695
entry: index.ts
497696
memoryMb: 256
697+
cpuLimit: 0.5
498698
timeoutMs: 60000
499699
env:
500700
NODE_ENV: production
@@ -524,20 +724,9 @@ Create an `ignite.policy.yaml` file to customize security settings:
524724
security:
525725
network:
526726
enabled: false # Block all network (default)
527-
allowedHosts: # Optional: allow specific hosts
528-
- api.example.com
529-
allowedPorts: # Optional: allow specific ports
530-
- 443
531727
532728
filesystem:
533729
readOnly: true # Read-only root filesystem
534-
allowedWritePaths: # Paths that can be written to
535-
- /tmp
536-
blockedReadPaths: # Paths blocked from reading
537-
- /etc/passwd
538-
- /etc/shadow
539-
- /proc
540-
- /sys
541730
542731
process:
543732
allowSpawn: false # Block spawning child processes

0 commit comments

Comments
 (0)