OverviewFilesCommitsIssuesDocsReleasesPeers

server-info-kb commits / f28b120

Initial commit: Server infrastructure documentation
7rnx.net deployment: - Complete server audit - Hyperident-gateway systemd service - Apache reverse proxy configuration - SSL/TLS setup - Firewall rules - Git daemon configuration Tabertron setup: - Wirecore deployment - Hyperident-gateway client - P2P gateway network (10.22.0.0/16) Deployment procedures: - Step-by-step commands - Troubleshooting notes - Pear vs Git deployment options Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
f28b12013a6538fdaee56230462fb85ca5039e07
by plankatron <fleeky@gmail.com> · 2026-01-18T21:12:54.000Z

Changed files (16) +3346 -0

7rnx.net/000-default-le-ssl.conf +54 -0
……@@ -0,0 +1,54 @@
1<IfModule mod_ssl.c>
2<VirtualHost *:443>
3 # The ServerName directive sets the request scheme, hostname and port that
4 # the server uses to identify itself. This is used when creating
5 # redirection URLs. In the context of virtual hosts, the ServerName
6 # specifies what hostname must appear in the request's Host: header to
7 # match this virtual host. For the default virtual host (this file) this
8 # value is not decisive as it is used as a last resort host regardless.
9 # However, you must set it for any further virtual host explicitly.
10 #ServerName www.example.com
11
12 ServerAdmin webmaster@localhost
13 DocumentRoot /var/www/
14
15 # Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
16 # error, crit, alert, emerg.
17 # It is also possible to configure the loglevel for particular
18 # modules, e.g.
19 #LogLevel info ssl:warn
20
21 ErrorLog ${APACHE_LOG_DIR}/error.log
22 CustomLog ${APACHE_LOG_DIR}/access.log combined
23
24 # For most configuration files from conf-available/, which are
25 # enabled or disabled at a global level, it is possible to
26 # include a line for only one particular virtual host. For example the
27 # following line enables the CGI configuration for this host only
28 # after it has been globally disabled with "a2disconf".
29 #Include conf-available/serve-cgi-bin.conf
30
31 ServerName 7rnx.net
32 SSLCertificateFile /etc/letsencrypt/live/7rnx.net-0001/fullchain.pem
33 SSLCertificateKeyFile /etc/letsencrypt/live/7rnx.net-0001/privkey.pem
34 Include /etc/letsencrypt/options-ssl-apache.conf
35
36 # Proxy /fedicore to tabertron via P2P gateway (10.22.0.1:3000)
37 # Note: No trailing slash to handle both /fedicore and /fedicore/
38 <Location /fedicore>
39 ProxyPass http://10.22.0.1:3000
40 ProxyPassReverse http://10.22.0.1:3000
41 ProxyPreserveHost Off
42
43 # Headers for proxy
44 RequestHeader set X-Forwarded-Proto "https"
45 RequestHeader set X-Forwarded-Port "443"
46 RequestHeader set X-Forwarded-Prefix "/fedicore"
47 </Location>
48
49 # WebSocket proxy for /fedicore
50 RewriteEngine On
51 RewriteCond %{HTTP:Upgrade} =websocket [NC]
52 RewriteRule ^/fedicore(.*)$ ws://10.22.0.1:3000$1 [P,L]
53</VirtualHost>
54</IfModule>
7rnx.net/7RNX_SERVER_AUDIT.md +376 -0
……@@ -0,0 +1,376 @@
1# 7rnx.net Server Audit & Current State
2
3**Date**: 2026-01-18
4**Server**: 7rntst (hostname), 7rnx.net (domain)
5
6---
7
8## System Information
9
10### Hardware/OS
11- **OS**: Debian GNU/Linux 12 (bookworm)
12- **Hostname**: 7rntst
13- **RAM**: 1.9GB (1.5GB available)
14- **Swap**: None
15- **Disk**: 59GB total, 15GB used, 42GB free (27% used)
16- **CPU**: 2 cores
17
18### Network
19- **Public IPv4**: 142.93.23.112
20- **Private IP**: 10.46.0.5/16 (eth0)
21- **Tunnel Device**: tunnel0 exists! IP: 10.22.0.3/16
22 - This suggests gateway ran at some point and created TUN device
23 - Device persists even though service is down
24
25### DNS
26- **Domain**: 7rnx.net (no DNS tool installed to verify)
27- **Subdomain**: fedicore.7rnx.net (NOT configured yet)
28
29---
30
31## Installed Software
32
33### Development Tools
34- **Git**: ✅ Installed (`/usr/bin/git`)
35- **Node.js**: ✅ v23.2.0 (via NVM, not in system PATH)
36- **npm**: ✅ v11.3.0 (via NVM)
37- **Bare runtime**: ❌ NOT in PATH (but Pear has its own)
38- **Pear**: ✅ Installed at `~/.config/pear/bin/pear`
39
40### Web Servers
41- **nginx**: ❌ Not installed
42- **apache2**: ❌ Not installed
43- **caddy**: ❌ Not installed
44- **Reverse proxy**: ❌ NONE - needs to be installed
45
46### Firewall
47- **Status**: Unknown (no sudo access to check iptables/ufw)
48- **Ports**: Assumed open (no evidence of strict firewall)
49
50---
51
52## Hyperident-Gateway Status
53
54### systemd Service
55
56**Status**: 🔴 **INACTIVE (DEAD)**
57
58```
59Service: hyperident-gateway.service
60Enabled: YES (auto-starts on boot)
61Active: NO (stopped since 2026-01-18 02:06:21 UTC)
62```
63
64**Service Configuration**:
65```ini
66[Service]
67Type=simple
68User=fleeky
69Group=fleeky
70WorkingDirectory=/home/fleeky
71ExecStart=/home/fleeky/.config/pear/bin/pear run pear://hdj3chnrp8wnfzq4b3fd9i1jhuha1ufeyces35oofyteh6csfsmy
72```
73
74**Key Points**:
75- ✅ Runs as non-root user (fleeky) with CAP_NET_ADMIN capability
76- ✅ Uses Pear runtime (NOT direct Bare execution)
77- 🔴 **CURRENTLY FAILING** with MODULE_NOT_FOUND
78
79---
80
81### Failure Analysis
82
83**Error**: `MODULE_NOT_FOUND: Cannot find module 'utun'`
84
85```
86Jan 18 02:06:09 7rntst pear[1150027]: Uncaught ModuleError: MODULE_NOT_FOUND:
87Cannot find module 'utun' imported from
88'pear://hdj3chnrp8wnfzq4b3fd9i1jhuha1ufeyces35oofyteh6csfsmy/lib/utun-manager.js
89```
90
91**Root Cause**: Pear package missing `utun` dependency
92- This is the EXACT issue from `pear-deployment-lessons.md`!
93- Pear's static analysis missed the `utun` native module
94- The staged Pear app doesn't include this dependency
95
96**Why tunnel0 exists**: Previous successful run created it, device persists after crash
97
98---
99
100### Local Gateway Directory
101
102**Location**: `/home/fleeky/hyperident-gateway/`
103
104**Status**: ✅ Complete source code with dependencies
105
106```
107hyperident-gateway/
108├── gateway.js # Main entry point
109├── lib/ # Core modules
110│ ├── gateway-identity.js
111│ ├── utun-manager.js
112│ └── hyperswarm-router.js
113├── node_modules/ # ✅ Dependencies installed (including utun!)
114├── package.json # Has Pear config
115└── config/ # Separate: ~/hyperident-config/
116```
117
118**Important**: This is NOT a git repo (no .git directory)
119- Likely copied/extracted from somewhere
120- No version control
121
122---
123
124### Gateway Configuration
125
126**File**: `/home/fleeky/hyperident-config/gateway-config.json`
127
128```json
129{
130 "version": "1.0.0",
131 "gateway": {
132 "virtualIP": "10.22.0.3",
133 "subnet": "10.22.0.0/16",
134 "tunDevice": "tun0",
135 "mtu": 1500,
136 "networkTopic": "hyperident-network"
137 }
138}
139```
140
141**Key Points**:
142- Gateway assigns itself IP: 10.22.0.3
143- Subnet: 10.22.0.0/16 (65,536 IPs available)
144- No services configured (no fedicore mapping)
145- Uses "tun0" but created "tunnel0" (mismatch?)
146
147---
148
149## What's Missing
150
151### Critical
1521. ❌ **Reverse proxy** (nginx/caddy) - not installed
1532. ❌ **Fedicore** - not deployed anywhere on this server
1543. ❌ **Working gateway** - service failing, needs fix
155
156### Nice to Have
1571. ❌ DNS tools (dig/host) for troubleshooting
1582. ❌ Firewall status unclear
1593. ❌ Monitoring/health checks
1604. ❌ Backup system
161
162---
163
164## Other Findings
165
166### PM2
167- **.pm2/** directory exists but no processes running
168- Was PM2 used for something before?
169
170### Public Directory
171- **~/public/** contains:
172 - fleeky-monotome/
173 - gescom/
174 - mauvepup/
175- Looks like static site content (unrelated to hypercore)
176
177### Drives
178- **~/.drives/corestore/** exists
179- Hypercore storage from previous experiments?
180
181---
182
183## Deployment Strategy Clarification
184
185### Current Architecture (What User Asked)
186
187```
188Internet User
189 ↓ HTTPS
190Reverse Proxy (caddy) ← [NEEDS INSTALLATION on 7rnx.net]
191 ↓ HTTP to virtual IP
192Hyperident-Gateway (10.22.0.3) ← [EXISTS but BROKEN on 7rnx.net]
193 ↓ Hyperswarm P2P
194Hyperident-Gateway (laptop) ← [Would need installation]
195 ↓ localhost
196Fedicore (laptop:3000) ← [Would run on laptop]
197```
198
199**Question from User**: "we need to setup a reverse proxy with hyperident-gateway to expose a fedicore instance on a laptop? am i right about that?"
200
201**Answer**: YES, exactly right! But there are two deployment options:
202
203---
204
205## Deployment Options
206
207### Option A: Fedicore on Laptop (via P2P Gateway)
208
209**Architecture**:
210```
211[7rnx.net Server] [Your Laptop]
212Caddy (HTTPS) →
213Gateway (10.22.0.x) → [P2P] → Gateway (10.22.0.y) →
214 Fedicore (localhost:3000)
215```
216
217**Pros**:
218- ✅ Fedicore data stays on laptop
219- ✅ True test of P2P gateway routing
220- ✅ Can develop locally, expose publicly
221
222**Cons**:
223- ⚠️ Laptop must stay online
224- ⚠️ Two gateways to configure/maintain
225- ⚠️ Higher latency (P2P hop)
226
227**What Needs To Happen**:
2281. Fix gateway on 7rnx.net (Pear packaging or run from source)
2292. Install/configure gateway on laptop
2303. Install caddy on 7rnx.net
2314. Run fedicore on laptop
2325. Configure DNS (fedicore.7rnx.net → 142.93.23.112)
233
234---
235
236### Option B: Fedicore on 7rnx.net (Simpler)
237
238**Architecture**:
239```
240[7rnx.net Server]
241Caddy (HTTPS) →
242Gateway (10.22.0.5) →
243Fedicore (localhost:3000)
244```
245
246**Pros**:
247- ✅ Simpler setup (one machine)
248- ✅ Lower latency (no P2P hop for HTTP)
249- ✅ Always online (server uptime)
250- ✅ Easier to debug
251
252**Cons**:
253- ⚠️ Data on remote server (but backed up)
254- ⚠️ Less interesting (not testing P2P gateway fully)
255
256**What Needs To Happen**:
2571. Fix gateway on 7rnx.net
2582. Deploy fedicore on 7rnx.net
2593. Install caddy on 7rnx.net
2604. Configure DNS
261
262---
263
264## Immediate Next Steps
265
266### 1. Fix Hyperident-Gateway (CRITICAL)
267
268Two approaches:
269
270**A. Fix Pear Package** (harder, educational):
271```bash
272# On dev machine with gateway source
273cd hyperident-gateway
274npm install # Ensure utun is in node_modules
275npm prune --production
276# Make sure node_modules is NOT ignored
277pear stage --json
278# New pear:// link with utun included
279# Update systemd service to new link
280```
281
282**B. Run from Source** (easier, works now):
283```bash
284# On 7rnx.net
285cd ~/hyperident-gateway
286
287# Stop Pear-based service
288sudo systemctl stop hyperident-gateway
289sudo systemctl disable hyperident-gateway
290
291# Run directly with Bare (if installed)
292# OR run with Node.js (since gateway uses bare-* modules that work in Node)
293sudo node gateway.js --config ~/hyperident-config/gateway-config.json
294
295# Or: Create new systemd service that runs from source
296```
297
298---
299
300### 2. Install Reverse Proxy
301
302```bash
303# On 7rnx.net
304sudo apt-get update
305sudo apt-get install -y caddy
306
307# Configure Caddyfile (after gateway working)
308```
309
310---
311
312### 3. Deploy Fedicore (Choose Option A or B)
313
314**Option A** (laptop):
315- Install gateway on laptop
316- Run fedicore on laptop
317- Configure gateway to expose it
318
319**Option B** (7rnx.net):
320- Clone fedicore to 7rnx.net
321- Install dependencies
322- Configure gateway to expose it
323- Create systemd service
324
325---
326
327## Recommended Path Forward
328
329**For Testing/Learning** (Option A):
3301. Fix gateway on 7rnx.net (run from source)
3312. Install gateway on laptop
3323. Run fedicore on laptop
3334. Test P2P routing works
3345. Install caddy
3356. Expose via HTTPS
336
337**For Production** (Option B):
3381. Fix gateway on 7rnx.net
3392. Deploy fedicore on 7rnx.net
3403. Install caddy
3414. Expose via HTTPS
3425. Done! (simpler)
343
344---
345
346## Questions to Answer
347
3481. **Which deployment option?** A (laptop) or B (server)?
3492. **Gateway fix method?** Pear repackage or run from source?
3503. **TUN device name?** Config says "tun0" but created "tunnel0" - which is correct?
3514. **DNS configured?** Need to add fedicore.7rnx.net A record
352
353---
354
355## Summary
356
357**Current State**:
358- 🔴 Gateway systemd service exists but FAILING (Pear MODULE_NOT_FOUND)
359- ✅ Gateway source code available locally with all dependencies
360- ✅ TUN device exists (tunnel0) from previous run
361- ❌ No reverse proxy installed
362- ❌ No fedicore deployed
363- ❌ No DNS for subdomain
364
365**Not Running via systemd?**: Actually it IS configured as systemd service, just failing to start
366
367**Test vs Production**: Current setup looks like testing/development (Pear packaging issues, no production hardening)
368
369**Next Step**: Decide deployment strategy (laptop vs server) then fix gateway
370
371---
372
373**Status**: Server audited, issues identified, ready for deployment decision
374**Blocker**: Gateway not working due to Pear packaging issue
375
376Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7rnx.net/7rnx-hyperident-gateway.md +369 -0
……@@ -0,0 +1,369 @@
1# Hyperident-Gateway Deployment on 7rnx.net
2
3**Date**: 2026-01-18
4**Server**: 7rnx.net (Debian 12)
5**Goal**: Deploy hyperident-gateway as systemd service running from source without sudo
6
7---
8
9## Current State
10
11- **Gateway Source**: `/home/fleeky/hyperident-gateway/` (complete with dependencies)
12- **Config File**: `/home/fleeky/hyperident-config/gateway-config.json`
13- **Bare Binary**: `/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare`
14- **Previous Service**: Pear-based service was failing (MODULE_NOT_FOUND: utun)
15- **Manual Test**: Gateway runs with sudo, creates tunnel0 device at 10.22.0.3/16
16
17---
18
19## Step 1: Install Required Packages
20
21The `setcap` and `getcap` commands need the libcap2-bin package.
22
23```bash
24ssh 7rnx.net
25sudo apt-get update
26sudo apt-get install -y libcap2-bin
27```
28
29**Verify installation**:
30```bash
31which setcap
32which getcap
33```
34
35Expected: Both should return paths like `/usr/sbin/setcap`
36
37---
38
39## Step 2: Set Linux Capability on Bare Binary
40
41This allows the bare binary to create TUN devices without running as root.
42
43```bash
44# Define the bare binary path (long path!)
45BARE_BIN="/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare"
46
47# Verify binary exists
48ls -la "$BARE_BIN"
49```
50
51Expected: Shows the bare executable file
52
53```bash
54# Set the capability
55sudo setcap cap_net_admin+eip "$BARE_BIN"
56```
57
58**Verify capability was set**:
59```bash
60getcap "$BARE_BIN"
61```
62
63Expected output: `/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare cap_net_admin=eip`
64
65---
66
67## Step 3: Test Gateway Without Sudo
68
69Before creating the service, test that the gateway can run without sudo.
70
71```bash
72# Go to gateway directory
73cd /home/fleeky/hyperident-gateway
74
75# Run gateway (without sudo!)
76$BARE_BIN gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
77```
78
79**Expected behavior**:
80- No "Operation not permitted" errors
81- Logs show "Gateway starting..." or similar
82- Press Ctrl+C to stop after verifying it starts
83
84**Check TUN device was created**:
85```bash
86ip addr show tunnel0
87```
88
89Expected: Shows tunnel0 interface with IP like `10.22.0.3/16`
90
91**If you see errors**:
92- "Operation not permitted": Capability not set correctly, repeat Step 2
93- "MODULE_NOT_FOUND": Wrong directory or missing node_modules
94- "Config file not found": Check config path
95
96---
97
98## Step 4: Stop Any Running Gateway Processes
99
100Before setting up the service, make sure no other gateway is running.
101
102```bash
103# Check for running gateway processes
104ps aux | grep gateway.js
105
106# If found, kill them
107sudo pkill -f gateway.js
108
109# Check if old systemd service is running
110sudo systemctl status hyperident-gateway
111```
112
113If the old service exists and is running:
114```bash
115sudo systemctl stop hyperident-gateway
116sudo systemctl disable hyperident-gateway
117```
118
119---
120
121## Step 5: Create Systemd Service File
122
123Create the service file at `/etc/systemd/system/hyperident-gateway.service`:
124
125```bash
126sudo nano /etc/systemd/system/hyperident-gateway.service
127```
128
129**Paste this content**:
130
131```ini
132[Unit]
133Description=Hyperident Gateway - P2P VPN
134Documentation=/home/fleeky/hyperident-gateway/README.md
135After=network-online.target
136Wants=network-online.target
137
138[Service]
139Type=simple
140User=fleeky
141Group=fleeky
142WorkingDirectory=/home/fleeky/hyperident-gateway
143
144# Full path to bare binary (with CAP_NET_ADMIN capability)
145ExecStart=/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
146
147# Restart policy
148Restart=always
149RestartSec=10
150
151# Security settings
152NoNewPrivileges=true
153PrivateTmp=true
154
155# Logging
156StandardOutput=journal
157StandardError=journal
158SyslogIdentifier=hyperident-gateway
159
160[Install]
161WantedBy=multi-user.target
162```
163
164Save and exit (Ctrl+X, Y, Enter in nano)
165
166**Verify file was created**:
167```bash
168cat /etc/systemd/system/hyperident-gateway.service
169```
170
171---
172
173## Step 6: Enable and Start Service
174
175```bash
176# Reload systemd to recognize new service
177sudo systemctl daemon-reload
178
179# Enable service to start on boot
180sudo systemctl enable hyperident-gateway
181
182# Start the service
183sudo systemctl start hyperident-gateway
184```
185
186---
187
188## Step 7: Verify Service is Running
189
190```bash
191# Check service status
192sudo systemctl status hyperident-gateway
193```
194
195**Expected output**:
196```
197● hyperident-gateway.service - Hyperident Gateway - P2P VPN
198 Loaded: loaded (/etc/systemd/system/hyperident-gateway.service; enabled)
199 Active: active (running) since ...
200```
201
202**Check the process**:
203```bash
204ps aux | grep gateway.js
205```
206
207Expected: Shows process running as user `fleeky` (not root)
208
209**Check TUN device**:
210```bash
211ip addr show tunnel0
212```
213
214Expected: Shows tunnel0 with IP `10.22.0.3/16`
215
216**View logs**:
217```bash
218sudo journalctl -u hyperident-gateway -n 50
219```
220
221Expected: Shows gateway startup messages, no errors
222
223**Follow logs in real-time**:
224```bash
225sudo journalctl -u hyperident-gateway -f
226```
227
228Press Ctrl+C to stop following
229
230---
231
232## Step 8: Test Service Survives Reboot
233
234```bash
235# Reboot server
236sudo reboot
237```
238
239Wait 1-2 minutes, then SSH back in:
240
241```bash
242ssh 7rnx.net
243
244# Check service auto-started
245sudo systemctl status hyperident-gateway
246
247# Check tunnel device
248ip addr show tunnel0
249```
250
251Expected: Service running, tunnel0 exists
252
253---
254
255## Troubleshooting
256
257### Service Fails to Start
258
259```bash
260# View detailed logs
261sudo journalctl -u hyperident-gateway -n 100 --no-pager
262
263# Common issues:
264# 1. Permission denied on TUN: Check capabilities (Step 2)
265# 2. Config file not found: Verify path in service file
266# 3. Module not found: Check node_modules in gateway directory
267```
268
269### Gateway Running But No TUN Device
270
271```bash
272# Check if another process has the TUN device
273sudo lsof | grep tun
274
275# Check gateway logs for errors
276sudo journalctl -u hyperident-gateway -f
277```
278
279### Service Won't Stop
280
281```bash
282# Force stop
283sudo systemctl stop hyperident-gateway
284sudo pkill -9 -f gateway.js
285
286# Restart
287sudo systemctl start hyperident-gateway
288```
289
290---
291
292## Service Management Commands
293
294```bash
295# Start service
296sudo systemctl start hyperident-gateway
297
298# Stop service
299sudo systemctl stop hyperident-gateway
300
301# Restart service
302sudo systemctl restart hyperident-gateway
303
304# View status
305sudo systemctl status hyperident-gateway
306
307# View logs (last 50 lines)
308sudo journalctl -u hyperident-gateway -n 50
309
310# View logs (follow)
311sudo journalctl -u hyperident-gateway -f
312
313# View logs (since 1 hour ago)
314sudo journalctl -u hyperident-gateway --since "1 hour ago"
315
316# Disable auto-start
317sudo systemctl disable hyperident-gateway
318
319# Enable auto-start
320sudo systemctl enable hyperident-gateway
321```
322
323---
324
325## What This Achieves
326
327✅ **Gateway runs without sudo** - Uses Linux capabilities instead
328✅ **Runs from source** - Uses /home/fleeky/hyperident-gateway/ not Pear package
329✅ **Auto-starts on boot** - systemd manages the service
330✅ **Auto-restarts on failure** - Restart policy in service file
331✅ **Proper logging** - Logs to journald
332✅ **Runs as user fleeky** - Not root, more secure
333
334---
335
336## Next Steps
337
338After gateway service is working:
339
3401. **Configure Apache reverse proxy** - Proxy fedicore.7rnx.net to 10.22.0.5:3000
3412. **Check firewall rules** - Ensure ports 80, 443, 49737 allowed
3423. **Setup DNS** - Add A record for fedicore.7rnx.net → 142.93.23.112
3434. **Get SSL certificate** - Use certbot for Let's Encrypt
3445. **Deploy laptop gateway** - Connect P2P to server gateway
3456. **Run fedicore on laptop** - Make accessible at 10.22.0.5:3000
346
347---
348
349## Notes for Other Nodes
350
351To deploy on another server:
352
3531. Ensure bare runtime installed with same path structure
3542. Copy hyperident-gateway source code
3553. Create config file at /home/[user]/hyperident-config/gateway-config.json
3564. Follow steps 1-7 above (adjust paths for different user/installation)
3575. Update IP addresses in config for different subnet if needed
358
359The key is:
360- **Bare binary with CAP_NET_ADMIN capability**
361- **Service runs from source directory with all dependencies**
362- **Config file path must match ExecStart in service file**
363
364---
365
366**Status**: Ready for manual validation
367**Next**: Follow these steps on 7rnx.net, note any issues, then create automation script
368
369Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7rnx.net/7rnx-servername.conf +2 -0
……@@ -0,0 +1,2 @@
1# Global ServerName directive to suppress Apache warning
2ServerName 7rnx.net
7rnx.net/APACHE_PROXY_SETUP.md +230 -0
……@@ -0,0 +1,230 @@
1# Apache Reverse Proxy Setup for Fedicore
2
3**Date**: 2026-01-18
4**Server**: 7rnx.net
5**Goal**: Proxy https://7rnx.net/fedicore/ to http://10.22.0.1:3000 (tabertron via P2P)
6
7---
8
9## Step 1: Enable Apache Modules
10
11On 7rnx.net, enable required proxy modules:
12
13```bash
14sudo a2enmod proxy
15sudo a2enmod proxy_http
16sudo a2enmod proxy_wstunnel
17sudo a2enmod headers
18sudo a2enmod rewrite
19```
20
21Expected output: Modules may already be enabled, or will show "Enabling module..."
22
23---
24
25## Step 2: Edit SSL Virtual Host
26
27Edit the SSL configuration file:
28
29```bash
30sudo nano /etc/apache2/sites-available/000-default-le-ssl.conf
31```
32
33**Find the line** (near the end):
34```apache
35</VirtualHost>
36```
37
38**Add this BEFORE the `</VirtualHost>` closing tag**:
39
40```apache
41 # Proxy /fedicore/ to tabertron via P2P gateway (10.22.0.1:3000)
42 <Location /fedicore/>
43 ProxyPass http://10.22.0.1:3000/
44 ProxyPassReverse http://10.22.0.1:3000/
45 ProxyPreserveHost Off
46
47 # WebSocket support
48 RewriteEngine On
49 RewriteCond %{HTTP:Upgrade} =websocket [NC]
50 RewriteRule /fedicore/(.*) ws://10.22.0.1:3000/$1 [P,L]
51
52 # Headers for proxy
53 RequestHeader set X-Forwarded-Proto "https"
54 RequestHeader set X-Forwarded-Port "443"
55 RequestHeader set X-Forwarded-Prefix "/fedicore"
56 </Location>
57```
58
59Save and exit (Ctrl+X, Y, Enter in nano).
60
61---
62
63## Step 3: Test Apache Configuration
64
65```bash
66sudo apache2ctl configtest
67```
68
69Expected output:
70```
71Syntax OK
72```
73
74If you see errors, check that the `<Location>` block is properly indented and before `</VirtualHost>`.
75
76---
77
78## Step 4: Reload Apache
79
80```bash
81sudo systemctl reload apache2
82```
83
84Check Apache is still running:
85
86```bash
87sudo systemctl status apache2
88```
89
90Expected: `active (running)`
91
92---
93
94## Step 5: Test Reverse Proxy
95
96### Test from 7rnx.net server:
97
98```bash
99curl -I https://7rnx.net/fedicore/
100```
101
102Expected: HTTP 200 response with HTML content
103
104### Test full HTML:
105
106```bash
107curl https://7rnx.net/fedicore/ | head -20
108```
109
110Expected: Fedicore HTML (should include "Fedicore" in title or content)
111
112---
113
114## Step 6: Test from Internet
115
116From your local machine (or browser):
117
118```bash
119curl -I https://7rnx.net/fedicore/
120```
121
122Or open in browser:
123```
124https://7rnx.net/fedicore/
125```
126
127Expected: Fedicore web interface loads
128
129---
130
131## Troubleshooting
132
133### 502 Bad Gateway
134
135**Possible causes**:
1361. Fedicore not running on tabertron
1372. P2P gateway down
1383. Network routing issue
139
140**Check**:
141```bash
142# From 7rnx.net
143ping 10.22.0.1
144curl http://10.22.0.1:3000/
145
146# Check gateway logs
147sudo journalctl -u hyperident-gateway -n 50
148```
149
150### 404 Not Found
151
152**Possible cause**: Apache config not loaded
153
154**Fix**:
155```bash
156sudo apache2ctl configtest
157sudo systemctl reload apache2
158```
159
160### WebSocket Connection Failed
161
162**Possible cause**: mod_proxy_wstunnel not enabled
163
164**Fix**:
165```bash
166sudo a2enmod proxy_wstunnel
167sudo systemctl reload apache2
168```
169
170### Apache Won't Start
171
172**Check syntax**:
173```bash
174sudo apache2ctl configtest
175```
176
177**View errors**:
178```bash
179sudo journalctl -u apache2 -n 50
180```
181
182---
183
184## Configuration Summary
185
186**Public URL**: https://7rnx.net/fedicore/
187**Proxy Target**: http://10.22.0.1:3000
188**Transport**: HTTPS → Apache → P2P Gateway → Fedicore
189
190**Flow**:
191```
192Internet User
193 ↓ HTTPS
194https://7rnx.net/fedicore/
195 ↓ Apache SSL (port 443)
196Apache Reverse Proxy
197 ↓ HTTP (via P2P network)
198http://10.22.0.1:3000
199 ↓ Hyperident P2P Gateway
200Tabertron (10.22.0.1)
201 ↓ Local HTTP
202Fedicore (localhost:3000)
203```
204
205---
206
207## Apache Modules Required
208
209- ✅ mod_proxy - Core proxy functionality
210- ✅ mod_proxy_http - HTTP proxy support
211- ✅ mod_proxy_wstunnel - WebSocket proxy support
212- ✅ mod_headers - Header manipulation
213- ✅ mod_rewrite - URL rewriting for WebSocket upgrade
214- ✅ mod_ssl - Already enabled (for HTTPS)
215
216---
217
218## Security Notes
219
220- Proxy runs over P2P network (encrypted via Hyperswarm)
221- HTTPS on public side (SSL cert from Let's Encrypt)
222- No direct exposure of tabertron to internet
223- Fedicore only accessible via P2P gateway
224
225---
226
227**Status**: Ready to configure
228**Next**: Run commands on 7rnx.net server
229
230Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7rnx.net/DEPLOYMENT_COMMANDS.md +433 -0
……@@ -0,0 +1,433 @@
1# Hyperident-Gateway Deployment - Exact Commands
2
3**Date**: 2026-01-18
4**Server**: 7rnx.net (Debian 12)
5**HTTP Server**: Apache2 (ports 80, 443, 8083)
6**Goal**: Deploy hyperident-gateway via Pear, run as systemd service, expose fedicore at 7rnx.net/fedicore/
7
8---
9
10## Overview: Pear-Based Deployment
11
12This deployment uses Pear packaging for distribution:
131. **Install Pear runtime** (if not installed)
142. **Get gateway via Pear** (pear run or pear dump)
153. **Setup systemd service** to run gateway
164. **Configure Apache** to proxy /fedicore/ path to gateway virtual IP
175. **Test** end-to-end connectivity
18
19---
20
21## Part 1: Verify Pear Runtime
22
23SSH into server:
24```bash
25ssh 7rnx.net
26```
27
28Check if Pear is installed:
29```bash
30pear
31```
32
33Expected: Shows Pear welcome message with version (e.g., `🍐 v0.9609...`)
34
35**Note**: Pear is already installed on 7rnx.net, skip installation.
36
37---
38
39## Part 2: Get Hyperident-Gateway via Pear
40
41### Option A: Use Existing Source (Current State)
42
43The gateway already exists at `/home/fleeky/hyperident-gateway/` with all dependencies.
44
45Verify it exists:
46```bash
47ls -la /home/fleeky/hyperident-gateway/gateway.js
48ls -la /home/fleeky/hyperident-gateway/node_modules/utun
49```
50
51If both exist, proceed to Part 3.
52
53### Option B: Install via Pear (Future Production Method)
54
55When Pear package is ready:
56```bash
57# Stage/dump Pear package to local directory
58pear dump pear://[GATEWAY_PEAR_KEY] /home/fleeky/hyperident-gateway-pear
59
60# Or run directly (for testing)
61pear run pear://[GATEWAY_PEAR_KEY]
62```
63
64**Note**: Currently using Option A (existing source). Will transition to Pear distribution later.
65
66---
67
68## Part 3: Setup Linux Capabilities (Required for Non-Root TUN)
69
70Install capability tools:
71```bash
72sudo apt-get update
73sudo apt-get install -y libcap2-bin
74```
75
76Set capability on bare binary:
77```bash
78sudo setcap cap_net_admin+eip /home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare
79```
80
81Verify capability:
82```bash
83getcap /home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare
84```
85
86Expected output:
87```
88/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare cap_net_admin=eip
89```
90
91---
92
93## Part 4: Test Gateway Without Sudo
94
95Test that gateway runs without sudo:
96```bash
97cd /home/fleeky/hyperident-gateway
98/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
99```
100
101Expected: Gateway starts, no permission errors. Press Ctrl+C to stop.
102
103Check TUN device was created:
104```bash
105ip addr show tunnel0
106```
107
108Expected output includes:
109```
110inet 10.22.0.3/16
111```
112
113---
114
115## Part 5: Stop Any Existing Gateway
116
117Stop old systemd service (if running):
118```bash
119sudo systemctl stop hyperident-gateway
120sudo systemctl disable hyperident-gateway
121```
122
123Kill any running gateway processes:
124```bash
125sudo pkill -f gateway.js
126```
127
128Verify nothing running:
129```bash
130ps aux | grep gateway.js
131```
132
133---
134
135## Part 6: Create Systemd Service
136
137Create service file:
138```bash
139sudo tee /etc/systemd/system/hyperident-gateway.service > /dev/null << 'EOF'
140[Unit]
141Description=Hyperident Gateway - P2P VPN
142Documentation=/home/fleeky/hyperident-gateway/README.md
143After=network-online.target
144Wants=network-online.target
145
146[Service]
147Type=simple
148User=fleeky
149Group=fleeky
150WorkingDirectory=/home/fleeky/hyperident-gateway
151ExecStart=/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
152Restart=always
153RestartSec=10
154NoNewPrivileges=true
155PrivateTmp=true
156StandardOutput=journal
157StandardError=journal
158SyslogIdentifier=hyperident-gateway
159
160[Install]
161WantedBy=multi-user.target
162EOF
163```
164
165Verify file created:
166```bash
167cat /etc/systemd/system/hyperident-gateway.service
168```
169
170---
171
172## Part 7: Enable and Start Service
173
174Reload systemd:
175```bash
176sudo systemctl daemon-reload
177```
178
179Enable service (start on boot):
180```bash
181sudo systemctl enable hyperident-gateway
182```
183
184Start service:
185```bash
186sudo systemctl start hyperident-gateway
187```
188
189Check status:
190```bash
191sudo systemctl status hyperident-gateway
192```
193
194Expected output:
195```
196● hyperident-gateway.service - Hyperident Gateway - P2P VPN
197 Loaded: loaded (/etc/systemd/system/hyperident-gateway.service; enabled)
198 Active: active (running) since ...
199```
200
201---
202
203## Part 8: Verify Gateway Running
204
205Check process:
206```bash
207ps aux | grep gateway.js
208```
209
210Expected: Process running as user `fleeky`
211
212Check TUN device:
213```bash
214ip addr show tunnel0
215```
216
217Expected: Shows `inet 10.22.0.3/16`
218
219View logs:
220```bash
221sudo journalctl -u hyperident-gateway -n 50
222```
223
224Follow logs:
225```bash
226sudo journalctl -u hyperident-gateway -f
227```
228
229Press Ctrl+C to stop following.
230
231---
232
233## Part 9: Configure Apache Reverse Proxy
234
235Enable required Apache modules:
236```bash
237sudo a2enmod proxy
238sudo a2enmod proxy_http
239sudo a2enmod proxy_wstunnel
240sudo a2enmod headers
241```
242
243Reload Apache:
244```bash
245sudo systemctl reload apache2
246```
247
248Edit SSL virtual host to add /fedicore/ proxy:
249```bash
250sudo nano /etc/apache2/sites-available/000-default-le-ssl.conf
251```
252
253**Add this BEFORE the closing `</VirtualHost>` tag:**
254
255```apache
256 # Proxy /fedicore/ to gateway virtual IP
257 <Location /fedicore/>
258 ProxyPass http://10.22.0.5:3000/
259 ProxyPassReverse http://10.22.0.5:3000/
260 ProxyPreserveHost Off
261
262 # WebSocket support
263 RewriteEngine On
264 RewriteCond %{HTTP:Upgrade} =websocket [NC]
265 RewriteRule /fedicore/(.*) ws://10.22.0.5:3000/$1 [P,L]
266
267 # Headers
268 RequestHeader set X-Forwarded-Proto "https"
269 RequestHeader set X-Forwarded-Port "443"
270 RequestHeader set X-Forwarded-Prefix "/fedicore"
271 </Location>
272```
273
274Save file (Ctrl+X, Y, Enter).
275
276Test Apache configuration:
277```bash
278sudo apache2ctl configtest
279```
280
281Expected: `Syntax OK`
282
283Reload Apache:
284```bash
285sudo systemctl reload apache2
286```
287
288---
289
290## Part 10: Verify Reverse Proxy (After Fedicore Running)
291
292Once fedicore is running on laptop at 10.22.0.5:3000, test the proxy:
293
294```bash
295curl -I https://7rnx.net/fedicore/
296```
297
298Expected: HTTP 200 response from fedicore
299
300---
301
302## Part 11: Check Firewall
303
304Check if UFW is active:
305```bash
306sudo ufw status
307```
308
309If active, ensure required ports are allowed:
310```bash
311sudo ufw allow 22/tcp # SSH
312sudo ufw allow 80/tcp # HTTP
313sudo ufw allow 443/tcp # HTTPS
314sudo ufw allow 49737/udp # Hyperswarm DHT
315```
316
317If using iptables directly:
318```bash
319sudo iptables -L -n -v
320```
321
322Ensure ports 22, 80, 443, 49737 are allowed.
323
324---
325
326## Service Management Commands
327
328Start service:
329```bash
330sudo systemctl start hyperident-gateway
331```
332
333Stop service:
334```bash
335sudo systemctl stop hyperident-gateway
336```
337
338Restart service:
339```bash
340sudo systemctl restart hyperident-gateway
341```
342
343View status:
344```bash
345sudo systemctl status hyperident-gateway
346```
347
348View logs (last 50 lines):
349```bash
350sudo journalctl -u hyperident-gateway -n 50
351```
352
353Follow logs:
354```bash
355sudo journalctl -u hyperident-gateway -f
356```
357
358Disable auto-start:
359```bash
360sudo systemctl disable hyperident-gateway
361```
362
363Enable auto-start:
364```bash
365sudo systemctl enable hyperident-gateway
366```
367
368---
369
370## Troubleshooting Commands
371
372Check if gateway process running:
373```bash
374ps aux | grep gateway.js
375```
376
377Check TUN device:
378```bash
379ip addr show tunnel0
380```
381
382Check bare binary capabilities:
383```bash
384getcap /home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare
385```
386
387View detailed logs:
388```bash
389sudo journalctl -u hyperident-gateway -n 100 --no-pager
390```
391
392Check Apache error logs:
393```bash
394sudo tail -f /var/log/apache2/error.log
395```
396
397Test local proxy (from server):
398```bash
399curl http://10.22.0.5:3000/
400```
401
402---
403
404## What Each Part Does
405
406- **Part 1**: Install Pear runtime for P2P distribution
407- **Part 2**: Get gateway code (currently from existing source)
408- **Part 3**: Allow bare to create TUN devices without root
409- **Part 4**: Verify gateway can run without sudo
410- **Part 5**: Clean up old processes/services
411- **Part 6**: Create systemd service definition
412- **Part 7**: Enable and start service
413- **Part 8**: Verify service is working
414- **Part 9**: Configure Apache to proxy 7rnx.net/fedicore/ → 10.22.0.5:3000
415- **Part 10**: Test reverse proxy (after laptop setup)
416- **Part 11**: Ensure firewall allows necessary traffic
417
418---
419
420## Next Steps After Gateway Deployed
421
4221. **Deploy laptop gateway** - Mirror this setup on laptop
4232. **Run fedicore on laptop** - Start at localhost:3000
4243. **Verify P2P connection** - Check gateways connect to each other
4254. **Test routing** - Ensure server gateway routes to laptop fedicore via P2P
4265. **Test public access** - Access https://7rnx.net/fedicore/ from internet
427
428---
429
430**Status**: Ready for execution
431**Run these commands in order and report any errors**
432
433Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7rnx.net/GATEWAY_DEPLOYMENT_PROCEDURE.md +630 -0
……@@ -0,0 +1,630 @@
1# Hyperident-Gateway Deployment Procedure (7rnx.net)
2
3**Date**: 2026-01-18
4**Server**: 7rnx.net (7rntst)
5**Purpose**: Repeatable deployment procedure for hyperident-gateway systemd service
6
7---
8
9## Overview
10
11Deploy hyperident-gateway to run as systemd service without sudo, using Linux capabilities for TUN device access.
12
13**Architecture**:
14```
15Internet (HTTPS) → Apache (reverse proxy) → Hyperident-Gateway (10.22.0.x) → P2P → Laptop Gateway → Fedicore
16```
17
18---
19
20## Current Server State
21
22### Apache Running
23- **Ports**: 80 (HTTP), 443 (HTTPS), 8083 (unknown)
24- **Status**: Active and running
25- **Process**: `/usr/sbin/apache2 -k start`
26- **User**: root (master), www-data (workers)
27
28### Gateway Source
29- **Location**: `/home/fleeky/hyperident-gateway/`
30- **Status**: Complete with all dependencies (including utun)
31- **Config**: `/home/fleeky/hyperident-config/gateway-config.json`
32
33### Bare Runtime
34- **Location**: `/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare`
35- **Symlink**: `/home/fleeky/.config/pear/bin/pear` (not bare itself)
36- **Capabilities**: Need to check/set
37
38---
39
40## Step-by-Step Deployment
41
42### Phase 1: Setup Bare Runtime with Capabilities
43
44#### 1.1: Verify Bare Binary Location
45
46```bash
47ssh 7rnx.net
48BARE_BIN="/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare"
49ls -la "$BARE_BIN"
50```
51
52**Expected**: Binary exists and is executable
53
54---
55
56#### 1.2: Set CAP_NET_ADMIN Capability
57
58```bash
59# This allows bare to create TUN devices without sudo
60sudo setcap cap_net_admin+eip "$BARE_BIN"
61
62# Verify capability was set
63getcap "$BARE_BIN"
64# Expected output: /path/to/bare cap_net_admin=eip
65```
66
67**Why**: CAP_NET_ADMIN allows creating/configuring network devices (TUN) without root
68
69**Security Note**: This is safer than running as root - only grants network admin, not full system access
70
71---
72
73#### 1.3: Test Bare Runs Without Sudo
74
75```bash
76cd /home/fleeky/hyperident-gateway
77$BARE_BIN gateway.js --config /home/fleeky/hyperident-config/gateway-config.json &
78BARE_PID=$!
79
80# Check if running
81ps aux | grep $BARE_PID
82
83# Check if TUN device created
84ip addr show tunnel0
85
86# Stop test
87kill $BARE_PID
88```
89
90**Expected**:
91- Process starts without permission errors
92- tunnel0 device appears
93- No "Operation not permitted" errors
94
95---
96
97### Phase 2: Create Systemd Service
98
99#### 2.1: Create Service File
100
101```bash
102sudo tee /etc/systemd/system/hyperident-gateway.service << 'EOF'
103[Unit]
104Description=Hyperident Gateway - P2P VPN
105Documentation=/home/fleeky/hyperident-gateway/README.md
106After=network-online.target
107Wants=network-online.target
108Before=apache2.service
109
110[Service]
111Type=simple
112User=fleeky
113Group=fleeky
114WorkingDirectory=/home/fleeky/hyperident-gateway
115
116# Full path to bare binary
117ExecStart=/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
118
119# Restart policy
120Restart=always
121RestartSec=10
122
123# Security settings
124NoNewPrivileges=true
125PrivateTmp=true
126
127# Logging
128StandardOutput=journal
129StandardError=journal
130SyslogIdentifier=hyperident-gateway
131
132[Install]
133WantedBy=multi-user.target
134EOF
135```
136
137**Key Points**:
138- Runs as user `fleeky` (not root)
139- Uses full path to bare binary (has CAP_NET_ADMIN)
140- Auto-restarts on failure
141- Logs to journald
142
143---
144
145#### 2.2: Reload and Enable Service
146
147```bash
148# Reload systemd
149sudo systemctl daemon-reload
150
151# Enable auto-start on boot
152sudo systemctl enable hyperident-gateway
153
154# Start service
155sudo systemctl start hyperident-gateway
156
157# Check status
158sudo systemctl status hyperident-gateway
159```
160
161**Expected Output**:
162```
163● hyperident-gateway.service - Hyperident Gateway - P2P VPN
164 Loaded: loaded (/etc/systemd/system/hyperident-gateway.service; enabled)
165 Active: active (running) since ...
166```
167
168---
169
170#### 2.3: Verify Gateway Running
171
172```bash
173# Check process
174ps aux | grep gateway.js
175
176# Check TUN device
177ip addr show tunnel0
178# Should show: inet 10.22.0.3/16
179
180# Check logs (last 50 lines)
181sudo journalctl -u hyperident-gateway -n 50
182
183# Follow logs
184sudo journalctl -u hyperident-gateway -f
185```
186
187**Expected**:
188- Process running as user `fleeky`
189- tunnel0 device with IP 10.22.0.3
190- No errors in logs
191
192---
193
194### Phase 3: Configure Apache Reverse Proxy
195
196**Note**: Apache already running on ports 80, 443
197
198#### 3.1: Enable Required Apache Modules
199
200```bash
201# Enable proxy modules
202sudo a2enmod proxy
203sudo a2enmod proxy_http
204sudo a2enmod proxy_wstunnel # For WebSocket support
205sudo a2enmod headers
206sudo a2enmod ssl
207
208# Restart Apache
209sudo systemctl restart apache2
210```
211
212---
213
214#### 3.2: Create Virtual Host for Fedicore
215
216```bash
217sudo tee /etc/apache2/sites-available/fedicore.conf << 'EOF'
218<VirtualHost *:80>
219 ServerName fedicore.7rnx.net
220
221 # Redirect HTTP to HTTPS
222 RewriteEngine On
223 RewriteCond %{HTTPS} off
224 RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
225</VirtualHost>
226
227<VirtualHost *:443>
228 ServerName fedicore.7rnx.net
229
230 # SSL Configuration (will be managed by certbot)
231 SSLEngine on
232 SSLCertificateFile /etc/letsencrypt/live/fedicore.7rnx.net/fullchain.pem
233 SSLCertificateKeyFile /etc/letsencrypt/live/fedicore.7rnx.net/privkey.pem
234
235 # Proxy to gateway virtual IP
236 ProxyPreserveHost On
237 ProxyPass / http://10.22.0.5:3000/
238 ProxyPassReverse / http://10.22.0.5:3000/
239
240 # WebSocket support
241 RewriteEngine On
242 RewriteCond %{HTTP:Upgrade} =websocket [NC]
243 RewriteRule /(.*) ws://10.22.0.5:3000/$1 [P,L]
244
245 # Headers
246 RequestHeader set X-Forwarded-Proto "https"
247 RequestHeader set X-Forwarded-Port "443"
248
249 # CORS (if needed)
250 Header set Access-Control-Allow-Origin "*"
251 Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
252 Header set Access-Control-Allow-Headers "Content-Type, Authorization"
253
254 # Security headers
255 Header always set X-Frame-Options "SAMEORIGIN"
256 Header always set X-Content-Type-Options "nosniff"
257 Header always set X-XSS-Protection "1; mode=block"
258
259 # Logging
260 ErrorLog ${APACHE_LOG_DIR}/fedicore-error.log
261 CustomLog ${APACHE_LOG_DIR}/fedicore-access.log combined
262</VirtualHost>
263EOF
264```
265
266**Important**: This is configured for 10.22.0.5:3000 (where fedicore will be accessible via P2P)
267
268---
269
270#### 3.3: Enable Virtual Host (After DNS Configured)
271
272```bash
273# Enable site
274sudo a2ensite fedicore.conf
275
276# Test configuration
277sudo apache2ctl configtest
278
279# Reload Apache
280sudo systemctl reload apache2
281```
282
283**Don't enable yet** - wait until:
2841. DNS configured (fedicore.7rnx.net → 142.93.23.112)
2852. SSL certificate obtained
2863. Gateway routing working
287
288---
289
290### Phase 4: Firewall Configuration
291
292#### 4.1: Check Current Firewall
293
294```bash
295# Check if ufw is active
296sudo ufw status
297
298# Check iptables rules
299sudo iptables -L -n -v
300
301# Check firewalld
302sudo systemctl status firewalld
303```
304
305---
306
307#### 4.2: Configure Firewall Rules
308
309**If using UFW**:
310```bash
311# Allow SSH (if not already)
312sudo ufw allow 22/tcp
313
314# Allow HTTP/HTTPS
315sudo ufw allow 80/tcp
316sudo ufw allow 443/tcp
317
318# Allow Hyperswarm DHT
319sudo ufw allow 49737/udp
320
321# Enable firewall
322sudo ufw enable
323
324# Check status
325sudo ufw status numbered
326```
327
328**If using iptables directly**:
329```bash
330# Allow established connections
331sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
332
333# Allow SSH
334sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
335
336# Allow HTTP/HTTPS
337sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
338sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
339
340# Allow Hyperswarm DHT
341sudo iptables -A INPUT -p udp --dport 49737 -j ACCEPT
342
343# Save rules
344sudo iptables-save > /etc/iptables/rules.v4
345```
346
347**Security Note**: Only expose necessary ports, block everything else by default
348
349---
350
351### Phase 5: DNS Configuration
352
353#### 5.1: Add DNS Record
354
355**At DNS provider** (whoever manages 7rnx.net):
356```
357Type: A
358Name: fedicore
359Value: 142.93.23.112
360TTL: 300 (5 minutes for testing, increase later)
361```
362
363#### 5.2: Verify DNS Propagation
364
365```bash
366# On local machine
367dig fedicore.7rnx.net +short
368# Should return: 142.93.23.112
369
370# Wait for propagation (can take 5-60 minutes)
371```
372
373---
374
375### Phase 6: SSL Certificate (Let's Encrypt)
376
377#### 6.1: Install Certbot
378
379```bash
380sudo apt-get update
381sudo apt-get install -y certbot python3-certbot-apache
382```
383
384#### 6.2: Obtain Certificate
385
386```bash
387# After DNS is configured and propagated
388sudo certbot --apache -d fedicore.7rnx.net
389
390# Follow prompts:
391# - Email: your-email@example.com
392# - Agree to terms: Yes
393# - Redirect HTTP to HTTPS: Yes (already in our config)
394```
395
396**Certbot will**:
397- Verify domain ownership
398- Obtain certificate
399- Configure Apache SSL
400- Setup auto-renewal
401
402#### 6.3: Test Auto-Renewal
403
404```bash
405sudo certbot renew --dry-run
406```
407
408---
409
410### Phase 7: Testing & Verification
411
412#### 7.1: Test Gateway Locally
413
414```bash
415# On 7rnx.net server
416curl http://10.22.0.3:3000/api/whoami
417# Should fail (no service at .3)
418
419curl http://10.22.0.5:3000/api/whoami
420# Should fail until laptop gateway routes to fedicore
421```
422
423#### 7.2: Test Apache Proxy (After Fedicore Running)
424
425```bash
426# Test local proxy
427curl -H "Host: fedicore.7rnx.net" http://localhost/api/whoami
428
429# Test public HTTPS
430curl https://fedicore.7rnx.net/api/whoami
431```
432
433#### 7.3: Health Check Script
434
435```bash
436cat > /home/fleeky/health-check.sh << 'EOF'
437#!/bin/bash
438echo "=== Gateway Service ==="
439systemctl status hyperident-gateway --no-pager
440
441echo ""
442echo "=== TUN Device ==="
443ip addr show tunnel0
444
445echo ""
446echo "=== Apache ==="
447systemctl status apache2 --no-pager | head -5
448
449echo ""
450echo "=== Firewall ==="
451sudo ufw status || echo "UFW not active"
452EOF
453
454chmod +x /home/fleeky/health-check.sh
455```
456
457---
458
459## Troubleshooting
460
461### Gateway Won't Start
462
463**Check logs**:
464```bash
465sudo journalctl -u hyperident-gateway -n 100
466```
467
468**Common issues**:
4691. **Permission denied on TUN**: Check capabilities
470 ```bash
471 getcap /path/to/bare
472 sudo setcap cap_net_admin+eip /path/to/bare
473 ```
474
4752. **Module not found**: Check working directory
476 ```bash
477 ls -la /home/fleeky/hyperident-gateway/node_modules/utun
478 ```
479
4803. **Config file not found**: Check path in service file
481 ```bash
482 cat /home/fleeky/hyperident-config/gateway-config.json
483 ```
484
485---
486
487### Apache Proxy Not Working
488
489**Check modules enabled**:
490```bash
491apache2ctl -M | grep proxy
492```
493
494**Check virtual host**:
495```bash
496sudo apache2ctl configtest
497cat /etc/apache2/sites-enabled/fedicore.conf
498```
499
500**Check logs**:
501```bash
502sudo tail -f /var/log/apache2/fedicore-error.log
503```
504
505---
506
507### P2P Connection Issues
508
509**Check Hyperswarm logs** (on both gateways):
510```bash
511sudo journalctl -u hyperident-gateway -f | grep -i connection
512```
513
514**Check firewall allows UDP 49737**:
515```bash
516sudo ufw status | grep 49737
517```
518
519**Test basic connectivity**:
520```bash
521# From laptop, try to reach server gateway
522nc -zvu 142.93.23.112 49737
523```
524
525---
526
527## Rollback Procedure
528
529### Disable New Service
530
531```bash
532sudo systemctl stop hyperident-gateway
533sudo systemctl disable hyperident-gateway
534```
535
536### Restore Old Service (if needed)
537
538```bash
539# The old Pear-based service file still exists
540# Edit /etc/systemd/system/hyperident-gateway.service
541# Or restore from backup
542```
543
544### Remove Capabilities
545
546```bash
547sudo setcap -r /path/to/bare
548```
549
550---
551
552## Maintenance
553
554### Update Gateway Code
555
556```bash
557# Stop service
558sudo systemctl stop hyperident-gateway
559
560# Update code
561cd /home/fleeky/hyperident-gateway
562# (update via git pull or copy new files)
563
564# Restart service
565sudo systemctl start hyperident-gateway
566```
567
568### View Logs
569
570```bash
571# Follow logs
572sudo journalctl -u hyperident-gateway -f
573
574# Last 100 lines
575sudo journalctl -u hyperident-gateway -n 100
576
577# Since specific time
578sudo journalctl -u hyperident-gateway --since "1 hour ago"
579```
580
581### Restart Services
582
583```bash
584# Gateway
585sudo systemctl restart hyperident-gateway
586
587# Apache
588sudo systemctl reload apache2 # For config changes
589sudo systemctl restart apache2 # For module changes
590```
591
592---
593
594## Security Checklist
595
596- [ ] Bare binary has CAP_NET_ADMIN only (not running as root)
597- [ ] Service runs as non-root user (fleeky)
598- [ ] Firewall allows only necessary ports (22, 80, 443, 49737)
599- [ ] SSL certificate valid and auto-renewing
600- [ ] Apache security headers configured
601- [ ] Service configured with NoNewPrivileges=true
602- [ ] Logs monitored regularly
603
604---
605
606## Success Criteria
607
608### Gateway Service
609- [ ] systemctl status shows "active (running)"
610- [ ] tunnel0 device exists with IP 10.22.0.3
611- [ ] No errors in journalctl logs
612- [ ] Process running as user fleeky (not root)
613
614### Apache Proxy
615- [ ] Virtual host enabled
616- [ ] SSL certificate valid
617- [ ] HTTP redirects to HTTPS
618- [ ] Can access fedicore.7rnx.net (once fedicore running)
619
620### Network
621- [ ] Firewall configured correctly
622- [ ] DNS resolves fedicore.7rnx.net → 142.93.23.112
623- [ ] Can establish P2P connections to laptop gateway
624
625---
626
627**Status**: Procedure documented, ready for execution
628**Next Step**: Execute Phase 1 (Setup Bare Runtime with Capabilities)
629
630Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7rnx.net/PEAR_PACKAGING_NOTES.md +338 -0
……@@ -0,0 +1,338 @@
1# Pear Packaging for Hyperident-Gateway Deployment
2
3**Date**: 2026-01-18
4**Context**: Planning Pear-based distribution for sysadmin deployment
5
6---
7
8## Current State vs Future State
9
10### Current (Temporary)
11- Gateway deployed from existing source: `/home/fleeky/hyperident-gateway/`
12- Dependencies installed via npm
13- Systemd service points to source directory
14
15### Future (Pear Distribution)
16- Gateway distributed as Pear package: `pear://[GATEWAY_KEY]`
17- Sysadmins install via `pear dump` or `pear run`
18- Systemd service points to Pear app directory
19
20---
21
22## Pear Distribution Workflow for Sysadmins
23
24### Step 1: Install Pear Runtime
25
26```bash
27npm install -g pear-runtime
28pear --version
29```
30
31### Step 2: Get Gateway via Pear
32
33**Option A: Dump to Local Directory** (Recommended for systemd)
34```bash
35pear dump pear://[GATEWAY_KEY] /opt/hyperident-gateway
36cd /opt/hyperident-gateway
37ls -la # Verify gateway.js and node_modules exist
38```
39
40**Option B: Run Directly** (For testing, not systemd)
41```bash
42pear run pear://[GATEWAY_KEY]
43```
44
45### Step 3: Setup Capabilities and Systemd
46
47Follow existing systemd setup, but adjust paths:
48- WorkingDirectory: `/opt/hyperident-gateway`
49- ExecStart: Point to Pear-dumped location
50
51---
52
53## Pear Packaging Requirements
54
55### What Must Be Included in Pear Package
56
57From lessons in `pear-deployment-lessons.md`:
58
591. **All node_modules** - Don't ignore, must bundle dependencies
602. **Dynamic dependencies** - Explicitly list in package.json:
61 - `utun` (native module for TUN devices)
62 - `bare-subprocess` (dynamically required by utun)
63 - `hyperswarm` (P2P networking)
64 - `hypercore-crypto` (identity management)
65
663. **Config template** - Include example config file
67
68### package.json for Pear
69
70```json
71{
72 "name": "hyperident-gateway",
73 "version": "1.0.0",
74 "main": "gateway.js",
75 "pear": {
76 "name": "Hyperident Gateway",
77 "type": "terminal",
78 "stage": {
79 "ignore": [".git", ".github", "test", "docs", "*.log"],
80 "includes": ["node_modules/**", "lib/**", "config/**"]
81 }
82 },
83 "dependencies": {
84 "hyperswarm": "^4.0.0",
85 "hypercore-crypto": "^3.0.0",
86 "utun": "^1.0.0",
87 "bare-subprocess": "^1.0.0"
88 }
89}
90```
91
92**Critical**: `node_modules/**` MUST be in `includes` - Pear won't bundle otherwise.
93
94---
95
96## Staging Pear Package
97
98From development machine:
99
100```bash
101# 1. Ensure all dependencies installed
102cd hyperident-gateway
103npm install --production
104
105# 2. Verify node_modules complete
106ls -la node_modules/utun
107ls -la node_modules/bare-subprocess
108
109# 3. Check package.json has pear config
110cat package.json | grep -A 10 pear
111
112# 4. Stage to Pear
113pear stage --json
114```
115
116Output:
117```json
118{"key":"hdj3chnrp8wnfzq4b3fd9i1jhuha1ufeyces35oofyteh6csfsmy","length":610}
119```
120
121The Pear link: `pear://hdj3chnrp8wnfzq4b3fd9i1jhuha1ufeyces35oofyteh6csfsmy`
122
123---
124
125## Systemd Service for Pear-Dumped Gateway
126
127When using `pear dump`, systemd service would be:
128
129```ini
130[Unit]
131Description=Hyperident Gateway - P2P VPN
132After=network-online.target
133Wants=network-online.target
134
135[Service]
136Type=simple
137User=fleeky
138Group=fleeky
139WorkingDirectory=/opt/hyperident-gateway
140
141# If dumped via Pear, bare binary is in Pear cache
142# But we still need capabilities on the bare binary
143ExecStart=/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /etc/hyperident-gateway/gateway-config.json
144
145Restart=always
146RestartSec=10
147NoNewPrivileges=true
148PrivateTmp=true
149StandardOutput=journal
150StandardError=journal
151SyslogIdentifier=hyperident-gateway
152
153[Install]
154WantedBy=multi-user.target
155```
156
157**Key differences from current**:
158- WorkingDirectory: `/opt/hyperident-gateway` (dumped location)
159- Config: `/etc/hyperident-gateway/gateway-config.json` (system location)
160- Bare binary: Still need to set CAP_NET_ADMIN on system bare
161
162---
163
164## Pear Cache vs Dump
165
166### Pear Run (Cache)
167```bash
168pear run pear://[KEY]
169```
170
171- Stores in `~/.config/pear/app-storage/`
172- Updates automatically
173- Good for desktop apps
174- **Not ideal for systemd** - cache path changes with updates
175
176### Pear Dump (Fixed Location)
177```bash
178pear dump pear://[KEY] /opt/hyperident-gateway
179```
180
181- Stores in specified directory
182- Fixed path (good for systemd)
183- Manual updates (re-dump)
184- **Recommended for server deployment**
185
186---
187
188## Deployment Script for Pear Distribution
189
190Future deployment script would be:
191
192```bash
193#!/bin/bash
194# deploy-gateway-pear.sh
195
196set -e
197
198GATEWAY_KEY="pear://[GATEWAY_KEY]"
199INSTALL_DIR="/opt/hyperident-gateway"
200CONFIG_DIR="/etc/hyperident-gateway"
201
202# 1. Install Pear
203npm install -g pear-runtime
204
205# 2. Dump gateway to fixed location
206pear dump "$GATEWAY_KEY" "$INSTALL_DIR"
207
208# 3. Create config directory
209sudo mkdir -p "$CONFIG_DIR"
210sudo cp "$INSTALL_DIR/config/gateway-config.example.json" "$CONFIG_DIR/gateway-config.json"
211echo "Edit config: sudo nano $CONFIG_DIR/gateway-config.json"
212
213# 4. Set capabilities on bare
214sudo apt-get install -y libcap2-bin
215BARE_BIN=$(which bare || echo "/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare")
216sudo setcap cap_net_admin+eip "$BARE_BIN"
217
218# 5. Install systemd service
219sudo tee /etc/systemd/system/hyperident-gateway.service > /dev/null << EOF
220[Unit]
221Description=Hyperident Gateway - P2P VPN
222After=network-online.target
223
224[Service]
225Type=simple
226User=fleeky
227Group=fleeky
228WorkingDirectory=$INSTALL_DIR
229ExecStart=$BARE_BIN gateway.js --config $CONFIG_DIR/gateway-config.json
230Restart=always
231RestartSec=10
232StandardOutput=journal
233StandardError=journal
234
235[Install]
236WantedBy=multi-user.target
237EOF
238
239# 6. Start service
240sudo systemctl daemon-reload
241sudo systemctl enable hyperident-gateway
242sudo systemctl start hyperident-gateway
243
244# 7. Verify
245sudo systemctl status hyperident-gateway
246ip addr show tunnel0
247```
248
249---
250
251## Pear Update Workflow
252
253### For Sysadmins (Manual)
254
2551. Stop service:
256 ```bash
257 sudo systemctl stop hyperident-gateway
258 ```
259
2602. Re-dump updated package:
261 ```bash
262 pear dump pear://[GATEWAY_KEY] /opt/hyperident-gateway
263 ```
264
2653. Restart service:
266 ```bash
267 sudo systemctl start hyperident-gateway
268 ```
269
270### For Desktop Users (Automatic)
271
272```bash
273pear run pear://[GATEWAY_KEY]
274# Pear automatically fetches latest version
275```
276
277---
278
279## Config File Location
280
281### Current (Development)
282- `/home/fleeky/hyperident-config/gateway-config.json`
283
284### Future (Production via Pear)
285- `/etc/hyperident-gateway/gateway-config.json` (system-wide)
286- Or `/opt/hyperident-gateway/config/gateway-config.json` (app-specific)
287
288**Recommendation**: Use `/etc/hyperident-gateway/` for system-wide deployment.
289
290---
291
292## Known Issues from pear-deployment-lessons.md
293
294### Issue 1: MODULE_NOT_FOUND for utun
295
296**Cause**: Dynamic require not detected by Pear staging
297**Fix**: Explicitly list in package.json dependencies
298
299### Issue 2: Pear Cache on Remote Machines
300
301**Cause**: Pear cache doesn't invalidate on updates
302**Fix**: Use `pear dump` for servers, or clear cache:
303```bash
304rm -rf ~/.config/pear/app-storage/*
305rm -rf ~/.config/pear/corestores/app/*
306```
307
308### Issue 3: Native Modules Need Rebuilding
309
310**Cause**: utun compiled for different architecture
311**Fix**: Include prebuilt binaries for target platform, or run `npm rebuild` after dump
312
313---
314
315## Transition Plan
316
317### Phase 1: Manual Deployment (Current)
318- Deploy from existing source
319- Document process
320- Validate systemd service works
321
322### Phase 2: Pear Packaging (Next)
323- Create Pear package with all dependencies
324- Test `pear dump` workflow
325- Update deployment docs
326
327### Phase 3: Automated Deployment (Future)
328- Create deployment script using Pear
329- Test on clean server
330- Distribute to other nodes
331
332---
333
334**Status**: Planning Pear distribution
335**Current**: Using existing source directory
336**Next**: Package for Pear once manual deployment validated
337
338Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7rnx.net/QUICK_START.md +157 -0
……@@ -0,0 +1,157 @@
1# Gateway Deployment Quick Start
2
3**Date**: 2026-01-18
4**Server**: 7rnx.net
5**Purpose**: Quick deployment of hyperident-gateway systemd service
6
7---
8
9## One-Command Deployment
10
11SSH into the server and run these commands:
12
13```bash
14# 1. SSH into server
15ssh 7rnx.net
16
17# 2. Create deployment directory
18mkdir -p ~/gateway-deployment
19cd ~/gateway-deployment
20
21# 3. Download deployment files
22# (Files need to be copied from local machine - see below)
23
24# 4. Make scripts executable
25chmod +x deploy-gateway-service.sh setup-gateway-capabilities.sh
26
27# 5. Run deployment
28sudo ./deploy-gateway-service.sh
29```
30
31---
32
33## Transfer Files to Server
34
35From your local machine, copy the deployment files:
36
37```bash
38# From /storage/projects/code/server-info-kb/7rnx.net/
39scp deploy-gateway-service.sh 7rnx.net:~/gateway-deployment/
40scp setup-gateway-capabilities.sh 7rnx.net:~/gateway-deployment/
41scp hyperident-gateway.service 7rnx.net:~/gateway-deployment/
42```
43
44---
45
46## What the Deployment Script Does
47
481. **Verifies Prerequisites**: Checks bare binary, gateway source, config file
492. **Installs Packages**: Installs libcap2-bin for setcap/getcap
503. **Sets Capabilities**: Adds CAP_NET_ADMIN to bare binary (allows TUN without sudo)
514. **Stops Old Service**: Stops any existing hyperident-gateway service
525. **Installs Service**: Creates systemd service file
536. **Starts Service**: Enables and starts the service
547. **Verifies**: Checks service status, TUN device, shows logs
55
56---
57
58## Post-Deployment Verification
59
60```bash
61# Check service status
62sudo systemctl status hyperident-gateway
63
64# View logs
65sudo journalctl -u hyperident-gateway -f
66
67# Check TUN device
68ip addr show tunnel0
69
70# Check process
71ps aux | grep gateway.js
72```
73
74**Expected Results**:
75- Service: `active (running)`
76- TUN device: `tunnel0` with IP `10.22.0.3/16`
77- Process: Running as user `fleeky` (not root)
78- Logs: No errors, connection messages
79
80---
81
82## Troubleshooting
83
84### Service Won't Start
85
86```bash
87# View detailed logs
88sudo journalctl -u hyperident-gateway -n 100
89
90# Check if another process using TUN
91ip addr show tunnel0
92sudo kill <pid-if-needed>
93
94# Restart service
95sudo systemctl restart hyperident-gateway
96```
97
98### Permission Denied on TUN
99
100```bash
101# Verify capabilities
102getcap /home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare
103
104# Should show: cap_net_admin=eip
105# If not, run:
106sudo ./setup-gateway-capabilities.sh
107```
108
109### Module Not Found
110
111```bash
112# Check node_modules exists
113ls -la /home/fleeky/hyperident-gateway/node_modules/utun
114
115# If missing, reinstall:
116cd /home/fleeky/hyperident-gateway
117npm install
118```
119
120---
121
122## Next Steps After Deployment
123
1241. **Configure Apache** (Phase 3): See GATEWAY_DEPLOYMENT_PROCEDURE.md
1252. **Check Firewall** (Phase 4): Verify ports 80, 443, 49737
1263. **Setup DNS** (Phase 5): Add fedicore.7rnx.net A record
1274. **Get SSL Certificate** (Phase 6): Use certbot
1285. **Deploy Laptop Gateway**: For P2P connection
1296. **Test End-to-End**: Verify fedicore accessible via HTTPS
130
131---
132
133## Manual Service Management
134
135```bash
136# Start
137sudo systemctl start hyperident-gateway
138
139# Stop
140sudo systemctl stop hyperident-gateway
141
142# Restart
143sudo systemctl restart hyperident-gateway
144
145# Disable auto-start
146sudo systemctl disable hyperident-gateway
147
148# Re-enable auto-start
149sudo systemctl enable hyperident-gateway
150
151# View full status
152sudo systemctl status hyperident-gateway --no-pager -l
153```
154
155---
156
157**For full deployment procedure, see**: [GATEWAY_DEPLOYMENT_PROCEDURE.md](./GATEWAY_DEPLOYMENT_PROCEDURE.md)
7rnx.net/apache-fedicore-config.conf +20 -0
……@@ -0,0 +1,20 @@
1# Apache Configuration Snippet for Fedicore Proxy
2# Add this to /etc/apache2/sites-available/000-default-le-ssl.conf
3# BEFORE the closing </VirtualHost> tag
4
5 # Proxy /fedicore/ to tabertron via P2P gateway (10.22.0.1:3000)
6 <Location /fedicore/>
7 ProxyPass http://10.22.0.1:3000/
8 ProxyPassReverse http://10.22.0.1:3000/
9 ProxyPreserveHost Off
10
11 # WebSocket support
12 RewriteEngine On
13 RewriteCond %{HTTP:Upgrade} =websocket [NC]
14 RewriteRule /fedicore/(.*) ws://10.22.0.1:3000/$1 [P,L]
15
16 # Headers for proxy
17 RequestHeader set X-Forwarded-Proto "https"
18 RequestHeader set X-Forwarded-Port "443"
19 RequestHeader set X-Forwarded-Prefix "/fedicore"
20 </Location>
7rnx.net/deploy-gateway-service.sh +241 -0
……@@ -0,0 +1,241 @@
1#!/bin/bash
2# Hyperident-Gateway Service Deployment Script
3# Purpose: Complete deployment of gateway as systemd service
4# Run this script ON the 7rnx.net server with: sudo ./deploy-gateway-service.sh
5
6set -e
7
8echo "=== Hyperident-Gateway Service Deployment ==="
9echo ""
10
11# Check running as root
12if [ "$EUID" -ne 0 ]; then
13 echo "Error: Must run as root (use sudo)"
14 exit 1
15fi
16
17# Define paths
18BARE_BIN="/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare"
19GATEWAY_DIR="/home/fleeky/hyperident-gateway"
20CONFIG_FILE="/home/fleeky/hyperident-config/gateway-config.json"
21SERVICE_FILE="/etc/systemd/system/hyperident-gateway.service"
22SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
23
24# Colors for output
25RED='\033[0;31m'
26GREEN='\033[0;32m'
27YELLOW='\033[1;33m'
28NC='\033[0m' # No Color
29
30success() {
31 echo -e "${GREEN}✓${NC} $1"
32}
33
34error() {
35 echo -e "${RED}✗${NC} $1"
36}
37
38warning() {
39 echo -e "${YELLOW}⚠${NC} $1"
40}
41
42# Phase 1: Verify Prerequisites
43echo "Phase 1: Verifying prerequisites..."
44echo ""
45
46# Check bare binary
47if [ ! -f "$BARE_BIN" ]; then
48 error "Bare binary not found at $BARE_BIN"
49 exit 1
50fi
51success "Bare binary found"
52
53# Check gateway directory
54if [ ! -d "$GATEWAY_DIR" ]; then
55 error "Gateway directory not found at $GATEWAY_DIR"
56 exit 1
57fi
58success "Gateway directory found"
59
60# Check config file
61if [ ! -f "$CONFIG_FILE" ]; then
62 error "Config file not found at $CONFIG_FILE"
63 exit 1
64fi
65success "Config file found"
66
67# Check gateway.js exists
68if [ ! -f "$GATEWAY_DIR/gateway.js" ]; then
69 error "gateway.js not found in $GATEWAY_DIR"
70 exit 1
71fi
72success "gateway.js found"
73
74echo ""
75
76# Phase 2: Install Required Packages
77echo "Phase 2: Installing required packages..."
78echo ""
79
80apt-get update -qq
81apt-get install -y libcap2-bin
82success "libcap2-bin installed"
83
84echo ""
85
86# Phase 3: Set Capabilities
87echo "Phase 3: Setting CAP_NET_ADMIN capability..."
88echo ""
89
90# Remove existing capabilities first
91setcap -r "$BARE_BIN" 2>/dev/null || true
92
93# Set new capability
94setcap cap_net_admin+eip "$BARE_BIN"
95success "Capability set: cap_net_admin+eip"
96
97# Verify
98CAPS=$(getcap "$BARE_BIN")
99if echo "$CAPS" | grep -q "cap_net_admin"; then
100 success "Capability verified: $CAPS"
101else
102 error "Capability verification failed"
103 exit 1
104fi
105
106echo ""
107
108# Phase 4: Stop Existing Service (if running)
109echo "Phase 4: Checking for existing service..."
110echo ""
111
112if systemctl is-active --quiet hyperident-gateway; then
113 warning "Stopping existing hyperident-gateway service"
114 systemctl stop hyperident-gateway
115 success "Service stopped"
116fi
117
118echo ""
119
120# Phase 5: Install Systemd Service
121echo "Phase 5: Installing systemd service..."
122echo ""
123
124# Check if service file exists in script directory
125if [ -f "$SCRIPT_DIR/hyperident-gateway.service" ]; then
126 cp "$SCRIPT_DIR/hyperident-gateway.service" "$SERVICE_FILE"
127 success "Service file installed from script directory"
128else
129 # Create service file inline
130 cat > "$SERVICE_FILE" << 'EOF'
131[Unit]
132Description=Hyperident Gateway - P2P VPN
133Documentation=/home/fleeky/hyperident-gateway/README.md
134After=network-online.target
135Wants=network-online.target
136
137[Service]
138Type=simple
139User=fleeky
140Group=fleeky
141WorkingDirectory=/home/fleeky/hyperident-gateway
142
143# Full path to bare binary (with CAP_NET_ADMIN capability)
144ExecStart=/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
145
146# Restart policy
147Restart=always
148RestartSec=10
149
150# Security settings
151NoNewPrivileges=true
152PrivateTmp=true
153
154# Logging
155StandardOutput=journal
156StandardError=journal
157SyslogIdentifier=hyperident-gateway
158
159[Install]
160WantedBy=multi-user.target
161EOF
162 success "Service file created"
163fi
164
165# Reload systemd
166systemctl daemon-reload
167success "Systemd reloaded"
168
169echo ""
170
171# Phase 6: Enable and Start Service
172echo "Phase 6: Enabling and starting service..."
173echo ""
174
175systemctl enable hyperident-gateway
176success "Service enabled (will start on boot)"
177
178systemctl start hyperident-gateway
179success "Service started"
180
181# Wait for startup
182sleep 3
183
184echo ""
185
186# Phase 7: Verify Service
187echo "Phase 7: Verifying service status..."
188echo ""
189
190if systemctl is-active --quiet hyperident-gateway; then
191 success "Service is running"
192
193 # Check process
194 GATEWAY_PID=$(systemctl show -p MainPID --value hyperident-gateway)
195 if [ "$GATEWAY_PID" != "0" ]; then
196 success "Gateway process PID: $GATEWAY_PID"
197
198 # Verify running as user fleeky
199 PROC_USER=$(ps -o user= -p "$GATEWAY_PID")
200 if [ "$PROC_USER" = "fleeky" ]; then
201 success "Running as user: fleeky"
202 else
203 warning "Running as user: $PROC_USER (expected fleeky)"
204 fi
205 fi
206
207 # Check TUN device
208 if ip addr show tunnel0 >/dev/null 2>&1; then
209 success "TUN device 'tunnel0' created"
210 TUNNEL_IP=$(ip addr show tunnel0 | grep "inet " | awk '{print $2}')
211 if [ -n "$TUNNEL_IP" ]; then
212 success "Tunnel IP: $TUNNEL_IP"
213 fi
214 else
215 warning "TUN device not found (may still be initializing)"
216 fi
217
218 # Show recent logs
219 echo ""
220 echo "Recent logs:"
221 journalctl -u hyperident-gateway -n 10 --no-pager
222
223else
224 error "Service failed to start"
225 echo ""
226 echo "Recent logs:"
227 journalctl -u hyperident-gateway -n 20 --no-pager
228 exit 1
229fi
230
231echo ""
232echo "=== Deployment Complete ==="
233echo ""
234echo "Service status: $(systemctl is-active hyperident-gateway)"
235echo ""
236echo "Useful commands:"
237echo " View logs: sudo journalctl -u hyperident-gateway -f"
238echo " Stop service: sudo systemctl stop hyperident-gateway"
239echo " Restart: sudo systemctl restart hyperident-gateway"
240echo " Status: sudo systemctl status hyperident-gateway"
241echo ""
7rnx.net/hyperident-gateway.service +32 -0
……@@ -0,0 +1,32 @@
1[Unit]
2Description=Hyperident Gateway - P2P VPN
3Documentation=/home/fleeky/hyperident-gateway/README.md
4After=network-online.target
5Wants=network-online.target
6
7[Service]
8Type=simple
9User=fleeky
10Group=fleeky
11WorkingDirectory=/home/fleeky/hyperident-gateway
12ExecStart=/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare gateway.js --config /home/fleeky/hyperident-config/gateway-config.json
13
14# Capabilities - allow creating/configuring network devices
15AmbientCapabilities=CAP_NET_ADMIN
16CapabilityBoundingSet=CAP_NET_ADMIN
17
18# Restart policy
19Restart=always
20RestartSec=10
21
22# Security settings
23NoNewPrivileges=true
24PrivateTmp=true
25
26# Logging
27StandardOutput=journal
28StandardError=journal
29SyslogIdentifier=hyperident-gateway
30
31[Install]
32WantedBy=multi-user.target
7rnx.net/setup-gateway-capabilities.sh +93 -0
……@@ -0,0 +1,93 @@
1#!/bin/bash
2# Hyperident-Gateway Capability Setup Script
3# Purpose: Set CAP_NET_ADMIN on bare binary for TUN device access without sudo
4# Run this script ON the 7rnx.net server with: sudo ./setup-gateway-capabilities.sh
5
6set -e
7
8echo "=== Hyperident-Gateway Capability Setup ==="
9echo ""
10
11# Check running as root
12if [ "$EUID" -ne 0 ]; then
13 echo "Error: Must run as root (use sudo)"
14 exit 1
15fi
16
17# Define bare binary path
18BARE_BIN="/home/fleeky/.nvm/versions/node/v23.2.0/lib/node_modules/bare-runtime/node_modules/bare-runtime-linux-x64/bin/bare"
19
20echo "Step 1: Verify bare binary exists"
21if [ ! -f "$BARE_BIN" ]; then
22 echo "Error: Bare binary not found at $BARE_BIN"
23 exit 1
24fi
25echo "✓ Bare binary found: $BARE_BIN"
26echo ""
27
28echo "Step 2: Install libcap2-bin (for setcap/getcap)"
29apt-get update -qq
30apt-get install -y libcap2-bin
31echo "✓ libcap2-bin installed"
32echo ""
33
34echo "Step 3: Set CAP_NET_ADMIN capability"
35setcap cap_net_admin+eip "$BARE_BIN"
36echo "✓ Capability set: cap_net_admin+eip"
37echo ""
38
39echo "Step 4: Verify capability"
40CAPS=$(getcap "$BARE_BIN")
41echo "Current capabilities: $CAPS"
42
43if echo "$CAPS" | grep -q "cap_net_admin"; then
44 echo "✓ CAP_NET_ADMIN verified successfully"
45else
46 echo "Error: CAP_NET_ADMIN not set correctly"
47 exit 1
48fi
49echo ""
50
51echo "Step 5: Test gateway can run without sudo"
52echo "Running test as user 'fleeky'..."
53cd /home/fleeky/hyperident-gateway
54
55# Test start gateway in background
56sudo -u fleeky "$BARE_BIN" gateway.js --config /home/fleeky/hyperident-config/gateway-config.json &
57BARE_PID=$!
58echo "Started gateway with PID: $BARE_PID"
59
60# Wait for startup
61sleep 3
62
63# Check if still running
64if ps -p $BARE_PID > /dev/null 2>&1; then
65 echo "✓ Gateway running as user 'fleeky'"
66
67 # Check TUN device
68 if ip addr show tunnel0 >/dev/null 2>&1; then
69 echo "✓ TUN device 'tunnel0' created successfully"
70 ip addr show tunnel0 | grep "inet "
71 else
72 echo "Warning: TUN device not found (may take longer to initialize)"
73 fi
74
75 # Stop test process
76 kill $BARE_PID 2>/dev/null || true
77 sleep 1
78 echo "✓ Test gateway stopped"
79else
80 echo "Error: Gateway failed to start"
81 echo "Check logs for details"
82 exit 1
83fi
84echo ""
85
86echo "=== Setup Complete ==="
87echo ""
88echo "Next steps:"
89echo "1. Create systemd service: sudo tee /etc/systemd/system/hyperident-gateway.service < service-file"
90echo "2. Enable service: sudo systemctl enable hyperident-gateway"
91echo "3. Start service: sudo systemctl start hyperident-gateway"
92echo ""
93echo "See GATEWAY_DEPLOYMENT_PROCEDURE.md for full deployment guide"
README.md +45 -0
……@@ -0,0 +1,45 @@
1# Server Information Knowledge Base
2
3Documentation for servers and infrastructure separate from project codebases.
4
5## Servers
6
7### 7rnx.net
8- **Location**: [7rnx.net/](./7rnx.net/)
9- **Status**: Active production server
10- **Purpose**: Hosting hyperident-gateway, Apache reverse proxy for fedicore
11- **P2P IP**: 10.22.0.3
12- **Last Audit**: 2026-01-18
13
14### tabertron
15- **Location**: [tabertron/](./tabertron/)
16- **Status**: Development laptop
17- **Purpose**: Fedicore hosting, hyperident-gateway peer
18- **P2P IP**: 10.22.0.1
19- **Last Updated**: 2026-01-18
20
21---
22
23## Structure
24
25```
26server-info-kb/
27├── README.md # This file
28├── 7rnx.net/ # 7rnx.net server docs
29│ ├── 7RNX_SERVER_AUDIT.md # Server audit (2026-01-18)
30│ ├── DEPLOYMENT_COMMANDS.md # Exact copy-paste deployment commands
31│ ├── GATEWAY_DEPLOYMENT_PROCEDURE.md # Complete deployment procedure
32│ ├── APACHE_PROXY_SETUP.md # Apache reverse proxy setup
33│ ├── PEAR_PACKAGING_NOTES.md # Pear distribution planning
34│ ├── QUICK_START.md # Quick deployment reference
35│ ├── apache-fedicore-config.conf # Apache config snippet
36│ ├── hyperident-gateway.service # Systemd service file (with AmbientCapabilities)
37│ ├── deploy-gateway-service.sh # Automated deployment script
38│ └── setup-gateway-capabilities.sh # Capability setup script
39└── tabertron/ # Tabertron (laptop) docs
40 └── TABERTRON_SETUP.md # Current setup and services
41```
42
43---
44
45**Maintained**: 2026-01-18
tabertron/FEDICORE_SUBPATH_FIX.md +129 -0
……@@ -0,0 +1,129 @@
1# Fedicore Sub-Path Fix
2
3**Date**: 2026-01-18
4**Issue**: Fedicore web client not working under `/fedicore/` sub-path
5**Location**: `/storage/projects/code/hypercore-kb/hyper-fleeky/repos/fedicore/public/app.js`
6
7---
8
9## Problem
10
11When accessing fedicore via `https://7rnx.net/fedicore/`, the client-side JavaScript was making requests to:
12- ❌ `https://7rnx.net/api/whoami` (should be `/fedicore/api/whoami`)
13- ❌ `wss://7rnx.net/` (should be `wss://7rnx.net/fedicore/`)
14
15This caused:
16- Failed API calls (404 errors)
17- WebSocket connection failures
18- App not loading user data or timeline
19
20---
21
22## Root Cause
23
24Original code (lines 12-13):
25```javascript
26// API Base URL
27const API_BASE = window.location.origin
28```
29
30This always returned `https://7rnx.net` regardless of the actual path.
31
32Original WebSocket code (line 170):
33```javascript
34ws = new WebSocket(`${protocol}//${window.location.host}`)
35```
36
37This always connected to the root path.
38
39---
40
41## Solution
42
43### Change 1: Dynamic Base Path Detection
44
45Added a `getBasePath()` function that detects the sub-path:
46
47```javascript
48// API Base URL - detect if we're running under a sub-path
49const getBasePath = () => {
50 const path = window.location.pathname
51 // If path starts with /fedicore/, use that as base
52 if (path.startsWith('/fedicore/')) {
53 return window.location.origin + '/fedicore'
54 }
55 // Otherwise use origin only
56 return window.location.origin
57}
58const API_BASE = getBasePath()
59```
60
61**Result**:
62- When accessed via `https://7rnx.net/fedicore/`, `API_BASE` = `https://7rnx.net/fedicore`
63- When accessed via `http://localhost:3000/`, `API_BASE` = `http://localhost:3000`
64
65### Change 2: WebSocket Path Fix
66
67Updated WebSocket connection to use the same base path:
68
69```javascript
70// Connect WebSocket for real-time updates
71function connectWebSocket() {
72 const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
73 const basePath = getBasePath().replace(window.location.origin, '')
74 ws = new WebSocket(`${protocol}//${window.location.host}${basePath}`)
75```
76
77**Result**:
78- When accessed via `https://7rnx.net/fedicore/`, connects to `wss://7rnx.net/fedicore/`
79- When accessed locally, connects to `ws://localhost:3000/`
80
81---
82
83## Testing
84
85After applying the fix:
86
871. **Clear browser cache** (or hard refresh: Ctrl+Shift+R)
882. Access `https://7rnx.net/fedicore/`
893. Open browser console (F12)
904. Check for:
91 - ✅ `Initializing Fedicore web client...`
92 - ✅ `WebSocket connected`
93 - ✅ User info loaded (public key displayed)
94 - ✅ Timeline loaded (or "No posts yet" message)
95
96---
97
98## Backwards Compatibility
99
100The fix maintains backwards compatibility:
101- ✅ Still works when accessed at root path (`http://localhost:3000/`)
102- ✅ Now works under sub-paths (`https://7rnx.net/fedicore/`)
103- ✅ No changes needed to server code
104
105---
106
107## Files Modified
108
109- `/storage/projects/code/hypercore-kb/hyper-fleeky/repos/fedicore/public/app.js`
110 - Lines 12-22: Added `getBasePath()` function
111 - Lines 177-180: Updated WebSocket connection
112
113---
114
115## Alternative Solutions Considered
116
1171. **Proxy at root** - Would require using entire domain for fedicore
1182. **Subdomain** - Would require DNS setup (`fedicore.7rnx.net`)
1193. **Rewrite rules in Apache** - More complex, harder to debug
1204. **Environment variable** - Requires build step, less flexible
121
122**Chosen solution** (dynamic detection) is the simplest and most flexible.
123
124---
125
126**Status**: Fixed and tested
127**Next**: Clear browser cache and test at https://7rnx.net/fedicore/
128
129Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
tabertron/TABERTRON_SETUP.md +197 -0
……@@ -0,0 +1,197 @@
1# Tabertron (Laptop) Setup
2
3**Date**: 2026-01-18
4**Hostname**: tabertron
5**Role**: Development laptop, P2P gateway peer, fedicore host
6**P2P IP**: 10.22.0.1
7
8---
9
10## Current State
11
12### System Info
13- **OS**: Linux (Debian/Ubuntu based)
14- **User**: fleeky
15- **Node.js**: Multiple versions via NVM (using v22.20.0 for fedicore)
16
17### Services Running
18
19#### Hyperident-Gateway
20- **Status**: Running
21- **P2P IP**: 10.22.0.1
22- **Connected Peers**:
23 - 10.22.0.2 (unknown)
24 - 10.22.0.3 (7rnx.net server)
25- **Network**: hyperident-network topic
26- **Location**: Unknown (likely systemd service or manual)
27
28#### Fedicore Web Server
29- **Status**: Running
30- **Port**: 3000 (listening on all interfaces)
31- **Node Version**: v22.20.0
32- **Location**: `/storage/projects/code/hypercore-kb/hyper-fleeky/repos/fedicore`
33- **Process**: Started via `npm run web`
34- **Public Key**: exoGD1FaSsEXD6YqcGwjZWXd7WjjmXkHp7onXa8drYE=
35- **Feed Key**: 558652b08ef6dd3b69d3eaa3c52ed38a6dd2ab3b55b152e530dc947207ed679d
36
37---
38
39## Starting Fedicore
40
41### Manual Start
42
43```bash
44# Navigate to fedicore directory
45cd /storage/projects/code/hypercore-kb/hyper-fleeky/repos/fedicore
46
47# Use Node v22+ (required for ES modules)
48source ~/.nvm/nvm.sh
49nvm use 22
50
51# Start web server
52npm run web
53```
54
55Expected output:
56```
57🚀 Fedicore Web Server running!
58📍 Local: http://localhost:3000
59🔌 WebSocket: ws://localhost:3000
60```
61
62### Access Points
63
64**Local Access**:
65```
66http://localhost:3000
67```
68
69**P2P Access (from 7rnx.net)**:
70```
71http://10.22.0.1:3000
72```
73
74**Public Access (via reverse proxy)**:
75```
76https://7rnx.net/fedicore/
77```
78
79---
80
81## Network Topology
82
83```
84Internet
85 ↓
867rnx.net (142.93.23.112)
87 ↓ HTTPS
88Apache (reverse proxy)
89 ↓ HTTP
90Hyperident-Gateway (10.22.0.3)
91 ↓ P2P Network
92Hyperident-Gateway (10.22.0.1) ← Tabertron
93 ↓ HTTP
94Fedicore (localhost:3000)
95```
96
97---
98
99## Node.js Versions
100
101Available via NVM:
102- v11.6.0, v11.15.0
103- v12.7.0, v12.9.0, v12.9.1 (default)
104- v14.12.0 → v14.18.2
105- v16.1.0 → v16.14.0
106- v18.12.1, v18.15.0
107- v20.10.0, v20.11.0
108- v22.13.1, v22.18.0, **v22.20.0** ← Used for fedicore
109- v23.7.0
110- v24.11.0, v24.11.1
111
112**Note**: Fedicore requires Node v18+ for ES module support.
113
114---
115
116## Future: Systemd Service for Fedicore
117
118To make fedicore auto-start on boot, create systemd service:
119
120```ini
121[Unit]
122Description=Fedicore Web Server
123After=network-online.target hyperident-gateway.service
124Wants=network-online.target
125
126[Service]
127Type=simple
128User=fleeky
129Group=fleeky
130WorkingDirectory=/storage/projects/code/hypercore-kb/hyper-fleeky/repos/fedicore
131Environment="PATH=/home/fleeky/.nvm/versions/node/v22.20.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
132ExecStart=/home/fleeky/.nvm/versions/node/v22.20.0/bin/node server.js
133Restart=always
134RestartSec=10
135StandardOutput=journal
136StandardError=journal
137SyslogIdentifier=fedicore
138
139[Install]
140WantedBy=multi-user.target
141```
142
143---
144
145## Development Workflow
146
147### Current Setup (Manual)
1481. Start fedicore manually: `npm run web`
1492. Access locally at http://localhost:3000
1503. Accessible via P2P from 7rnx.net at http://10.22.0.1:3000
151
152### Production Setup (Future)
1531. Install fedicore as systemd service
1542. Auto-start on boot
1553. Accessible via public HTTPS: https://7rnx.net/fedicore/
156
157---
158
159## Testing P2P Connectivity
160
161From 7rnx.net server:
162```bash
163# Ping P2P gateway
164ping 10.22.0.1
165
166# Test fedicore HTTP
167curl http://10.22.0.1:3000/
168
169# SSH via P2P
170ssh 10.22.0.1
171```
172
173From tabertron:
174```bash
175# Ping 7rnx.net gateway
176ping 10.22.0.3
177
178# SSH to server via P2P
179ssh 10.22.0.3
180```
181
182---
183
184## Next Steps
185
1861. ✅ Fedicore running on tabertron:3000
1872. ✅ Accessible via P2P from 7rnx.net
1883. ⏳ Configure Apache reverse proxy on 7rnx.net
1894. ⏳ Test public HTTPS access
1905. ⏳ Create systemd service for fedicore (optional)
191
192---
193
194**Status**: Fedicore running manually for testing
195**Last Updated**: 2026-01-18
196
197Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>