153 lines
5.6 KiB
Markdown
153 lines
5.6 KiB
Markdown
# Project Mycelium
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Rust and Cargo (latest stable version)
|
|
- Git
|
|
|
|
### Setup
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://git.ourworld.tf/tfgrid_research/projectmycelium
|
|
cd projectmycelium
|
|
```
|
|
|
|
2. Build the project:
|
|
```bash
|
|
cargo build
|
|
```
|
|
|
|
3. Run the application:
|
|
```bash
|
|
cargo run
|
|
```
|
|
|
|
To run with a different port:
|
|
|
|
```
|
|
cargo run -- --port 9998
|
|
```
|
|
|
|
4. Open your browser and navigate to `http://localhost:9999`
|
|
|
|
## Architecture
|
|
|
|
Project Mycelium is a Rust web app built on Actix Web.
|
|
|
|
- **Backend (Rust/Actix Web):**
|
|
- Routes: `src/routes/mod.rs`
|
|
- Controllers: `src/controllers/`
|
|
- Middleware: `src/middleware/`
|
|
- Config: `src/config/`
|
|
- Library crate: `src/lib.rs`; Binary: `src/main.rs`
|
|
- **Views and Static Assets:**
|
|
- Templates (Tera): `src/views/`
|
|
- Frontend JS: `src/static/js/` (CSP-compliant; no inline JS)
|
|
- **API Contract:**
|
|
- Responses follow a `ResponseBuilder` JSON envelope. Frontend unwraps with:
|
|
```js
|
|
const result = await response.json();
|
|
const data = result.data || result;
|
|
```
|
|
- Display rules: render "No limit" for null/undefined numeric limits; prefer server-formatted amounts.
|
|
|
|
## Marketplace Overview
|
|
|
|
- **Roles & Areas**
|
|
- End user, Farmer, Application Provider, Service Provider dashboards: `/dashboard/{user|farmer|application-provider|service-provider}` (see `DashboardController` in `src/controllers/dashboard.rs`).
|
|
- Public catalogue: `/marketplace`, `/products`, `/products/{id}`, `/cart`, `/checkout`.
|
|
- **Core Concepts**
|
|
- Products (apps, services, compute). Orders and cart lifecycle.
|
|
- Slices (compute resources) on the ThreeFold Grid, publicly listed at `/marketplace/compute`.
|
|
- Credits wallet for balance, transactions, quick top-up, and auto top-up.
|
|
- **Primary Flows**
|
|
- Browse products: `/products`, details at `/products/{id}`; APIs under `/api/products*`.
|
|
- Cart & checkout: `/cart`, `/checkout`; APIs under `/api/cart*` and `/api/orders*`.
|
|
- Slice rental: forms at `/marketplace/slice/rent*`; APIs include `/api/products/{id}/rent` and `/api/marketplace/rent-slice`.
|
|
- Wallet & credits: dashboard page `/dashboard/wallet`; APIs under `/api/wallet/*` (balance, transactions, instant purchase, quick top-up, auto top-up).
|
|
- Settings & SSH keys: `/dashboard/settings`; APIs under `/api/dashboard/settings/*` and `/api/dashboard/ssh-keys*`.
|
|
|
|
## Security & CSP
|
|
|
|
- **Security headers** (via `SecurityHeaders` in `src/middleware/mod.rs`, enabled in `src/main.rs`):
|
|
- `X-Content-Type-Options: nosniff`
|
|
- `X-Frame-Options: DENY`
|
|
- `X-XSS-Protection: 1; mode=block`
|
|
- **CSP practice**:
|
|
- No inline JavaScript in templates; all JS under `src/static/js/`.
|
|
- Templates (Tera) should hydrate data via JSON blocks, keeping CSP-friendly structure.
|
|
- Note: A `Content-Security-Policy` response header is not set yet. Recommended policy (production):
|
|
```
|
|
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'
|
|
```
|
|
Adjust as needed for external assets or APIs.
|
|
|
|
### Authentication & Sessions
|
|
|
|
- **Auth flows** (`src/routes/mod.rs`):
|
|
- Gitea OAuth when `GITEA_CLIENT_ID` is set (see `src/config/oauth.rs`).
|
|
- Username/password login otherwise (`src/controllers/auth.rs`).
|
|
- **Password hashing**: `bcrypt` for stored password hashes.
|
|
- **Sessions** (`actix-session`):
|
|
- Cookie store with `HttpOnly` and `SameSite=Lax`, TTL 2h, name `project_mycelium_session`.
|
|
- `cookie_secure=false` in dev; enable `true` behind HTTPS in production.
|
|
- **JWT** (`auth_token` cookie):
|
|
- Set as `HttpOnly`; `secure=false` in dev. Enable `secure=true` in production.
|
|
- Dashboard and protected scopes are wrapped by `JwtAuth` middleware.
|
|
|
|
## Repository Layout
|
|
|
|
- `docs/dev/` — Design, guides, and methodologies
|
|
- Roadmap and UX contracts: `docs/dev/design/projectmycelium-roadmap.md`
|
|
- `docs/ops/` — Ops notes and runbooks
|
|
- `config/zinit/` — Service definitions (dev/prod)
|
|
- `scripts/` — Utilities and deployment helpers
|
|
- `src/` — Application source (routes, controllers, views, static assets)
|
|
- `tests/frontend_ux/` — UX test suite (feature-gated)
|
|
- `user_data/` — Test fixtures and persistent data used by UX tests
|
|
|
|
## Documentation
|
|
|
|
Key design and UX contract documentation lives in:
|
|
|
|
- `docs/dev/design/projectmycelium-roadmap.md`
|
|
- Canonical UX contracts (e.g., SSH Keys, Settings, Auto Top-Up)
|
|
- Proven debugging methodology and marketplace-wide audit plan
|
|
|
|
## Testing
|
|
|
|
UX tests are written in Rust using WebDriver clients (`thirtyfour`, `fantoccini`) and run under the `ux_testing` feature flag.
|
|
|
|
- **Run all UX tests:**
|
|
```bash
|
|
cargo test --features ux_testing -- --nocapture
|
|
```
|
|
- **Individual suites** (from `Cargo.toml`):
|
|
- `public_access_ux`, `authentication_ux`, `purchase_cart_ux`, `credits_wallet_ux`
|
|
- `marketplace_categories_ux`, `provider_dashboards_ux`, `settings_management_ux`, `ssh_key_frontend_ux`
|
|
- **Requirements:** Ensure a compatible WebDriver (e.g., ChromeDriver/GeckoDriver) is available on PATH.
|
|
- **Pattern:** Tests follow a per-step runner with persistent fixtures under `user_data/` for deterministic results.
|
|
|
|
## Develop
|
|
|
|
> see https://git.ourworld.tf/herocode/rweb_starterkit is the web starter kit
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
Once the application is running, you can access it through your web browser at `http://localhost:9999`. The default configuration provides:
|
|
|
|
- Home page at `/`
|
|
- About page at `/about`
|
|
- Contact page at `/contact`
|
|
- Login page at `/login`
|
|
- Registration page at `/register`
|
|
|
|
### Configuration
|
|
|
|
> see https://git.ourworld.tf/herocode/rweb_starterkit is the web starter kit
|