Skip to content

Commit 7c81f0e

Browse files
dmvtclaude
andcommitted
docs: add self-host tutorial series from dstack-info
Bring over 31 tutorial markdown files covering the full self-hosting workflow: TDX setup, host configuration, dstack installation, gateway deployment, blockchain integration, first app deployment, KMS CVM deployment, and troubleshooting guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 31cfd48 commit 7c81f0e

31 files changed

Lines changed: 10210 additions & 0 deletions

docs/tutorials/attestation-verification.md

Lines changed: 848 additions & 0 deletions
Large diffs are not rendered by default.

docs/tutorials/blockchain-setup.md

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
---
2+
title: "Blockchain Wallet Setup"
3+
description: "Set up an Ethereum wallet and fund it with testnet ETH for dstack deployment"
4+
section: "Prerequisites"
5+
stepNumber: 5
6+
totalSteps: 7
7+
lastUpdated: 2026-01-09
8+
prerequisites: []
9+
tags:
10+
- blockchain
11+
- ethereum
12+
- wallet
13+
- testnet
14+
- sepolia
15+
difficulty: intermediate
16+
estimatedTime: 15-20 minutes
17+
---
18+
19+
# Blockchain Wallet Setup
20+
21+
dstack's Key Management Service (KMS) is deployed as a smart contract on the Ethereum blockchain. For tutorial purposes, we'll use the **Sepolia testnet**, which allows you to deploy and test without spending real ETH.
22+
23+
## What You'll Need
24+
25+
- **Ethereum wallet** with a private key
26+
- **Testnet ETH** (~0.1 ETH minimum for deployment)
27+
28+
## Why Sepolia?
29+
30+
Sepolia is one of Ethereum's official testnets:
31+
32+
- Free testnet ETH from faucets
33+
- Similar to mainnet but without real value
34+
- Perfect for development and testing
35+
- Widely supported by tools and services
36+
37+
---
38+
39+
## Option 1: Command-Line Wallet (Recommended)
40+
41+
If you have [Foundry](https://book.getfoundry.sh/getting-started/installation) installed, you can create a wallet using the `cast` command.
42+
43+
### Step 1.1: Check if Foundry is Installed
44+
45+
```bash
46+
cast --version
47+
```
48+
49+
If not installed, see: https://book.getfoundry.sh/getting-started/installation
50+
51+
### Step 1.2: Generate New Wallet
52+
53+
```bash
54+
cast wallet new
55+
```
56+
57+
**Example output:**
58+
59+
```
60+
Successfully created new keypair.
61+
Address: 0x91Ba69FCD13D2876FD06907a2880BDBC93C336aF
62+
Private key: 0xd76e8d3059484d5d9167c4e10cfeea2a4efa655875112e693e18fb4ab890b98a
63+
```
64+
65+
⚠️ **Save these immediately:**
66+
67+
- **Address:** Your public wallet address (safe to share)
68+
- **Private Key:** SECRET - never share or commit to git
69+
70+
### Step 1.3: Store Wallet Credentials Securely
71+
72+
Create secure files to store your wallet address and private key:
73+
74+
```bash
75+
# Create secure directory
76+
mkdir -p ~/.dstack/secrets
77+
chmod 700 ~/.dstack/secrets
78+
79+
# Store wallet address (replace with your address)
80+
echo "0xYOUR_ADDRESS_HERE" > ~/.dstack/secrets/sepolia-address
81+
chmod 600 ~/.dstack/secrets/sepolia-address
82+
83+
# Store private key (replace with your key)
84+
echo "0xYOUR_PRIVATE_KEY_HERE" > ~/.dstack/secrets/sepolia-private-key
85+
chmod 600 ~/.dstack/secrets/sepolia-private-key
86+
```
87+
88+
⚠️ **IMPORTANT:** Add to `.gitignore` if working in a git repository:
89+
90+
```bash
91+
echo "~/.dstack/secrets/" >> ~/.gitignore
92+
```
93+
94+
### Step 1.4: Check Wallet Balance
95+
96+
```bash
97+
# Quick check using public Sepolia RPC
98+
cast balance "$(cat ~/.dstack/secrets/sepolia-address)" --rpc-url https://ethereum-sepolia-rpc.publicnode.com
99+
```
100+
101+
Expected output for new wallet: `0` (zero)
102+
103+
---
104+
105+
## Option 2: MetaMask Wallet
106+
107+
If you prefer a browser-based wallet, MetaMask is the most popular choice.
108+
109+
### Step 2.1: Install MetaMask
110+
111+
1. Visit: https://metamask.io/
112+
2. Install browser extension (Chrome, Firefox, Brave, Edge)
113+
3. Create new wallet or import existing one
114+
4. **Save your seed phrase securely** (12 or 24 words)
115+
116+
### Step 2.2: Add Sepolia Network
117+
118+
1. Open MetaMask
119+
2. Click network dropdown (top center)
120+
3. Click "Add Network" or "Add a network manually"
121+
4. Enter Sepolia network details:
122+
123+
```
124+
Network Name: Sepolia
125+
RPC URL: https://ethereum-sepolia-rpc.publicnode.com
126+
Chain ID: 11155111
127+
Currency Symbol: ETH
128+
Block Explorer: https://sepolia.etherscan.io
129+
```
130+
131+
5. Click "Save"
132+
133+
### Step 2.3: Get Your Wallet Address
134+
135+
1. Open MetaMask
136+
2. Click on account name (top center)
137+
3. Address shown below name (starts with `0x...`)
138+
4. Click to copy
139+
140+
### Step 2.4: Export Private Key (for dstack CLI)
141+
142+
⚠️ **Only do this if you need the private key for programmatic access**
143+
144+
1. Open MetaMask
145+
2. Click three dots (top right) → Account Details
146+
3. Click "Export Private Key"
147+
4. Enter MetaMask password
148+
5. Click to reveal and copy private key
149+
6. Store securely as shown in Step 1.3
150+
151+
---
152+
153+
## Step 2: Get Testnet ETH
154+
155+
You need testnet ETH to deploy the KMS smart contract.
156+
157+
### PoW Faucet (Recommended)
158+
159+
**Best option for new wallets** - no requirements:
160+
161+
1. Visit: https://sepolia-faucet.pk910.de/
162+
2. Enter your wallet address
163+
3. Click "Start Mining"
164+
4. Wait 10-30 minutes while mining runs in your browser
165+
5. Claim your testnet ETH (typically 0.05-0.1 ETH per session)
166+
167+
**Why this faucet?**
168+
169+
- No mainnet ETH balance required
170+
- No account signup needed
171+
- No MetaMask required
172+
- Works for brand new wallets
173+
- Just needs patience for mining
174+
175+
### MetaMask Faucet
176+
177+
If you're using MetaMask:
178+
179+
- URL: https://docs.metamask.io/developer-tools/faucet
180+
-**Requires:** MetaMask extension installed
181+
182+
### More Faucet Options
183+
184+
For a comprehensive list of Sepolia faucets with their specific requirements, see:
185+
**https://faucetlink.to/sepolia**
186+
187+
This page lists all available faucets and their requirements (mainnet ETH balance, account signup, etc.)
188+
189+
### Verify You Received ETH
190+
191+
**Command Line:**
192+
193+
```bash
194+
# Quick check using public Sepolia RPC
195+
cast balance "$(cat ~/.dstack/secrets/sepolia-address)" --rpc-url https://ethereum-sepolia-rpc.publicnode.com
196+
```
197+
198+
Expected: Non-zero value (e.g., `50000000000000000` = 0.05 ETH, `100000000000000000` = 0.1 ETH in wei)
199+
200+
**MetaMask:**
201+
202+
- Switch to Sepolia network
203+
- Check balance shown in extension
204+
205+
**Block Explorer:**
206+
207+
```bash
208+
# Open in browser
209+
open "https://sepolia.etherscan.io/address/$(cat ~/.dstack/secrets/sepolia-address)"
210+
211+
# Or manually visit with your address
212+
https://sepolia.etherscan.io/address/YOUR_ADDRESS
213+
```
214+
215+
---
216+
217+
## Step 3: Verify Your Secrets
218+
219+
Check that all required secrets are stored:
220+
221+
```bash
222+
# List your secrets
223+
ls -la ~/.dstack/secrets/
224+
```
225+
226+
You should have:
227+
- `sepolia-address` - Your wallet address
228+
- `sepolia-private-key` - Your wallet private key
229+
230+
**Test your configuration:**
231+
232+
```bash
233+
echo "Wallet: $(cat ~/.dstack/secrets/sepolia-address)"
234+
echo "Balance: $(cast balance "$(cat ~/.dstack/secrets/sepolia-address)" --rpc-url https://ethereum-sepolia-rpc.publicnode.com)"
235+
```
236+
237+
---
238+
239+
## Verification Checklist
240+
241+
Before proceeding to KMS deployment, verify:
242+
243+
- ✅ Wallet created and address saved to `~/.dstack/secrets/sepolia-address`
244+
- ✅ Private key stored securely in `~/.dstack/secrets/sepolia-private-key`
245+
- ✅ Wallet has ≥0.1 testnet ETH
246+
- ✅ Can query balance via cast
247+
248+
---
249+
250+
## Troubleshooting
251+
252+
For detailed solutions, see the [Prerequisites Troubleshooting Guide](/tutorial/troubleshooting-prerequisites#blockchain-wallet-setup-issues):
253+
254+
- [Faucet not sending ETH](/tutorial/troubleshooting-prerequisites#problem-faucet-not-sending-eth)
255+
- [RPC endpoint timing out](/tutorial/troubleshooting-prerequisites#problem-rpc-endpoint-timing-out)
256+
- ["Connection refused" error](/tutorial/troubleshooting-prerequisites#problem-connection-refused-error)
257+
- [Can't see balance in cast](/tutorial/troubleshooting-prerequisites#problem-cant-see-balance-in-cast)
258+
259+
---
260+
261+
## Security Best Practices
262+
263+
### DO:
264+
265+
**Follow these practices:**
266+
267+
- Store private keys in encrypted files with restricted permissions (chmod 600)
268+
- Use environment variables for sensitive data
269+
- Keep separate wallets for testnet and mainnet
270+
- Back up your wallet securely (encrypted USB, password manager)
271+
- Use hardware wallet for mainnet production deployments
272+
273+
### DON'T:
274+
275+
**Avoid these mistakes:**
276+
277+
- Commit private keys to git repositories
278+
- Share private keys via email, chat, or screenshots
279+
- Use testnet wallet for mainnet (always use separate wallets)
280+
- Store private keys in plain text on cloud storage
281+
- Reuse private keys across projects
282+
283+
---
284+
285+
## Next Steps
286+
287+
Once your wallet is set up and funded, you can proceed to:
288+
289+
1. **Host Setup:** [TDX Hardware Verification](/tutorial/tdx-hardware-verification) - Begin configuring your TDX-capable server
290+
2. **Skip Ahead:** If you already have a TDX-enabled server, you'll use this wallet in the KMS deployment phase
291+
292+
Your blockchain wallet is ready for dstack KMS deployment! 🎉

0 commit comments

Comments
 (0)