Skip to content

Commit 201bf2a

Browse files
ALaustrupALaustrup
committed
docs: Add production deployment guide with systemd, monitoring, and backup procedures
1 parent 65b8f28 commit 201bf2a

1 file changed

Lines changed: 335 additions & 0 deletions

File tree

‎docs/DEPLOYMENT.md‎

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
1+
# Demiurge Protocol - Production Deployment Guide
2+
3+
## Overview
4+
5+
This document outlines the deployment process for the Demiurge Protocol to production servers.
6+
7+
## Prerequisites
8+
9+
### Server Requirements
10+
11+
- **OS**: Ubuntu 22.04 LTS or Debian 12
12+
- **RAM**: Minimum 16GB (32GB recommended for validators)
13+
- **Storage**: 500GB SSD (NVMe recommended)
14+
- **CPU**: 4+ cores (8+ recommended)
15+
- **Network**: Static IP, ports 30333, 9944, 9933 open
16+
17+
### Software Dependencies
18+
19+
```bash
20+
# Update system
21+
sudo apt update && sudo apt upgrade -y
22+
23+
# Install build essentials
24+
sudo apt install -y build-essential pkg-config libssl-dev libclang-dev git curl
25+
26+
# Install Rust (nightly required for ZK circuits)
27+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
28+
source $HOME/.cargo/env
29+
rustup install nightly
30+
rustup default stable
31+
32+
# Install Node.js (for SDKs)
33+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
34+
sudo apt install -y nodejs
35+
```
36+
37+
## Build Process
38+
39+
### 1. Clone Repository
40+
41+
```bash
42+
git clone https://github.com/ALaustrup/Demiurge-Blockchain.git
43+
cd Demiurge-Blockchain
44+
```
45+
46+
### 2. Build Framework
47+
48+
```bash
49+
cd framework
50+
51+
# Build release binaries
52+
cargo build --release --features "demiurge-agentic/std,demiurge-cvp/zk-plonky2"
53+
54+
# Run tests
55+
cargo test --release --features "demiurge-agentic/std"
56+
```
57+
58+
### 3. Build Node
59+
60+
```bash
61+
# The main node binary
62+
cargo build --release -p demiurge-node
63+
```
64+
65+
## Configuration
66+
67+
### Create Node Configuration
68+
69+
```toml
70+
# /etc/demiurge/node.toml
71+
72+
[network]
73+
listen_addresses = ["/ip4/0.0.0.0/tcp/30333"]
74+
bootnodes = [] # Add known bootnodes here
75+
max_peers = 50
76+
77+
[chain]
78+
chain_id = "demiurge-mainnet-1"
79+
genesis_path = "/etc/demiurge/genesis.json"
80+
81+
[rpc]
82+
enabled = true
83+
listen_address = "127.0.0.1:9944"
84+
cors = ["*"]
85+
max_connections = 100
86+
87+
[validator]
88+
enabled = true
89+
account = "YOUR_VALIDATOR_ACCOUNT_HEX"
90+
# Generate with: dd if=/dev/urandom bs=32 count=1 2>/dev/null | xxd -p -c 64
91+
92+
[storage]
93+
path = "/var/lib/demiurge/data"
94+
cache_size_mb = 512
95+
96+
[logging]
97+
level = "info"
98+
format = "json"
99+
```
100+
101+
### Create Systemd Service
102+
103+
```ini
104+
# /etc/systemd/system/demiurge-node.service
105+
106+
[Unit]
107+
Description=Demiurge Blockchain Node
108+
After=network.target
109+
110+
[Service]
111+
Type=simple
112+
User=demiurge
113+
Group=demiurge
114+
ExecStart=/usr/local/bin/demiurge-node --config /etc/demiurge/node.toml
115+
Restart=on-failure
116+
RestartSec=10
117+
LimitNOFILE=65535
118+
StandardOutput=journal
119+
StandardError=journal
120+
121+
[Install]
122+
WantedBy=multi-user.target
123+
```
124+
125+
## Deployment Steps
126+
127+
### 1. Create User
128+
129+
```bash
130+
sudo useradd -r -s /bin/false demiurge
131+
sudo mkdir -p /var/lib/demiurge/data
132+
sudo mkdir -p /etc/demiurge
133+
sudo chown -R demiurge:demiurge /var/lib/demiurge
134+
```
135+
136+
### 2. Copy Binaries
137+
138+
```bash
139+
sudo cp target/release/demiurge-node /usr/local/bin/
140+
sudo chmod +x /usr/local/bin/demiurge-node
141+
```
142+
143+
### 3. Copy Configuration
144+
145+
```bash
146+
sudo cp node.toml /etc/demiurge/
147+
sudo cp genesis.json /etc/demiurge/
148+
sudo chown -R demiurge:demiurge /etc/demiurge
149+
```
150+
151+
### 4. Enable Service
152+
153+
```bash
154+
sudo systemctl daemon-reload
155+
sudo systemctl enable demiurge-node
156+
sudo systemctl start demiurge-node
157+
```
158+
159+
### 5. Check Status
160+
161+
```bash
162+
# View logs
163+
sudo journalctl -u demiurge-node -f
164+
165+
# Check status
166+
sudo systemctl status demiurge-node
167+
168+
# Check RPC
169+
curl -H "Content-Type: application/json" \
170+
-d '{"jsonrpc":"2.0","id":1,"method":"chain_getStatus","params":[]}' \
171+
http://localhost:9944
172+
```
173+
174+
## Security Hardening
175+
176+
### Firewall Configuration
177+
178+
```bash
179+
# Allow SSH
180+
sudo ufw allow 22/tcp
181+
182+
# Allow P2P networking
183+
sudo ufw allow 30333/tcp
184+
185+
# Allow RPC (internal only)
186+
# sudo ufw allow from 10.0.0.0/8 to any port 9944
187+
188+
# Enable firewall
189+
sudo ufw enable
190+
```
191+
192+
### Reverse Proxy (Nginx)
193+
194+
```nginx
195+
# /etc/nginx/sites-available/demiurge-rpc
196+
197+
server {
198+
listen 443 ssl http2;
199+
server_name rpc.demiurge.cloud;
200+
201+
ssl_certificate /etc/letsencrypt/live/rpc.demiurge.cloud/fullchain.pem;
202+
ssl_certificate_key /etc/letsencrypt/live/rpc.demiurge.cloud/privkey.pem;
203+
204+
location / {
205+
proxy_pass http://127.0.0.1:9944;
206+
proxy_http_version 1.1;
207+
proxy_set_header Upgrade $http_upgrade;
208+
proxy_set_header Connection "upgrade";
209+
proxy_set_header Host $host;
210+
proxy_set_header X-Real-IP $remote_addr;
211+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
212+
proxy_set_header X-Forwarded-Proto $scheme;
213+
}
214+
}
215+
```
216+
217+
## Monitoring
218+
219+
### Prometheus Metrics
220+
221+
The node exposes Prometheus metrics at `/metrics` on port 9615:
222+
223+
```bash
224+
# Add to Prometheus config
225+
scrape_configs:
226+
- job_name: 'demiurge'
227+
static_configs:
228+
- targets: ['localhost:9615']
229+
```
230+
231+
### Key Metrics
232+
233+
- `demiurge_block_height`: Current block height
234+
- `demiurge_peers_connected`: Number of connected peers
235+
- `demiurge_transactions_processed`: Transaction throughput
236+
- `demiurge_cvp_mutations_verified`: CVP mutations verified
237+
238+
### Alerting Rules
239+
240+
```yaml
241+
groups:
242+
- name: demiurge
243+
rules:
244+
- alert: NodeDown
245+
expr: up{job="demiurge"} == 0
246+
for: 5m
247+
labels:
248+
severity: critical
249+
annotations:
250+
summary: "Demiurge node is down"
251+
252+
- alert: BlockProductionStopped
253+
expr: increase(demiurge_block_height[10m]) == 0
254+
for: 10m
255+
labels:
256+
severity: critical
257+
annotations:
258+
summary: "Block production has stopped"
259+
260+
- alert: LowPeerCount
261+
expr: demiurge_peers_connected < 3
262+
for: 5m
263+
labels:
264+
severity: warning
265+
annotations:
266+
summary: "Low peer count"
267+
```
268+
269+
## Backup Procedures
270+
271+
### Database Backup
272+
273+
```bash
274+
#!/bin/bash
275+
# /etc/cron.daily/demiurge-backup
276+
277+
BACKUP_DIR="/var/backups/demiurge"
278+
DATE=$(date +%Y%m%d_%H%M%S)
279+
280+
# Stop node temporarily
281+
sudo systemctl stop demiurge-node
282+
283+
# Create backup
284+
sudo tar -czf $BACKUP_DIR/demiurge-$DATE.tar.gz /var/lib/demiurge/data
285+
286+
# Start node
287+
sudo systemctl start demiurge-node
288+
289+
# Remove old backups (keep 7 days)
290+
find $BACKUP_DIR -type f -mtime +7 -delete
291+
```
292+
293+
## Upgrade Procedure
294+
295+
### Rolling Upgrade
296+
297+
```bash
298+
# 1. Build new version
299+
cd Demiurge-Blockchain
300+
git pull
301+
cargo build --release
302+
303+
# 2. Stop service
304+
sudo systemctl stop demiurge-node
305+
306+
# 3. Replace binary
307+
sudo cp target/release/demiurge-node /usr/local/bin/
308+
309+
# 4. Start service
310+
sudo systemctl start demiurge-node
311+
312+
# 5. Verify
313+
sudo journalctl -u demiurge-node -f
314+
```
315+
316+
## Troubleshooting
317+
318+
### Common Issues
319+
320+
1. **Node won't start**: Check permissions on data directory
321+
2. **No peers**: Verify firewall rules and bootnode addresses
322+
3. **High memory usage**: Adjust cache_size_mb in config
323+
4. **RPC timeout**: Check Nginx proxy settings
324+
325+
### Log Locations
326+
327+
- Node logs: `journalctl -u demiurge-node`
328+
- Nginx logs: `/var/log/nginx/access.log`
329+
- System logs: `/var/log/syslog`
330+
331+
## Contact
332+
333+
- GitHub: https://github.com/ALaustrup/Demiurge-Blockchain
334+
- Discord: https://discord.gg/demiurge
335+
- Documentation: https://docs.demiurge.cloud

0 commit comments

Comments
 (0)