Shogun Relay is a production-ready connection hub that unifies GunDB and IPFS into a single solution.
- GunDB Relay — WebSocket relay with SQLite/RADISK persistence and WebRTC support
- IPFS Integration — Upload, pin, manage, and preview IPFS content via REST API
- Admin Dashboard — Modern React-based UI for monitoring and management
- Network Federation — Relay discovery, storage proofs, and reputation system
git clone <repository-url>
cd shogun-relay
./docker-start.sh
curl http://localhost:8765/healthWhen deploying via CapRover, you must configure the Container HTTP Port in the app settings to correctly route NGINX traffic.
- Go to your CapRover Dashboard -> Apps -> shogun-relay -> HTTP Settings.
- Set Container HTTP Port to
8765. - Click Save & Update.
(Failure to do this will result in 502 Bad Gateway or 504 Gateway Timeout errors).
cd shogun-relay/relay
npm install
npm run start:devAdmin dashboards: http://localhost:8765/
Create a .env file with essential variables:
| Variable | Description | Default |
|---|---|---|
ADMIN_PASSWORD |
Admin token for all routes | (required) |
IPFS_API_URL |
IPFS API endpoint | http://127.0.0.1:5001 |
RELAY_PORT |
HTTP port | 8765 |
STORAGE_TYPE |
sqlite or radisk |
sqlite |
See Environment Variables for complete reference.
| Path | Description |
|---|---|
/dashboard |
New React Dashboard (Recommended) |
/admin |
Legacy entry (redirects) |
/endpoints |
API reference explorer |
| API Reference | Complete REST API documentation | | Environment Variables | All configuration options | | Node Operator Guide | Run your own relay | | Network Federation | Relay discovery & reputation | | Relay Keys | Keypair configuration |
| Endpoint | Description |
|---|---|
GET /gun |
WebSocket for Gun clients |
GET /health |
Health check |
GET /api/v1/system/stats |
System statistics |
| Endpoint | Description |
|---|---|
POST /api/v1/ipfs/upload |
Upload single file |
POST /api/v1/ipfs/upload-directory |
Upload multiple files as directory (maintains structure) |
GET /api/v1/ipfs/cat/:cid |
Stream content |
POST /api/v1/ipfs/pin/add |
Pin content |
GET /api/v1/ipfs/pin/ls |
List pins |
| Endpoint | Description |
|---|---|
GET /api/v1/user-uploads/system-hashes-map |
Get complete file metadata map |
POST /api/v1/user-uploads/save-system-hash |
Save file metadata (admin) |
DELETE /api/v1/user-uploads/remove-system-hash/:cid |
Remove file metadata |
Full API documentation at /endpoints or see API Reference.
shogun-relay/
├── relay/
│ ├── src/
│ │ ├── index.ts # Express + Gun bootstrap
│ │ ├── routes/ # REST endpoints
│ │ └── public/ # Admin frontends
├── docs/ # Documentation
└── docker/ # Docker utilities
| Issue | Solution |
|---|---|
| Gun clients fail to connect | wscat -c ws://localhost:8765/gun |
| IPFS API unauthorized | Check IPFS_API_TOKEN |
| Admin UI "token required" | Enter token at /admin first |
- Fork the repository
- Create a feature branch
- Add tests when relevant
- Submit a pull request
MIT License © Shogun contributors. See LICENSE.