🚀 MyZubster: Complete Technical Guide to Install, Run & Contribute
A step-by-step guide to setting up your own decentralized freelance marketplace with Monero payments
A step-by-step guide to setting up your own decentralized freelance marketplace with Monero payments
📌 What is MyZubster?
MyZubster is an open-source ecosystem for peer-to-peer service marketplaces powered by Monero (XMR). It allows anyone to create a freelance marketplace where:
Buyers and sellers connect directly
Payments are made in Monero – private and untraceable
Funds are secured through multi-signature escrow
Communications are end-to-end encrypted
Users can remain anonymous with Tor/Orbot integration
🧩 Architecture Overview
MyZubster is built with three core components:
text
┌─────────────────────────────────────────────────────────────┐
│ MyZubster Ecosystem │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Gateway │◄──►│ Marketplace │◄──►│ App │ │
│ │ (Monero) │ │ (Backend) │ │ (Mobile) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Blockchain │ │ Database │ │ Users │ │
│ │ (Monero) │ │ (SQLite) │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Component Role Tech Stack
Gateway Monero payment engine Node.js, Express, MongoDB, monero-javascript
Marketplace Backend API Node.js, Express, Sequelize, SQLite, JWT
App Mobile client React Native, Expo, PGP, Tor/Orbot
🛠️ Prerequisites
Before you start, make sure you have:
Requirement Version Notes
Node.js v18 or higher node -v to check
npm v9 or higher npm -v to check
Git Latest git --version to check
Docker Latest (optional) For containerized deployment
Windows WSL2 recommended For Linux commands
Mac/Linux Native Works out of the box
🚀 Installation Guide
1️⃣ Clone the Repository
bash
git clone https://github.com/DanielIoni-creator/myzubster.git
cd myzubster
This will download all three components into a single folder.
2️⃣ Install Dependencies
📦 Gateway
bash
cd gateway
npm install
cd ..
📦 Marketplace
bash
cd marketplace
npm install
cd ..
📦 App (optional)
bash
cd app
npm install
cd ..
3️⃣ Configure Environment Variables
Each component needs a .env file. Copy the examples:
Gateway
bash
cp gateway/.env.example gateway/.env
Edit gateway/.env:
env
PORT=3000
NODE_ENV=development
MONERO_RPC_URL=http://localhost:18081
MONERO_RPC_USERNAME=
MONERO_RPC_PASSWORD=
MONGODB_URI=mongodb://localhost:27017/myzubster
JWT_SECRET=your_gateway_jwt_secret
WEBHOOK_URL=http://localhost:4000/webhook/order-update
WEBHOOK_SECRET=your_webhook_secret
LOG_LEVEL=info
Marketplace
bash
cp marketplace/.env.example marketplace/.env
Edit marketplace/.env:
env
PORT=4000
NODE_ENV=development
DATABASE_URL=sqlite:./database.sqlite
JWT_SECRET=your_marketplace_jwt_secret
MYZUBSTER_API_URL=http://localhost:3000/api
MYZUBSTER_API_TOKEN=your_admin_token
WEBHOOK_SECRET=your_webhook_secret
COMMISSION_PERCENTAGE=2.0
App
bash
cp app/.env.example app/.env
Edit app/.env:
env
API_URL=http://localhost:4000/api
GOOGLE_MAPS_API_KEY=your_google_maps_key
MONERO_NETWORK=stagenet
⚠️ Important: Never commit .env files to GitHub. They are already in .gitignore.
🔧 Running MyZubster
Option A: Running Components Separately
1️⃣ Start MongoDB (for Gateway)
Using Docker:
bash
docker run -d -p 27017:27017 --name mongodb mongo:6
Or install MongoDB locally: MongoDB Installation Guide
2️⃣ Start the Gateway
Terminal 1:
bash
cd gateway
npm run dev
Expected output:
text
🚀 Server avviato sulla porta 3000
✅ Connesso a MongoDB
📦 Database: mongodb://localhost:27017/myzubster
3️⃣ Start the Marketplace
Terminal 2:
bash
cd marketplace
npm run dev
Expected output:
text
🚀 Marketplace avviato su http://localhost:4000
✅ Connessione database stabilita
📦 Database sincronizzato
4️⃣ Start the App (React Native/Expo)
Terminal 3:
bash
cd app
npm start
or
expo start
Scan the QR code with the Expo Go app on your phone, or press a to run on Android emulator.
Option B: Using Docker Compose (All Services)
bash
From the root directory
docker-compose up -d
This starts:
MongoDB (port 27017)
Gateway (port 3000)
Marketplace (port 4000)
App (port 19000)
Verify all services are running:
bash
docker-compose ps
🧪 Testing the Flow
Once all services are running, you can test the full flow.
1️⃣ Health Checks
bash
Gateway
curl -s http://localhost:3000/api/health
Marketplace
curl -s http://localhost:4000/api/health
Expected response:
json
{"status":"OK","message":"MyZubster Gateway is running!"}
{"status":"ok","service":"Marketplace API"}
2️⃣ Register a Buyer
bash
curl -X POST http://localhost:4000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"buyer@test.com","password":"test123","username":"buyer","name":"Buyer Test"}'
3️⃣ Register a Seller
bash
curl -X POST http://localhost:4000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"seller@test.com","password":"test123","username":"seller","name":"Seller Test"}'
4️⃣ Promote Seller to Seller Role
bash
SQLite command
sqlite3 marketplace/database.sqlite "UPDATE Users SET role = 'seller' WHERE email = 'seller@test.com';"
5️⃣ Login as Buyer
bash
BUYER_TOKEN=$(curl -s -X POST http://localhost:4000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"buyer@test.com","password":"test123"}' | jq -r .token)
echo $BUYER_TOKEN
6️⃣ Login as Seller
bash
SELLER_TOKEN=$(curl -s -X POST http://localhost:4000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"seller@test.com","password":"test123"}' | jq -r .token)
echo $SELLER_TOKEN
7️⃣ Create a Skill (Seller)
bash
SKILL_ID=$(curl -s -X POST http://localhost:4000/api/skills \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SELLER_TOKEN" \
-d '{"title":"React Native Developer","description":"I build mobile apps","price":150,"category":"development"}' | jq -r .id)
echo $SKILL_ID
8️⃣ Create an Order (Buyer)
bash
ORDER_ID=$(curl -s -X POST http://localhost:4000/api/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BUYER_TOKEN" \
-d "{\"skillId\":$SKILL_ID}" | jq -r .id)
echo $ORDER_ID
9️⃣ Check Order Status
bash
curl -X GET http://localhost:4000/api/orders/$ORDER_ID \
-H "Authorization: Bearer $BUYER_TOKEN" | jq
Expected output:
json
{
"id": 1,
"buyerId": 1,
"skillId": 1,
"amount": 150,
"currency": "USD",
"moneroAddress": "8A1B2C3D...",
"moneroAmount": 150,
"status": "pending",
"network": "testnet"
}
📡 API Endpoints Reference
Public Endpoints
Method Endpoint Description
POST /api/auth/register Register new user
POST /api/auth/login Login and get JWT token
GET /api/skills List all skills
GET /api/skills/:id Get skill details
Protected Endpoints (Require JWT)
Method Endpoint Description
GET /api/auth/me Get current user profile
POST /api/skills Create new skill
PUT /api/skills/:id Update skill
DELETE /api/skills/:id Delete skill
POST /api/orders Create new order
GET /api/orders/my Get user's orders
GET /api/orders/:id Get order details
PATCH /api/orders/:id/status Update order status
🐳 Docker Deployment (Production)
1️⃣ Build Images
bash
docker-compose build
2️⃣ Run Containers
bash
docker-compose up -d
3️⃣ Check Logs
bash
docker-compose logs -f
4️⃣ Stop Services
bash
docker-compose down
🧪 Testing
Run All Tests
bash
Gateway
cd gateway && npm test
Marketplace
cd marketplace && npm test
App
cd app && npm test
Run Specific Tests
bash
cd marketplace
npm test -- auth.test.js
npm test -- skills.test.js
📂 Project Structure
text
myzubster/
├── gateway/
│ ├── src/
│ │ ├── models/
│ │ ├── routes/
│ │ ├── services/
│ │ └── utils/
│ ├── tests/
│ ├── .env.example
│ ├── package.json
│ └── server.js
├── marketplace/
│ ├── src/
│ │ ├── models/
│ │ ├── routes/
│ │ ├── middleware/
│ │ └── config/
│ ├── tests/
│ ├── .env.example
│ ├── package.json
│ └── server.js
├── app/
│ ├── src/
│ │ ├── screens/
│ │ ├── components/
│ │ ├── navigation/
│ │ └── services/
│ ├── .env.example
│ ├── package.json
│ └── App.js
├── docker-compose.yml
├── .gitignore
└── README.md
🐛 Troubleshooting
Port Already in Use
bash
Find process using port 4000
sudo netstat -tulpn | grep :4000
or
sudo lsof -i :4000
Kill the process
sudo kill -9 [PID]
Database Issues
Reset SQLite database:
bash
rm marketplace/database.sqlite
npm run dev # Will recreate database
Reset MongoDB:
bash
docker stop mongodb
docker rm mongodb
docker run -d -p 27017:27017 --name mongodb mongo:6
JWT Token Invalid
Tokens expire after 7 days. Login again to get a new token:
bash
curl -X POST http://localhost:4000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"buyer@test.com","password":"test123"}'
Gateway Connection Refused
Make sure MongoDB is running:
bash
docker ps | grep mongodb
or
ps aux | grep mongod
🤝 Contributing
We welcome contributions! Here's how:
Fork the repository
Create a branch: git checkout -b feature/your-feature
Make your changes
Run tests: npm test
Commit: git commit -m 'feat: add your feature'
Push: git push origin feature/your-feature
Open a Pull Request
Development Workflow
bash
Clone your fork
git clone https://github.com/your-username/myzubster.git
cd myzubster
Install dependencies
npm install
Start development server
npm run dev
Run tests
npm test
Build for production
npm run build
📚 Resources
Project Repository: github.com/DanielIoni-creator/myzubster
Marketplace: github.com/DanielIoni-creator/MyZubster-Marketplace
Gateway: github.com/DanielIoni-creator/MyZubsterGateway
App: github.com/DanielIoni-creator/MyZubster-App
Author DEV.to: dev.to/danielioni
📬 Contact
Author: Daniel Ioni
GitHub: @DanielIoni-creator
DEV.to: @danielioni
📄 License
This project is licensed under the MIT License.
Built with ❤️ for privacy, freedom, and decentralization.
⭐ Star the Project!
If you found this guide helpful, please star the repository on GitHub!
https://img.shields.io/github/stars/DanielIoni-creator/myzubster?style=social
Questions? Comments? Drop them below! 👇
Top comments (0)