Skip to content

Commit b675ad9

Browse files
MossakaMossaka
committed
Add release workflow and update documentation for container image strategy
Signed-off-by: Jiaxiao (mossaka) Zhou <duibao55328@gmail.com>
1 parent 9bb4ba0 commit b675ad9

7 files changed

Lines changed: 542 additions & 87 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*' # Trigger on version tags like v1.0.0, v0.1.0, etc.
7+
workflow_dispatch: # Allow manual triggers
8+
9+
permissions:
10+
contents: write # Required for creating releases
11+
packages: write # Required for pushing to GHCR
12+
13+
jobs:
14+
build-and-release:
15+
name: Build and Release
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: '22'
26+
cache: 'npm'
27+
28+
- name: Install dependencies
29+
run: npm ci
30+
31+
- name: Build TypeScript
32+
run: npm run build
33+
34+
- name: Extract version from tag
35+
id: version_early
36+
run: |
37+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
38+
VERSION=$(node -p "require('./package.json').version")
39+
echo "version=v$VERSION" >> $GITHUB_OUTPUT
40+
echo "version_number=$VERSION" >> $GITHUB_OUTPUT
41+
else
42+
VERSION="${GITHUB_REF#refs/tags/}"
43+
VERSION_NUMBER="${VERSION#v}"
44+
echo "version=$VERSION" >> $GITHUB_OUTPUT
45+
echo "version_number=$VERSION_NUMBER" >> $GITHUB_OUTPUT
46+
fi
47+
48+
- name: Log in to GitHub Container Registry
49+
uses: docker/login-action@v3
50+
with:
51+
registry: ghcr.io
52+
username: ${{ github.actor }}
53+
password: ${{ secrets.GITHUB_TOKEN }}
54+
55+
- name: Set up Docker Buildx
56+
uses: docker/setup-buildx-action@v3
57+
58+
- name: Build and push Squid image
59+
uses: docker/build-push-action@v5
60+
with:
61+
context: ./containers/squid
62+
push: true
63+
tags: |
64+
ghcr.io/${{ github.repository }}/squid:${{ steps.version_early.outputs.version_number }}
65+
ghcr.io/${{ github.repository }}/squid:latest
66+
cache-from: type=gha
67+
cache-to: type=gha,mode=max
68+
69+
- name: Build and push Copilot image
70+
uses: docker/build-push-action@v5
71+
with:
72+
context: ./containers/copilot
73+
push: true
74+
tags: |
75+
ghcr.io/${{ github.repository }}/copilot:${{ steps.version_early.outputs.version_number }}
76+
ghcr.io/${{ github.repository }}/copilot:latest
77+
cache-from: type=gha
78+
cache-to: type=gha,mode=max
79+
80+
- name: Install pkg for binary creation
81+
run: npm install -g pkg
82+
83+
- name: Create binaries
84+
run: |
85+
mkdir -p release
86+
87+
# Create standalone executable for Linux
88+
pkg . \
89+
--targets node18-linux-x64 \
90+
--output release/awf
91+
92+
# Rename output to include platform
93+
mv release/awf-linux release/awf-linux-x64
94+
95+
- name: Create tarball for npm package
96+
run: |
97+
npm pack
98+
mv *.tgz release/awf.tgz
99+
100+
- name: Generate checksums
101+
run: |
102+
cd release
103+
sha256sum * > checksums.txt
104+
105+
- name: Create Release Notes
106+
id: release_notes
107+
run: |
108+
cat > release_notes.md << 'EOF'
109+
## Installation
110+
111+
### Binary Installation (Recommended)
112+
113+
**Linux (x64):**
114+
```bash
115+
curl -L https://github.com/${{ github.repository }}/releases/download/${{ steps.version_early.outputs.version }}/awf-linux-x64 -o awf
116+
chmod +x awf
117+
sudo mv awf /usr/local/bin/
118+
```
119+
120+
### NPM Installation (Alternative)
121+
122+
```bash
123+
# Install from tarball
124+
npm install -g https://github.com/${{ github.repository }}/releases/download/${{ steps.version_early.outputs.version }}/awf.tgz
125+
```
126+
127+
### Requirements
128+
129+
- Docker and Docker Compose must be installed
130+
- For iptables manipulation, run with sudo: `sudo awf ...`
131+
- Container images will be pulled automatically from GHCR on first run
132+
133+
## Verification
134+
135+
Verify checksums after download:
136+
```bash
137+
sha256sum -c checksums.txt
138+
```
139+
140+
## Usage
141+
142+
```bash
143+
sudo awf --allow-domains github.com,api.github.com 'curl https://api.github.com'
144+
```
145+
146+
See [README.md](https://github.com/${{ github.repository }}/blob/${{ steps.version_early.outputs.version }}/README.md) for full documentation.
147+
148+
## Container Images
149+
150+
Published to GitHub Container Registry:
151+
- `ghcr.io/${{ github.repository }}/squid:${{ steps.version_early.outputs.version_number }}`
152+
- `ghcr.io/${{ github.repository }}/copilot:${{ steps.version_early.outputs.version_number }}`
153+
- `ghcr.io/${{ github.repository }}/squid:latest`
154+
- `ghcr.io/${{ github.repository }}/copilot:latest`
155+
EOF
156+
157+
- name: Create GitHub Release
158+
uses: softprops/action-gh-release@v1
159+
with:
160+
tag_name: ${{ steps.version_early.outputs.version }}
161+
name: Release ${{ steps.version_early.outputs.version }}
162+
body_path: release_notes.md
163+
draft: false
164+
prerelease: ${{ contains(steps.version_early.outputs.version, 'alpha') || contains(steps.version_early.outputs.version, 'beta') || contains(steps.version_early.outputs.version, 'rc') }}
165+
files: |
166+
release/awf-linux-x64
167+
release/awf.tgz
168+
release/checksums.txt
169+
env:
170+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
171+
172+
- name: Upload artifacts (for debugging)
173+
uses: actions/upload-artifact@v4
174+
if: always()
175+
with:
176+
name: release-artifacts
177+
path: release/
178+
retention-days: 7

‎CLAUDE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,25 @@ sudo awf --help
114114

115115
**Note:** After each `npm run build`, the wrapper automatically uses the latest compiled code. Update the paths in the wrapper script to match your node installation and project directory.
116116

117+
## Container Image Strategy
118+
119+
The firewall uses two Docker containers (Squid proxy and Copilot execution environment). By default, the CLI pulls pre-built images from GitHub Container Registry (GHCR) for faster startup and easier distribution.
120+
121+
**Default behavior (GHCR images):**
122+
- Images are automatically pulled from `ghcr.io/mossaka/gh-aw-firewall/squid:latest` and `ghcr.io/mossaka/gh-aw-firewall/copilot:latest`
123+
- Published during releases via `.github/workflows/release.yml`
124+
- Users don't need to build containers locally
125+
126+
**Local build option:**
127+
- Use `--build-local` flag to build containers from source
128+
- Useful for development or when GHCR is unavailable
129+
- Example: `sudo awf --build-local --allow-domains github.com 'curl https://github.com'`
130+
131+
**Custom registry/tag:**
132+
- `--image-registry <registry>` - Use a different registry (default: `ghcr.io/mossaka/gh-aw-firewall`)
133+
- `--image-tag <tag>` - Use a specific version tag (default: `latest`)
134+
- Example: `sudo awf --image-tag v0.2.0 --allow-domains github.com 'curl https://github.com'`
135+
117136
## Architecture
118137

119138
The codebase follows a modular architecture with clear separation of concerns:

0 commit comments

Comments
 (0)