Skip to content

Commit 5b67c84

Browse files
dash14dash14
committed
Move Development section from README to docs/development.md
1 parent c101a57 commit 5b67c84

File tree

2 files changed

+119
-111
lines changed

2 files changed

+119
-111
lines changed

‎README.md‎

Lines changed: 1 addition & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -496,117 +496,7 @@ If you encounter issues, try reproducing the problem locally to get detailed log
496496

497497
## Development
498498

499-
### Testing
500-
501-
```bash
502-
# Audit mode test (start → build → verify → clean up)
503-
make test_audit_mode
504-
505-
# Restrict mode test (start → build → verify → clean up)
506-
make test_restrict_mode
507-
```
508-
509-
### Viewing Logs
510-
511-
```bash
512-
# All communication logs
513-
docker compose logs builder
514-
515-
# Real-time log monitoring
516-
docker compose logs -f builder
517-
```
518-
519-
**Log format:**
520-
521-
```
522-
[28/Jan/2026:10:15:30 +0000] [ALLOWED] TCP 200 1234 5678 0.123 "github.com:443"
523-
[28/Jan/2026:10:15:31 +0000] [BLOCKED] TCP 502 0 0 0.001 "malicious.com:443"
524-
[28/Jan/2026:10:15:32 +0000] [AUDIT] HTTP 200 2345 6789 0.234 "npmjs.org:80"
525-
```
526-
527-
Fields: `[timestamp] [status] protocol http_status bytes_sent bytes_received duration "domain:port"`
528-
529-
### Makefile Commands
530-
531-
| Command | Description |
532-
|---------|-------------|
533-
| `make help` | Show available commands |
534-
| `make run_audit_mode` | Start in audit mode |
535-
| `make run_restrict_mode` | Start in restrict mode (default domains) |
536-
| `make test_audit_mode` | Run audit mode tests (start → build → verify → clean up) |
537-
| `make test_restrict_mode` | Run restrict mode tests (start → build → verify → clean up) |
538-
| `make clean` | Remove all resources |
539-
540-
### Directory Structure
541-
542-
```
543-
.
544-
├── setup/
545-
│ ├── action.yml # GitHub Action: dash14/buildcage/setup@v1
546-
│ └── compose.yml # Compose config for GitHub Actions (with image tag)
547-
├── report/
548-
│ ├── action.yml # GitHub Action: dash14/buildcage/report@v1
549-
│ └── main.mjs # Log analysis and Job Summary output
550-
├── compose.yml # Docker Compose config
551-
├── compose.test.yml # Test override config
552-
├── Makefile # Operational commands
553-
├── docker/
554-
│ ├── Dockerfile # Multi-stage BuildKit + nginx + dnsmasq
555-
│ └── files/ # Builder container config files
556-
│ ├── entrypoint.sh # iptables/dnsmasq/nginx/buildkitd startup
557-
│ ├── buildkitd.toml # BuildKit config
558-
│ ├── cni.conflist # CNI config (isolated-net)
559-
│ ├── dnsmasq.conf # DNS config (all domains → gateway)
560-
│ └── nginx.conf.template # Dynamic nginx config (HTTP/HTTPS)
561-
└── test/
562-
├── Dockerfile.audit # Audit mode test
563-
├── Dockerfile.restrict # Restrict mode test
564-
├── assert-audit-mode.sh # Audit mode verification script
565-
├── assert-restrict-mode.sh # Restrict mode verification script
566-
├── helpers.sh # Test helpers
567-
├── test-server/ # Test HTTP server
568-
└── test-dns/ # Test DNS server
569-
```
570-
571-
### Local Usage (without GitHub Actions)
572-
573-
GitHub Actions inputs use lowercase names (e.g., `proxy_mode`), while environment variables for local/Docker Compose usage use uppercase (e.g., `PROXY_MODE`).
574-
575-
#### Starting the Builder
576-
577-
**Audit mode** (log all connections):
578-
579-
```bash
580-
make run_audit_mode
581-
```
582-
583-
**Restrict mode** (allowlist-based):
584-
585-
```bash
586-
make run_restrict_mode
587-
```
588-
589-
**Start with custom domains**:
590-
591-
```bash
592-
ALLOWED_HTTPS_DOMAINS="github.com,npmjs.org,example.com" make run_restrict_mode
593-
```
594-
595-
#### End-to-End Local Workflow
596-
597-
```bash
598-
# 1. Start buildcage
599-
make run_audit_mode
600-
601-
# 2. Build
602-
docker buildx build --builder buildcage --progress=plain -f Dockerfile .
603-
604-
# 3. View report
605-
docker compose logs builder
606-
607-
# 4. Clean up
608-
make clean
609-
```
499+
See the [Development Guide](./docs/development.md) for local usage, testing, viewing logs, and directory structure.
610500

611501
## Contributing
612502

‎docs/development.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Development Guide
2+
3+
This document covers local development, testing, and the project structure of buildcage.
4+
5+
## Local Usage
6+
7+
You can run buildcage locally without GitHub Actions using Docker Compose and Make.
8+
9+
> GitHub Actions inputs use lowercase names (e.g., `proxy_mode`), while environment variables for local usage use uppercase (e.g., `PROXY_MODE`).
10+
11+
### Starting the Builder
12+
13+
**Audit mode** (log all connections):
14+
15+
```bash
16+
make run_audit_mode
17+
```
18+
19+
**Restrict mode** (allowlist-based):
20+
21+
```bash
22+
make run_restrict_mode
23+
```
24+
25+
**Start with custom domains**:
26+
27+
```bash
28+
ALLOWED_HTTPS_DOMAINS="github.com,npmjs.org,example.com" make run_restrict_mode
29+
```
30+
31+
### End-to-End Workflow
32+
33+
```bash
34+
# 1. Start buildcage
35+
make run_audit_mode
36+
37+
# 2. Build
38+
docker buildx build --builder buildcage --progress=plain -f Dockerfile .
39+
40+
# 3. View report
41+
docker compose logs builder
42+
43+
# 4. Clean up
44+
make clean
45+
```
46+
47+
## Testing
48+
49+
```bash
50+
# Audit mode test (start → build → verify → clean up)
51+
make test_audit_mode
52+
53+
# Restrict mode test (start → build → verify → clean up)
54+
make test_restrict_mode
55+
```
56+
57+
## Viewing Logs
58+
59+
```bash
60+
# All communication logs
61+
docker compose logs builder
62+
63+
# Real-time log monitoring
64+
docker compose logs -f builder
65+
```
66+
67+
**Log format:**
68+
69+
```
70+
[28/Jan/2026:10:15:30 +0000] [ALLOWED] TCP 200 1234 5678 0.123 "github.com:443"
71+
[28/Jan/2026:10:15:31 +0000] [BLOCKED] TCP 502 0 0 0.001 "malicious.com:443"
72+
[28/Jan/2026:10:15:32 +0000] [AUDIT] HTTP 200 2345 6789 0.234 "npmjs.org:80"
73+
```
74+
75+
Fields: `[timestamp] [status] protocol http_status bytes_sent bytes_received duration "domain:port"`
76+
77+
## Makefile Commands
78+
79+
| Command | Description |
80+
|---------|-------------|
81+
| `make help` | Show available commands |
82+
| `make run_audit_mode` | Start in audit mode |
83+
| `make run_restrict_mode` | Start in restrict mode (default domains) |
84+
| `make test_audit_mode` | Run audit mode tests (start → build → verify → clean up) |
85+
| `make test_restrict_mode` | Run restrict mode tests (start → build → verify → clean up) |
86+
| `make clean` | Remove all resources |
87+
88+
## Directory Structure
89+
90+
```
91+
.
92+
├── setup/
93+
│ ├── action.yml # GitHub Action: dash14/buildcage/setup@v1
94+
│ └── compose.yml # Compose config for GitHub Actions (with image tag)
95+
├── report/
96+
│ ├── action.yml # GitHub Action: dash14/buildcage/report@v1
97+
│ └── main.mjs # Log analysis and Job Summary output
98+
├── docs/ # Documents
99+
├── compose.yml # Docker Compose config
100+
├── compose.test.yml # Test override config
101+
├── Makefile # Operational commands
102+
├── docker/
103+
│ ├── Dockerfile # Multi-stage BuildKit + nginx + dnsmasq
104+
│ └── files/ # Builder container config files
105+
│ ├── entrypoint.sh # iptables/dnsmasq/nginx/buildkitd startup
106+
│ ├── buildkitd.toml # BuildKit config
107+
│ ├── cni.conflist # CNI config (isolated-net)
108+
│ ├── dnsmasq.conf # DNS config (all domains → gateway)
109+
│ └── nginx.conf.template # Dynamic nginx config (HTTP/HTTPS)
110+
└── test/
111+
├── Dockerfile.audit # Audit mode test
112+
├── Dockerfile.restrict # Restrict mode test
113+
├── assert-audit-mode.sh # Audit mode verification script
114+
├── assert-restrict-mode.sh # Restrict mode verification script
115+
├── helpers.sh # Test helpers
116+
├── test-server/ # Test HTTP server
117+
└── test-dns/ # Test DNS server
118+
```

0 commit comments

Comments
 (0)
⚡