Skip to content

Commit 3304d54

Browse files
wwwehrwwwehr
authored
Merge branch 'Dstack-TEE:main' into npw/route53-weighted-routes
2 parents 86a7922 + a690aa3 commit 3304d54

51 files changed

Lines changed: 7087 additions & 148 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/reproducible-build.yml‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
name: Reproducible Build
2+
3+
on:
4+
push:
5+
paths:
6+
- 'tutorial/01a-reproducible-builds/**'
7+
pull_request:
8+
paths:
9+
- 'tutorial/01a-reproducible-builds/**'
10+
workflow_dispatch:
11+
12+
env:
13+
REGISTRY: ghcr.io
14+
IMAGE_NAME: ${{ github.repository }}/tutorial-01a-oracle
15+
16+
jobs:
17+
build:
18+
runs-on: ubuntu-latest
19+
permissions:
20+
contents: read
21+
packages: write
22+
defaults:
23+
run:
24+
working-directory: tutorial/01a-reproducible-builds
25+
26+
steps:
27+
- uses: actions/checkout@v4
28+
29+
- name: Set up Docker Buildx
30+
uses: docker/setup-buildx-action@v3
31+
32+
- name: Install skopeo
33+
run: sudo apt-get update && sudo apt-get install -y skopeo
34+
35+
- name: Build reproducible image
36+
run: |
37+
docker buildx create --name repro-builder --driver docker-container || true
38+
docker buildx build \
39+
--builder repro-builder \
40+
--build-arg SOURCE_DATE_EPOCH=0 \
41+
--no-cache \
42+
--output type=oci,dest=image.tar,rewrite-timestamp=true \
43+
.
44+
45+
- name: Compute and display hash
46+
id: hash
47+
run: |
48+
HASH=$(sha256sum image.tar | awk '{print $1}')
49+
DIGEST=$(skopeo inspect oci-archive:image.tar | jq -r .Digest)
50+
echo "image_hash=$HASH" >> $GITHUB_OUTPUT
51+
echo "image_digest=$DIGEST" >> $GITHUB_OUTPUT
52+
echo "## Reproducible Build Results" >> $GITHUB_STEP_SUMMARY
53+
echo "" >> $GITHUB_STEP_SUMMARY
54+
echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
55+
echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
56+
echo "| **Image Hash** | \`$HASH\` |" >> $GITHUB_STEP_SUMMARY
57+
echo "| **Image Digest** | \`$DIGEST\` |" >> $GITHUB_STEP_SUMMARY
58+
echo "" >> $GITHUB_STEP_SUMMARY
59+
echo "Compare with your local build:" >> $GITHUB_STEP_SUMMARY
60+
echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
61+
echo "cd tutorial/01a-reproducible-builds && ./build-reproducible.sh" >> $GITHUB_STEP_SUMMARY
62+
echo "cat build-manifest.json" >> $GITHUB_STEP_SUMMARY
63+
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
64+
65+
- name: Verify against committed manifest
66+
run: |
67+
if [[ -f build-manifest.json ]]; then
68+
EXPECTED=$(jq -r .image_hash build-manifest.json)
69+
ACTUAL="${{ steps.hash.outputs.image_hash }}"
70+
echo "Expected: $EXPECTED"
71+
echo "Actual: $ACTUAL"
72+
if [[ "$EXPECTED" == "$ACTUAL" ]]; then
73+
echo "✓ Build matches committed manifest"
74+
else
75+
echo "✗ Build differs from committed manifest"
76+
exit 1
77+
fi
78+
else
79+
echo "No build-manifest.json found - skipping verification"
80+
fi
81+
82+
- name: Upload OCI image
83+
uses: actions/upload-artifact@v4
84+
with:
85+
name: reproducible-image
86+
path: tutorial/01a-reproducible-builds/image.tar
87+
retention-days: 7
88+
89+
- name: Login to GHCR
90+
if: github.event_name != 'pull_request'
91+
uses: docker/login-action@v3
92+
with:
93+
registry: ${{ env.REGISTRY }}
94+
username: ${{ github.actor }}
95+
password: ${{ secrets.GITHUB_TOKEN }}
96+
97+
- name: Push to GHCR
98+
if: github.event_name != 'pull_request'
99+
run: |
100+
IMAGE_TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"
101+
skopeo copy oci-archive:image.tar docker://$IMAGE_TAG
102+
echo "Pushed: $IMAGE_TAG" >> $GITHUB_STEP_SUMMARY
103+
if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
104+
LATEST_TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest"
105+
skopeo copy oci-archive:image.tar docker://$LATEST_TAG
106+
echo "Pushed: $LATEST_TAG" >> $GITHUB_STEP_SUMMARY
107+
fi

‎README.md‎

Lines changed: 165 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
**Example applications for [dstack](https://github.com/Dstack-TEE/dstack) - Deploy containerized apps to TEEs with end-to-end security in minutes**
1111

12-
[Getting Started](#getting-started) • [Examples](#examples) • [Contributing](CONTRIBUTING.md) • [Documentation](#documentation) • [Community](#community)
12+
[Getting Started](#getting-started) • [Use Cases](#use-cases) • [Core Patterns](#core-patterns) • [Dev Tools](#dev-scaffolding) • [Starter Packs](#starter-packs) • [Other Use Cases](#other-use-cases)
1313

1414
</div>
1515

@@ -19,113 +19,220 @@
1919

2020
This repository contains ready-to-deploy examples demonstrating how to build and run applications on [dstack](https://github.com/Dstack-TEE/dstack), the developer-friendly SDK for deploying containerized apps in Trusted Execution Environments (TEE).
2121

22-
### What You'll Find Here
22+
## Getting Started
2323

24-
- **Security Features** - Remote attestation, verification, and privacy-preserving apps
25-
- **Secret Management** - Secure handling of credentials and sensitive data in TEE environments
26-
- **Networking Patterns** - HTTPS termination, custom domains, port forwarding in the cloud
27-
- **Best Practices** - Production-ready implementations following TEE security principles
24+
### Prerequisites
2825

29-
## Prerequisites
26+
- Docker and Docker Compose
27+
- Node.js (for Phala CLI)
28+
- Git
3029

31-
Before you begin, ensure you have:
30+
### Setup
3231

33-
- Access to a dstack environment
34-
- Basic understanding of [TEE concepts](https://docs.phala.network/dstack)
35-
- Basic familiarity with Docker Compose configuration files
36-
- Git for cloning the repository
32+
```bash
33+
# Clone the repo
34+
git clone https://github.com/Dstack-TEE/dstack-examples.git
35+
cd dstack-examples
3736

38-
You can deploy dstack on your own server, or use [Phala Cloud](https://cloud.phala.network).
37+
# Install Phala CLI
38+
npm install -g phala
3939

40-
## Getting Started
40+
# Start the local simulator (no TEE hardware needed)
41+
phala simulator start
42+
```
4143

42-
### Quick Start
44+
### Run an Example Locally
4345

4446
```bash
45-
# Clone the repository
46-
git clone https://github.com/Dstack-TEE/dstack-examples.git
47-
cd dstack-examples
47+
cd tutorial/01-attestation-oracle
48+
docker compose run --rm \
49+
-v ~/.phala-cloud/simulator/0.5.3/dstack.sock:/var/run/dstack.sock \
50+
app
51+
```
52+
53+
### Deploy to Phala Cloud
54+
55+
```bash
56+
phala auth login
57+
phala deploy -n my-app -c docker-compose.yaml
58+
```
59+
60+
See [Phala Cloud](https://cloud.phala.network) for production TEE deployment.
61+
62+
---
63+
64+
## Tutorials
65+
66+
Step-by-step guides covering core dstack concepts.
67+
68+
| Tutorial | Description |
69+
|----------|-------------|
70+
| [01-attestation-oracle](./tutorial/01-attestation-oracle) | Use the guest SDK to work with attestations directly — build an oracle, bind data to TDX quotes via `report_data`, verify with local scripts |
71+
| [02-persistence-and-kms](./tutorial/02-persistence-and-kms) | Use `getKey()` for deterministic key derivation from a KMS — persistent wallets, same key across restarts |
72+
| [03-gateway-and-ingress](./tutorial/03-gateway-and-ingress) | Custom domains with automatic SSL, certificate evidence chain |
73+
| [04-upgrades](./tutorial/04-upgrades) | Extend `AppAuth.sol` with custom authorization logic — NFT-gated clusters, on-chain governance |
74+
75+
---
4876

49-
# Choose an example
50-
cd attestation/configid-based
77+
## Use Cases
5178

52-
# Copy the docker-compose.yaml content to your dstack deployment
53-
# Follow the example-specific README for deployment instructions
79+
Real-world applications you can build with dstack.
80+
81+
| Example | Description | Status |
82+
|---------|-------------|--------|
83+
| [8004-agent](./8004-agent) | Trustless AI agent with on-chain attestation and LLM access | Coming Soon |
84+
| [oracle](./oracle) | TEE oracle returning JSON + signature + attestation bundle | Coming Soon |
85+
| [mcp-server](./mcp-server) | Attested MCP tool server behind gateway | Coming Soon |
86+
| [telegram-agent](./telegram-agent) | Telegram bot with TEE wallet and verified execution | Coming Soon |
87+
88+
---
89+
90+
## Core Patterns
91+
92+
Key building blocks for dstack applications.
93+
94+
### Attestation
95+
96+
Request TEE attestations via the SDK. Mount `/var/run/dstack.sock` in your compose file to access the TEE.
97+
98+
```javascript
99+
import { DstackClient } from '@phala/dstack-sdk'
100+
const client = new DstackClient()
101+
const info = await client.info() // app_id, instance_id, tcb_info
102+
const quote = await client.getQuote(data) // TDX quote with custom report_data
103+
const key = await client.getKey('/my/path') // deterministic key derivation
54104
```
55105

56-
## Examples
106+
```yaml
107+
volumes:
108+
- /var/run/dstack.sock:/var/run/dstack.sock
109+
```
110+
111+
| Example | Description | Status |
112+
|---------|-------------|--------|
113+
| [timelock-nts](./timelock-nts) | Raw socket usage (what the SDK wraps) | Available |
114+
| [attestation/configid-based](./attestation/configid-based) | ConfigID-based verification | Available |
115+
116+
### Gateway & Domains
117+
118+
TLS termination, custom domains, external connectivity.
57119
58-
### Security & Attestation
59120
| Example | Description |
60121
|---------|-------------|
61-
| [attestation/configid-based](./attestation/configid-based) | ConfigID-based remote attestation verification |
62-
| [attestation/rtmr3-based](./attestation/rtmr3-based) | RTMR3-based attestation (legacy) |
122+
| [dstack-ingress](./custom-domain/dstack-ingress) | **Complete ingress solution** — auto SSL via Let's Encrypt, multi-domain, DNS validation, evidence generation with TDX quote chain |
123+
| [custom-domain](./custom-domain/custom-domain) | Simpler custom domain setup via zt-https |
124+
125+
### Keys & Persistence
126+
127+
Persistent keys across deployments via KMS.
128+
129+
| Example | Description | Status |
130+
|---------|-------------|--------|
131+
| [get-key-basic](./get-key-basic) | `dstack.get_key()` — same key identity across machines | Coming Soon |
132+
133+
### On-Chain Interaction
134+
135+
Light client for reading chain state, anchoring outputs.
63136

64-
### Networking & Domains
65137
| Example | Description |
66138
|---------|-------------|
67-
| [custom-domain](./custom-domain) | Set up custom domain with automatic TLS certificate management via zt-https |
139+
| [lightclient](./lightclient) | Ethereum light client (Helios) running in enclave |
140+
141+
---
142+
143+
## Dev Scaffolding
144+
145+
Development and debugging tools. **Not for production.**
146+
147+
| Example | Description |
148+
|---------|-------------|
149+
| [webshell](./webshell) | Web-based shell access for debugging |
68150
| [ssh-over-gateway](./ssh-over-gateway) | SSH tunneling through dstack gateway |
69151
| [tcp-port-forwarding](./tcp-port-forwarding) | Arbitrary TCP port forwarding |
70-
| [tor-hidden-service](./tor-hidden-service) | Run Tor hidden services in TEEs |
71152

72-
### Development Tools
153+
---
154+
155+
## Tech Demos
156+
157+
Interesting demonstrations.
158+
73159
| Example | Description |
74160
|---------|-------------|
75-
| [launcher](./launcher) | Generic launcher pattern for Docker Compose apps |
76-
| [webshell](./webshell) | Web-based shell access for debugging |
77-
| [prelaunch-script](./prelaunch-script) | Pre-launch script patterns used by Phala Cloud |
161+
| [tor-hidden-service](./tor-hidden-service) | Run Tor hidden services in TEEs |
162+
163+
---
164+
165+
## Starter Packs
166+
167+
Full-stack templates with SDK integration. These demonstrate attestation, key derivation, and wallet generation.
168+
169+
| Template | Stack | Link |
170+
|----------|-------|------|
171+
| **Next.js Starter** | Next.js + TypeScript | [phala-cloud-nextjs-starter](https://github.com/Phala-Network/phala-cloud-nextjs-starter) |
172+
| **Python Starter** | FastAPI + Python | [phala-cloud-python-starter](https://github.com/Phala-Network/phala-cloud-python-starter) |
173+
| **Bun Starter** | Bun + TypeScript | [phala-cloud-bun-starter](https://github.com/Phala-Network/phala-cloud-bun-starter) |
174+
| **Node.js Starter** | Express + TypeScript | [phala-cloud-node-starter](https://github.com/Gldywn/phala-cloud-node-starter) |
175+
176+
Features: `/api/tdx_quote` (attestation), `/api/eth_account` (derived wallet), `/api/info` (TCB info)
177+
178+
---
179+
180+
## Other Use Cases
181+
182+
External projects and templates worth exploring. These are maintained elsewhere but demonstrate interesting TEE patterns.
183+
184+
| Project | Description | Link |
185+
|---------|-------------|------|
186+
| **Oracle Template** | Price aggregator with verifiable networking (hardened TLS) and multi-source validation | [Gldywn/phala-cloud-oracle-template](https://github.com/Gldywn/phala-cloud-oracle-template) |
187+
| **VRF Template** | Verifiable Random Function — hardware-backed cryptographic randomness | [Phala-Network/phala-cloud-vrf-template](https://github.com/Phala-Network/phala-cloud-vrf-template) |
188+
| **Open WebUI** | Self-hosted AI chat interface in TEE | [phala-cloud/templates/openwebui](https://github.com/Phala-Network/phala-cloud/tree/main/templates/prebuilt/openwebui) |
189+
| **n8n Automation** | Workflow automation (400+ integrations) with OAuth in TEE | [Marvin-Cypher/phala-n8n-template](https://github.com/Marvin-Cypher/phala-n8n-template) |
190+
| **Primus Attestor** | zkTLS node — TEE + zero-knowledge proofs | [primus-labs/primus-network-startup](https://github.com/primus-labs/primus-network-startup) |
191+
| **NEAR Shade Agent** | Blockchain oracle/agent for NEAR with TEE attestation | [phala-cloud/templates/near-shade-agent](https://github.com/Phala-Network/phala-cloud/tree/main/templates/prebuilt/near-shade-agent) |
192+
| **Presidio** | Microsoft's PII de-identification running in TEE | [HashWarlock/presidio](https://github.com/HashWarlock/presidio/tree/phala-cloud) |
193+
| **ByteBot** | AI desktop agent — computer control in isolated TEE sandbox | [phala-cloud/templates/bytebot](https://github.com/Phala-Network/phala-cloud/tree/main/templates/prebuilt/bytebot) |
194+
195+
> **Note**: These templates use pre-built Docker images. For full auditability, review their source repos before deployment.
196+
197+
See the full [Phala Cloud templates](https://github.com/Phala-Network/phala-cloud#templates) for more options.
198+
199+
---
200+
201+
## Details
202+
203+
Implementation details and infrastructure patterns.
78204

79-
### Advanced Use Cases
80205
| Example | Description |
81206
|---------|-------------|
82-
| [lightclient](./lightclient) | Blockchain light client integration |
83-
| [timelock-nts](./timelock-nts) | Timelock decryption with NTS |
207+
| [launcher](./launcher) | Generic launcher pattern for Docker Compose apps |
208+
| [prelaunch-script](./prelaunch-script) | Pre-launch script patterns (Phala Cloud) |
84209
| [private-docker-image-deployment](./private-docker-image-deployment) | Using private Docker registries |
210+
| [attestation/rtmr3-based](./attestation/rtmr3-based) | RTMR3-based attestation (legacy) |
211+
212+
---
85213

86214
## Documentation
87215

88216
- **[dstack Documentation](https://docs.phala.network/dstack)** - Official platform documentation
89217
- **[Main Repository](https://github.com/Dstack-TEE/dstack)** - Core dstack framework
90-
- **[Security Guide](SECURITY.md)** - Security best practices
91218
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
92219

93220
## Development
94221

95-
Use the `dev.sh` script for validation and development tasks:
96-
97222
```bash
98223
./dev.sh help # Show available commands
99224
./dev.sh validate <example> # Validate a specific example
100225
./dev.sh validate-all # Validate all examples
101-
./dev.sh security # Run security checks
102-
./dev.sh lint # Run linting checks
103-
./dev.sh check-all # Run all checks
104226
```
105227

106-
## Contributing
107-
108-
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
109-
110228
## Community
111229

112-
### Getting Help
113-
114230
- **Telegram**: [Join our community](https://t.me/+UO4bS4jflr45YmUx)
115231
- **Issues**: [GitHub Issues](https://github.com/Dstack-TEE/dstack-examples/issues)
116232

117-
### Reporting Issues
118-
119-
When reporting issues, please include:
120-
121-
1. Example name and version
122-
2. Steps to reproduce
123-
3. Expected vs actual behavior
124-
4. Relevant logs and error messages
125-
126233
## License
127234

128-
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
235+
Apache 2.0 — see [LICENSE](LICENSE).
129236

130237
---
131238

0 commit comments

Comments
 (0)