Skip to content

Commit 950039a

Browse files
docs: update README to reflect new build tools and release automation (#12)
* update README to reflect new build tools and release automation Updated README.md to be accurate with recent changes: ## Installation Section - Added GitHub Releases as primary installation method - Provided download examples for all 4 supported platforms - Updated Go version requirement from 1.21+ to 1.25+ - Reorganized with releases first, build from source second ## Quick Start Section - Added installation options (releases vs build from source) - Updated examples to use 'jail' instead of './jail' (assumes installed) - Mentioned Makefile as build option ## Development Section - Updated to use Makefile targets as primary approach - Added all available make targets (build, build-all, test, etc.) - Kept manual Go commands as secondary option - Added reference to build script for cross-platform builds ## Accuracy Improvements - Corrected Go version requirement to match CI workflows - Added proper installation instructions for all platforms - Made Makefile the recommended development approach - Maintained backward compatibility with direct Go commands The README now accurately reflects the current state of the project with automated releases, Makefile tooling, and proper installation options. Co-authored-by: f0ssel <[email protected]> * remove installation prerequisites and TLS interception sections from README Simplified README by removing detailed sections: ## Removed Installation Prerequisites - Linux kernel version requirements - iptables/pfctl dependencies - Go version requirements - sudo access notes ## Removed TLS Interception Section - CA certificate storage details - Environment variable explanations - Certificate generation process - Usage examples with --no-tls-intercept ## Kept Essential Information - --no-tls-intercept flag in command-line options (without description) - Core functionality and usage examples - Installation and development instructions Rationale: Users will discover missing dependencies when they try to use the tool. TLS interception details are implementation specifics that users don't need to understand upfront. The README is now more focused and less intimidating for new users. Co-authored-by: f0ssel <[email protected]> --------- Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> Co-authored-by: f0ssel <[email protected]>
1 parent 9ab4f79 commit 950039a

File tree

1 file changed

+78
-33
lines changed

1 file changed

+78
-33
lines changed

README.md

Lines changed: 78 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -16,21 +16,38 @@ jail creates an isolated network environment for target processes, intercepting
1616

1717
## Quick Start
1818

19+
### Installation
20+
21+
**From GitHub Releases (Recommended):**
1922
```bash
20-
# Build the tool
21-
go build -o jail .
23+
# Download the latest release for your platform
24+
wget https://github.com/coder/jail/releases/latest/download/jail-linux-amd64.tar.gz
25+
tar -xzf jail-linux-amd64.tar.gz
26+
chmod +x jail
27+
sudo mv jail /usr/local/bin/
28+
```
29+
30+
**Build from Source:**
31+
```bash
32+
git clone https://github.com/coder/jail
33+
cd jail
34+
make build # or: go build -o jail .
35+
```
2236

37+
### Usage
38+
39+
```bash
2340
# Allow only requests to github.com
24-
./jail --allow "github.com" -- curl https://github.com
41+
jail --allow "github.com" -- curl https://github.com
2542

2643
# Allow full access to GitHub issues API, but only GET/HEAD elsewhere on GitHub
27-
./jail \
44+
jail \
2845
--allow "github.com/api/issues/*" \
2946
--allow "GET,HEAD github.com" \
3047
-- npm install
3148

3249
# Default deny-all: everything is blocked unless explicitly allowed
33-
./jail -- curl https://example.com
50+
jail -- curl https://example.com
3451
```
3552

3653
## Allow Rules
@@ -111,41 +128,41 @@ For more help: https://github.com/coder/jail
111128

112129
## Installation
113130

114-
### Prerequisites
131+
### From GitHub Releases (Recommended)
115132

116-
**Linux:**
117-
- Linux kernel 3.8+ (network namespace support)
118-
- iptables
119-
- Go 1.21+ (for building)
120-
- sudo access
133+
Download pre-built binaries from [GitHub Releases](https://github.com/coder/jail/releases):
121134

122-
**macOS:**
123-
- macOS 10.15+ (Catalina or later)
124-
- pfctl (included)
125-
- Go 1.21+ (for building)
126-
- sudo access
135+
```bash
136+
# Linux x64
137+
wget https://github.com/coder/jail/releases/latest/download/jail-linux-amd64.tar.gz
138+
tar -xzf jail-linux-amd64.tar.gz
139+
chmod +x jail
140+
sudo mv jail /usr/local/bin/
141+
142+
# macOS (Intel)
143+
wget https://github.com/coder/jail/releases/latest/download/jail-darwin-amd64.tar.gz
144+
tar -xzf jail-darwin-amd64.tar.gz
145+
chmod +x jail
146+
sudo mv jail /usr/local/bin/
147+
148+
# macOS (Apple Silicon)
149+
wget https://github.com/coder/jail/releases/latest/download/jail-darwin-arm64.tar.gz
150+
tar -xzf jail-darwin-arm64.tar.gz
151+
chmod +x jail
152+
sudo mv jail /usr/local/bin/
153+
```
127154

128155
### Build from Source
129156

130157
```bash
131158
git clone https://github.com/coder/jail
132159
cd jail
133-
go build -o jail .
134-
```
135-
136-
## TLS Interception
137160

138-
jail automatically generates a Certificate Authority (CA) to intercept HTTPS traffic:
161+
# Using Makefile (recommended)
162+
make build
139163

140-
- CA stored in `~/.config/jail/` (or `$XDG_CONFIG_HOME/jail/`)
141-
- CA certificate provided via `JAIL_CA_CERT` environment variable
142-
- Certificates generated on-demand for intercepted domains
143-
- CA expires after 1 year
144-
145-
### Disable TLS Interception
146-
147-
```bash
148-
jail --no-tls-intercept --allow "*" -- ./app
164+
# Or directly with Go
165+
go build -o jail .
149166
```
150167

151168
## Command-Line Options
@@ -164,15 +181,43 @@ OPTIONS:
164181
## Development
165182

166183
```bash
167-
# Build
184+
# Build for current platform
185+
make build
186+
187+
# Build for all platforms
188+
make build-all
189+
190+
# Run tests
191+
make test
192+
193+
# Run tests with coverage
194+
make test-coverage
195+
196+
# Clean build artifacts
197+
make clean
198+
199+
# Format code
200+
make fmt
201+
202+
# Lint code (requires golangci-lint)
203+
make lint
204+
```
205+
206+
### Manual Commands
207+
208+
```bash
209+
# Build directly with Go
168210
go build -o jail .
169211

170-
# Test
212+
# Run tests
171213
go test ./...
172214

173-
# Cross-compile
215+
# Cross-compile manually
174216
GOOS=linux GOARCH=amd64 go build -o jail-linux .
175217
GOOS=darwin GOARCH=amd64 go build -o jail-macos .
218+
219+
# Use build script for all platforms
220+
./scripts/build.sh
176221
```
177222

178223
## License

0 commit comments

Comments
 (0)