Project Mycelium Marketplace

A compute and services marketplace built with Rust/Actix-Web, hero_osis (JSON-RPC), hero_ledger (NEAR blockchain), and Tera templates. Supports standalone or subpath deployment behind a reverse proxy.

Live demo: https://projectmycelium.com/marketplace/demo

Quick Start

Option A: Docker Compose with Hero Backend

Runs the full stack: marketplace + hero_osis (data) + hero_ledger (blockchain).

cp .env.example .env
make key                     # generate SECRET_KEY

# Start marketplace + hero_osis + hero_ledger
docker compose -f docker-compose.yml -f docker-compose.hero.yml \
  --profile hero up -d

# http://localhost:8000

Option B: Native Rust with Fixtures (no external services)

Runs the marketplace locally using in-memory/JSON fixture data. No hero_osis or hero_ledger required.

cp .env.example .env
make key
make fixtures-run            # APP_DATA_SOURCE=fixtures, reads ./user_data
# http://localhost:9999

Option C: Native Rust with Hero Backend

Requires hero_osis (port 3377) and hero_ledger (port 3030) running separately.

cp .env.example .env
make key
APP_BACKEND=hero \
  HERO_OSIS_URL=http://localhost:3377 \
  HERO_OSIS_CONTEXT=root \
  HERO_LEDGER_RPC_URL=http://localhost:3030 \
  HERO_LEDGER_ROOT=local.hero \
  cargo run --bin projectmycelium
# http://localhost:9999

Architecture

The application uses a ServiceProvider dependency injection container with 14 trait objects. Controllers obtain the ServiceProvider from Actix-Web app data and call methods through trait interfaces. The concrete backend is selected at startup.

Service Traits (14 total)

Trait	Responsibility
ProductCatalog	Product listings, search, categories
UserAuth	Registration, login, password hashing (argon2)
UserProfile	User profile CRUD, avatars
OrderManager	Order lifecycle, history
CartManager	Shopping cart operations
WalletManager	Credits balance, transactions, top-up
MessagingManager	User-to-user messaging
SSHKeyManager	SSH key CRUD for compute access
ServiceProviderManager	Service provider onboarding, dashboards
AppProviderManager	Application provider management
ResourceProviderManager	Farmer/resource provider management
NodeRentalManager	Dedicated node rentals
SliceRentalManager	Compute slice rentals
SliceAssignmentManager	Slice-to-node assignment

Two Backends

• ServiceProvider::fixtures() -- In-memory/JSON fixtures from ./user_data. No external services needed. Ideal for local development and testing.
• ServiceProvider::hero() -- hero_osis JSON-RPC (port 3377) for all data operations + hero_ledger NEAR blockchain (port 3030) for wallet/payment settlement. Used in deployment.

Data Flow

Browser --> Actix-Web (Marketplace)
               |
               +--> ServiceProvider (trait dispatch)
                       |
                       +-- fixtures backend --> local JSON files (./user_data)
                       |
                       +-- hero backend -----> hero_osis (JSON-RPC :3377) --> persistent storage
                                       +-----> hero_ledger (NEAR :3030) --> blockchain settlement

Technology Stack

• Web framework: Rust, Actix-Web 4, Tera templates
• Data backend: hero_osis (JSON-RPC) -- schema-first data server
• Blockchain: hero_ledger (NEAR protocol) -- SPORE token balances, on-chain settlement
• Auth: Username/password with argon2 hashing; optional Gitea OAuth
• Sessions: actix-session cookie store, JWT for protected routes
• Security: HttpOnly cookies, SameSite=Lax, X-Frame-Options: DENY, CSP-friendly (no inline JS)

Key Concepts

• Products: Apps, services, and compute resources listed at /marketplace
• Slices: Compute resources on the Mycelium Grid at /marketplace/compute
• Credits Wallet: Balance, transactions, top-up at /dashboard/wallet
• Roles: End user, Farmer, Application Provider, Service Provider dashboards
• Cart/Checkout: Standard e-commerce flow at /cart, /checkout

Subpath Deployment

The app supports running under a URL prefix (e.g., /marketplace/demo) via the APP_BASE_PATH environment variable. When set:

• All templates render links with the base path prefix
• ResponseBuilder::redirect() auto-prepends the base path
• JS uses window.BASE_PATH for client-side routing
• Works behind k3s/Traefik or any reverse proxy

# In .env or deploy/single-vm/app.env:
APP_BASE_PATH=/marketplace/demo
PM_SSL_MODE=off   # when behind a reverse proxy that handles SSL

See docs/PRODUCTION_DEPLOYMENT.md and docs/DEVELOPMENT_DEPLOYMENT.md.

Deployment

Both deployment targets pull a pre-built Docker image from forge.ourworld.tf. Build and push first:

docker login forge.ourworld.tf -u YOUR_USERNAME   # one-time
make ship                                         # build + push image

Dev/Test: TFGrid VM

Provisions a VM on ThreeFold Grid, pulls the image, runs Docker Compose + Caddy SSL. Runs at projectmycelium.org/marketplace/demo.

cd deploy/single-vm
cp app.env.example app.env   # fill in credentials
make all                     # provision VM + pull image + DNS + test

See docs/DEVELOPMENT_DEPLOYMENT.md for the full guide.

Production: k3s cluster (Hetzner)

Runs as a pod inside the Hetzner k3s cluster. Devops applies Kubernetes manifests. Runs at projectmycelium.com/marketplace/demo.

kubectl apply -f deploy/k8s/

See docs/PRODUCTION_DEPLOYMENT.md for the full guide.

Configuration

.env (app config)

Variable	Description	Default
SECRET_KEY	Session encryption key (base64, 64 bytes)	required
APP_BACKEND	Backend selection: fixtures or hero	fixtures
APP_DATA_SOURCE	Data source: fixtures (JSON files) or hero (OSIS)	fixtures
APP_FIXTURES_PATH	Path to fixture data directory	./user_data
APP_BASE_PATH	URL prefix for subpath deployment	(empty)
HERO_OSIS_URL	hero_osis JSON-RPC endpoint	http://hero-osis:3377
HERO_OSIS_CONTEXT	hero_osis context name	root
HERO_LEDGER_RPC_URL	hero_ledger NEAR RPC endpoint	http://hero-ledger:3030
HERO_LEDGER_ROOT	hero_ledger root account	local.hero
GITEA_CLIENT_ID	Gitea OAuth client ID (optional)	-
GITEA_CLIENT_SECRET	Gitea OAuth client secret (optional)	-
ENVIRONMENT_BANNER	Show env banner: demo, development, etc.	(none)

See .env.example for all options.

deploy/single-vm/app.env (TFGrid deployment config)

Variable	Description	Default
PM_ENV	prod or dev	prod
BASE_DOMAIN	Domain name	projectmycelium.org
APP_BASE_PATH	Subpath prefix	(empty)
PM_SSL_MODE	auto (Caddy SSL) or off (behind proxy)	auto
CLOUDFLARE_API_TOKEN	For DNS automation	-
GIT_OURWORLD_TOKEN	Forgejo repo access	-

See deploy/single-vm/app.env.example for all options.

Repository Layout

src/
  main.rs                  # Actix-Web server entry point
  lib.rs                   # Library crate
  bin/                     # Additional binary targets
  config/                  # App + OAuth config
  controllers/             # Request handlers
  middleware/              # Auth, security headers
  models/                  # Data models, context builders
  routes/                  # Route definitions
  services/
    provider.rs            # ServiceProvider DI container
    traits/                # 14 service trait definitions
    impl_fixtures/         # Fixture backend implementations
    impl_hero/             # hero_osis + hero_ledger implementations
    factory.rs             # Backend factory (fixtures vs hero)
    ...                    # Domain services (product, order, grid, etc.)
  utils/                   # ResponseBuilder, helpers
  views/                   # Tera HTML templates
  static/                  # CSS, JS, images
deploy/
  k8s/                     # Kubernetes manifests for production (k3s)
  single-vm/               # TFGrid single-VM deployment (dev/test)
    tf/                    # OpenTofu config for VM provisioning
    scripts/setup.sh       # VM setup script
    app.env.example        # Deployment config template
    Makefile               # Deploy targets (make all, make dns, etc.)
docs/                      # Documentation
  PRODUCTION_DEPLOYMENT.md     # Production k3s deployment guide
  DEVELOPMENT_DEPLOYMENT.md    # Dev/test TFGrid VM deployment guide
  architecture.md              # Architecture overview
  archive/                     # Historical design docs
scripts/                   # Development helper scripts
  smoke-test.sh            # 109 endpoint smoke tests
  seed-hero-osis.sh        # Seed hero_osis with demo data
  build_lib.sh             # Shared build configuration
  dev-start.sh             # Start local Docker environment
  dev-stop.sh              # Stop local Docker environment
  dev-test.sh              # Run automated tests
tests/
  e2e/                     # Playwright end-to-end tests (103 tests)
user_data/                 # Fixture data (JSON files for local dev)
docker-compose.yml         # Base compose (marketplace + hero_osis + hero_ledger)
docker-compose.hero.yml    # Hero backend overlay (prebuilt registry images)
docker-compose.prod.yml    # Production compose (Caddy + SSL)
docker-compose.demo.yml    # Demo environment compose
Dockerfile                 # Multi-stage Rust build
Makefile                   # Development and deployment targets

Development Scripts

make build             # cargo build --release
make run               # Build and run the application
make dev               # Run in development mode with debug logging
make fixtures-run      # Run with filesystem fixtures (no hero_osis needed)
make check             # Fast cargo check without building
make fmt               # Format and lint code (cargo fmt + clippy)

make local-up          # Start Docker Compose environment
make local-down        # Stop and remove volumes
make local-rebuild     # Rebuild containers after code changes
make local-logs        # Tail container logs

make ship              # Build + push Docker image to forge.ourworld.tf
make release           # Build + push versioned release
make docker-login      # Log in to Forgejo container registry

make key               # Generate a new SECRET_KEY in .env
make check-errors      # cargo check, errors written to /tmp/cargo_errors_only.log
make help              # Show all available targets

Testing

Unit Tests

make test              # cargo test --lib
make test-all          # cargo test (all targets)

Smoke Tests (109 endpoint checks)

Verifies all public routes return expected HTTP status codes against a running instance.

bash scripts/smoke-test.sh http://localhost:8000
# or with a base path:
bash scripts/smoke-test.sh https://projectmycelium.org/marketplace/demo

End-to-End Tests (103 Playwright tests)

Full browser-driven tests covering user flows, cart, checkout, dashboards, and more.

cd tests/e2e
npm install
npx playwright test