f531002 · hyperident-gateway

Changed files (1) +248 -0

DEPLOYMENT.md +248 -0

…	…	@@ -0,0 +1,248 @@
	1	# Hyperident Gateway - Deployment Guide
	2
	3	This document explains how to deploy hyperident-gateway as a Pear application and via traditional methods.
	4
	5	## Pear Deployment (Recommended for P2P Distribution)
	6
	7	Pear allows you to distribute and update the gateway across the P2P network without centralized infrastructure.
	8
	9	### Prerequisites
	10
	11	Install Pear on the deployment machine:
	12
	13	```bash
	14	npx pear
	15	```
	16
	17	Follow the instructions to add Pear to your PATH.
	18
	19	### Development Workflow
	20
	21	1. Test locally in dev mode:
	22
	23	```bash
	24	cd /path/to/hyperident-gateway
	25	pear run --dev .
	26	```
	27
	28	This runs the gateway from your local directory without staging.
	29
	30	2. Stage for development channel:
	31
	32	```bash
	33	pear stage dev
	34	```
	35
	36	This creates a `pear://` link you can share with others for testing. The link is deterministic based on:
	37	- Channel name (`dev`)
	38	- App name (from package.json)
	39
	40	3. Test the staged version:
	41
	42	```bash
	43	pear run <dev-link>
	44	```
	45
	46	### Production Deployment
	47
	48	1. Stage for production:
	49
	50	```bash
	51	pear stage production
	52	```
	53
	54	This outputs a production `pear://` link.
	55
	56	2. Mark a release:
	57
	58	```bash
	59	pear release production
	60	```
	61
	62	This creates a versioned release point. Now `pear run <production-link>` will load this stable version by default.
	63
	64	3. Seed the app to the network:
	65
	66	```bash
	67	pear seed production
	68	```
	69
	70	Keep this running to ensure peers can download the app. You can stop it when enough peers are seeding.
	71
	72	### Installing on Remote Machines
	73
	74	On any machine with Pear installed:
	75
	76	```bash
	77	pear run <production-link> --args="--config /path/to/config.json"
	78	```
	79
	80	Arguments after `--args=` are passed to the gateway application.
	81
	82	### Deploying to 7rnx.net (DigitalOcean Droplet)
	83
	84	1. Install Pear on the droplet:
	85
	86	```bash
	87	ssh fleeky@7rnx.net
	88	npx pear
	89	# Add to PATH as instructed
	90	```
	91
	92	2. Run the gateway:
	93
	94	```bash
	95	pear run <production-link> --args="--config /etc/hyperident-gateway/config.json"
	96	```
	97
	98	3. Create systemd service for persistence:
	99
	100	Create `/etc/systemd/system/hyperident-gateway.service`:
	101
	102	```ini
	103	[Unit]
	104	Description=Hyperident Gateway (Pear)
	105	After=network-online.target
	106	Wants=network-online.target
	107
	108	[Service]
	109	Type=simple
	110	User=root
	111	ExecStart=/home/fleeky/.config/pear/bin/pear run <production-link> --args="--config /etc/hyperident-gateway/config.json"
	112	Restart=always
	113	RestartSec=10
	114	StandardOutput=journal
	115	StandardError=journal
	116
	117	[Install]
	118	WantedBy=multi-user.target
	119	```
	120
	121	Replace `<production-link>` with your actual pear:// link.
	122
	123	Enable and start:
	124
	125	```bash
	126	sudo systemctl daemon-reload
	127	sudo systemctl enable hyperident-gateway
	128	sudo systemctl start hyperident-gateway
	129	```
	130
	131	### Updates
	132
	133	When you update the code:
	134
	135	1. Stage new version:
	136	```bash
	137	pear stage production
	138	```
	139
	140	2. Mark new release:
	141	```bash
	142	pear release production
	143	```
	144
	145	3. Seed briefly to propagate:
	146	```bash
	147	pear seed production
	148	```
	149
	150	All peers running `pear run <link>` will automatically update to the new release on restart (or can be configured for hot-reload with Pear updates API).
	151
	152	## Traditional Deployment (Bare Runtime)
	153
	154	For direct deployment without Pear:
	155
	156	### Prerequisites
	157
	158	- Bare runtime installed
	159	- Root access (for TUN device creation)
	160
	161	### Local Development
	162
	163	```bash
	164	sudo bare gateway.js --config ./config/gateway-config.json
	165	```
	166
	167	### Installing on Remote Machine
	168
	169	1. Clone the repository:
	170
	171	Via P2P VPN (if already on network):
	172	```bash
	173	git clone git://10.22.0.1/hyperident-gateway.git
	174	cd hyperident-gateway
	175	```
	176
	177	Via SSH:
	178	```bash
	179	scp -r /path/to/hyperident-gateway fleeky@7rnx.net:/opt/
	180	```
	181
	182	2. Install dependencies:
	183
	184	```bash
	185	npm install --omit=dev
	186	```
	187
	188	3. Create configuration:
	189
	190	```bash
	191	sudo mkdir -p /etc/hyperident-gateway
	192	sudo cp config/gateway-config.json /etc/hyperident-gateway/
	193	```
	194
	195	Edit `/etc/hyperident-gateway/config.json` for the specific machine.
	196
	197	4. Create systemd service:
	198
	199	Use the provided service file at `systemd/hyperident-gateway.service` or follow Pear deployment systemd section above.
	200
	201	## Configuration
	202
	203	The gateway requires a config file with:
	204
	205	```json
	206	{
	207	"version": "1.0.0",
	208	"gateway": {
	209	"virtualIP": "10.22.0.X",
	210	"subnet": "10.22.0.0/16",
	211	"tunDevice": "tun0",
	212	"mtu": 1500,
	213	"networkTopic": "hyperident-network"
	214	}
	215	}
	216	```
	217
	218	Each gateway should have a unique `virtualIP` within the subnet.
	219
	220	## Troubleshooting
	221
	222	### Pear Issues
	223
	224	App won't stage:
	225	- Check package.json has valid `name` and `pear` fields
	226	- Run `pear doctor` for diagnostics
	227
	228	Peers can't download app:
	229	- Ensure `pear seed <channel>` is running
	230	- Check firewall allows UDP traffic
	231	- Verify the link is correct
	232
	233	### Gateway Issues
	234
	235	TUN device creation fails:
	236	- Ensure running as root
	237	- Check `utun` module is installed
	238
	239	Can't ping other gateways:
	240	- Verify both gateways use same `networkTopic`
	241	- Check firewall allows Hyperswarm traffic
	242	- Review gateway logs for connection status
	243
	244	## Links
	245
	246	- [Pear Documentation](https://docs.pears.com)
	247	- [Hyperswarm](https://github.com/holepunchto/hyperswarm)
	248	- [UTUN](https://github.com/holepunchto/utun)

hyperident-gateway commits / f531002

Changed files (1) +248 -0