# 🚀 Ospabhost 8.1 - S3 Object Storage Platform

Modern S3-compatible object storage management platform with billing, blog, and support ticketing system.

![Version](https://img.shields.io/badge/version-8.1-blue)
![Node.js](https://img.shields.io/badge/node.js-v24+-green)
![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)

[🇷🇺 Русская версия](README_ru.md)

---

## 📋 Table of Contents

- [About](#about)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Quick Start](#quick-start)
- [Deployment](#deployment)
- [Project Structure](#project-structure)
- [API Documentation](#api-documentation)
- [Contributing](#contributing)

---

## 🎯 About

**Ospabhost 8.1** is a comprehensive S3-compatible object storage management platform built on MinIO, featuring:

- 💾 **S3 Object Storage** - Full-featured MinIO-based storage with AWS S3 compatibility
- 📝 **Blog CMS** - Built-in content management system with Rich Text editor
- 🎫 **Support Tickets** - Priority-based ticketing system with attachments
- 💰 **Billing** - Balance management with check verification
- 🔐 **Authentication** - JWT + OAuth (Google, GitHub, Yandex) + QR auth
- 🔔 **Notifications** - Web Push and email notifications
- 🌓 **Dark Theme** - Automatic dark mode with system preference detection
- 📊 **Admin Panel** - Complete administration dashboard

---

## 🌟 Features

### For Users

#### S3 Object Storage
- **Bucket Management**
  - Create buckets with region selection
  - Custom pricing plans (per GB, bandwidth, requests)
  - Public/private access control
  - Object versioning
  - Presigned URLs for temporary access
  
- **Multiple File Upload Methods**
  - Drag & Drop interface
  - Multiple file selection
  - Folder upload with structure preservation (webkitdirectory)
  - Upload from URI/URL
  - Real-time progress tracking (percentage, speed in MB/s)
  - Upload cancellation
  
- **MinIO Console Access**
  - One-click console credentials (generated weekly)
  - Direct bucket management through MinIO UI
  - Advanced S3 operations

#### Blog
- Read articles and comment
- URL-based article access
- View counters
- RSS feed support

#### Support Tickets
- Create tickets with priority (low/normal/high/urgent) and category
- File attachments (up to 5 files, 10MB each)
- Real-time messaging with operators
- Status tracking: open → in_progress → awaiting_reply → resolved → closed
- Ticket history

#### Account & Security
- Balance management with check uploads
- Active session management (IP, device, browser tracking)
- Login history
- QR authentication (Telegram Web style)
- Individual session termination

### For Operators
- View and respond to tickets
- Automatic ticket assignment
- Priority and status management
- Internal notes (invisible to users)

### For Administrators
- **User Management**
  - View all users
  - Edit balance
  - Assign operator role
  - Block/unblock accounts

- **Pricing Management**
  - Configure S3 storage plans
  - Custom pricing (per GB, bandwidth, API requests)
  - Tariff categories

- **Blog Management**
  - Create/edit articles with Quill.js editor
  - Image uploads
  - Comment moderation
  - SEO settings

- **Check Verification**
  - Approve/reject balance top-up requests
  - View uploaded receipts

- **Testing Tools**
  - Send test push notifications
  - Send test emails
  - Log monitoring

---

## 🛠️ Tech Stack

### Backend
- **Node.js 24+** with Express.js
- **TypeScript 5.x** for type safety
- **Prisma ORM** with MySQL 8+
- **MinIO SDK** for S3 operations
- **JWT** + **Passport.js** for authentication
- **Multer** for file uploads
- **web-push** for notifications
- **Nodemailer** for emails
- **PM2** for process management

### Frontend
- **React 18** with TypeScript
- **Vite 7.x** for fast builds
- **React Router 6** for navigation
- **Tailwind CSS 3.3** for styling
- **React Quill** for rich text editing
- **Axios** for API calls
- **i18next** for localization (en/ru)
- **Service Worker** for push notifications

### Infrastructure
- **MySQL 8+** database
- **MinIO** S3-compatible storage
- **Nginx** reverse proxy
- **PM2** process manager
- **Git** (Gitea + GitHub)
- **Let's Encrypt** SSL

---

## 🚀 Quick Start

### Prerequisites
- Node.js 24+
- MySQL 8+
- MinIO server

### Installation

1. **Clone Repository**
```bash
git clone http://localhost:4000/ospab/ospab.host.git
cd ospab.host/ospabhost
```

2. **Backend Setup**
```bash
cd backend
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Database setup
npx prisma migrate deploy
npx prisma generate
npx prisma db seed

# Start development server
npm run dev
```

3. **Frontend Setup**
```bash
cd ../frontend
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your API URL

# Start development server
npm run dev
```

4. **Access Application**
- Frontend: http://localhost:5173
- Backend API: http://localhost:5000
- Dashboard: http://localhost:5173/dashboard

First registered user automatically becomes administrator.

---

## 🌐 Deployment

### Production Setup

1. **Install Dependencies**
```bash
# Node.js 24
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# MySQL and Nginx
sudo apt install mysql-server nginx

# PM2
sudo npm install -g pm2
```

2. **Backend Deployment**
```bash
cd /var/www/ospab.host/ospabhost/backend

npm install
cp .env.example .env
# Configure .env

# Create upload directories
mkdir -p uploads/{checks,blog,tickets}
chmod 755 uploads/*

# Database migrations
npx prisma migrate deploy
npx prisma generate

# Build and start
npm run build
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```

3. **Frontend Build**
```bash
cd ../frontend
npm install
npm run build
```

4. **Nginx Configuration**
```nginx
server {
    listen 80;
    server_name ospab.host;

    # Frontend
    location / {
        root /var/www/ospab.host/ospabhost/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # Backend API
    location /api {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # WebSocket
    location /ws {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # Static uploads
    location /uploads {
        alias /var/www/ospab.host/ospabhost/backend/uploads;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    client_max_body_size 50M;
}
```

5. **SSL Certificate**
```bash
sudo certbot --nginx -d ospab.host -d api.ospab.host
```

### Update Deployment
```bash
cd /var/www/ospab.host/ospabhost

# Pull latest changes
git pull

# Backend update
cd backend
npm install
npx prisma generate
npm run build
pm2 restart all

# Frontend update
cd ../frontend
npm install
npm run build

# Reload Nginx
sudo systemctl reload nginx
```

---

## 📁 Project Structure

```
ospab.host/
├── ospabhost/
│   ├── backend/
│   │   ├── src/
│   │   │   ├── modules/
│   │   │   │   ├── auth/          # Authentication (JWT, OAuth, QR)
│   │   │   │   ├── storage/       # S3 Storage (MinIO)
│   │   │   │   ├── blog/          # Blog CMS
│   │   │   │   ├── ticket/        # Support tickets
│   │   │   │   ├── check/         # Payment checks
│   │   │   │   ├── notification/  # Push & Email
│   │   │   │   ├── tariff/        # Pricing plans
│   │   │   │   ├── session/       # Session management
│   │   │   │   └── admin/         # Admin panel
│   │   │   ├── middleware/        # Express middleware
│   │   │   ├── prisma/            # Prisma client
│   │   │   ├── routes/            # Route definitions
│   │   │   ├── utils/             # Utilities
│   │   │   ├── websocket/         # WebSocket server
│   │   │   ├── index.ts           # Main entry point
│   │   │   └── server.ts          # Express server
│   │   ├── prisma/
│   │   │   ├── schema.prisma      # Database schema
│   │   │   ├── migrations/        # DB migrations
│   │   │   └── seed.ts            # Seed data
│   │   ├── uploads/               # User uploads
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── ecosystem.config.js    # PM2 config
│   │
│   └── frontend/
│       ├── src/
│       │   ├── pages/
│       │   │   ├── index.tsx           # Homepage
│       │   │   ├── login.tsx           # Login
│       │   │   ├── register.tsx        # Registration
│       │   │   ├── pricing.tsx         # Pricing plans
│       │   │   ├── blog.tsx            # Blog list
│       │   │   ├── blogpost.tsx        # Blog post
│       │   │   └── dashboard/
│       │   │       ├── mainpage.tsx        # Dashboard main
│       │   │       ├── summary.tsx         # Overview
│       │   │       ├── storage.tsx         # Storage buckets
│       │   │       ├── storage-bucket.tsx  # Bucket management
│       │   │       ├── tickets/            # Ticket system
│       │   │       ├── billing.tsx         # Balance
│       │   │       ├── settings.tsx        # Settings
│       │   │       ├── notifications.tsx   # Notifications
│       │   │       ├── admin.tsx           # Admin panel
│       │   │       ├── blogadmin.tsx       # Blog admin
│       │   │       └── blogeditor.tsx      # Post editor
│       │   ├── components/
│       │   │   ├── header.tsx          # Site header
│       │   │   ├── footer.tsx          # Site footer
│       │   │   └── PrivateRoute.tsx    # Protected routes
│       │   ├── context/
│       │   │   ├── authcontext.tsx     # Auth state
│       │   │   └── ThemeContext.tsx    # Theme state
│       │   ├── services/
│       │   │   └── apiClient.ts        # Axios client
│       │   ├── i18n/                   # Localization
│       │   ├── App.tsx
│       │   └── main.tsx
│       ├── public/
│       │   ├── service-worker.js       # Push notifications
│       │   └── robots.txt
│       ├── package.json
│       ├── vite.config.ts
│       └── tailwind.config.js
│
├── README.md                   # This file (English)
└── README_ru.md                # Russian version
```

---

## 📚 API Documentation

### Public Endpoints

#### Authentication
```http
POST /api/auth/register
POST /api/auth/login
GET  /api/auth/google
GET  /api/auth/github
GET  /api/auth/yandex
```

#### QR Authentication
```http
POST /api/qr-auth/generate       # Generate QR code
GET  /api/qr-auth/status/:code   # Check status (polling)
POST /api/qr-auth/confirm        # Confirm login (mobile)
```

#### Blog
```http
GET /api/blog/posts              # List posts
GET /api/blog/posts/:url         # Get post by URL
POST /api/blog/posts/:id/comments # Add comment
```

#### Storage Plans
```http
GET /api/storage/plans           # List pricing plans
```

### Protected Endpoints

All requests require: `Authorization: Bearer <JWT_TOKEN>`

#### S3 Storage
```http
GET    /api/storage/buckets                    # List buckets
POST   /api/storage/buckets                    # Create bucket
GET    /api/storage/buckets/:id                # Get bucket info
DELETE /api/storage/buckets/:id                # Delete bucket
PUT    /api/storage/buckets/:id                # Update settings

GET    /api/storage/buckets/:id/objects        # List objects
POST   /api/storage/buckets/:id/upload         # Upload file
POST   /api/storage/buckets/:id/upload-from-uri # Upload from URL
POST   /api/storage/buckets/:id/upload-directory # Upload folder
DELETE /api/storage/buckets/:id/objects        # Delete objects

POST   /api/storage/buckets/:id/presign        # Generate presigned URL
POST   /api/storage/buckets/:id/console-credentials # Get console access
```

#### Support Tickets
```http
GET    /api/tickets              # List user tickets
POST   /api/tickets              # Create ticket
GET    /api/tickets/:id          # Get ticket details
POST   /api/tickets/:id/messages # Send message
PATCH  /api/tickets/:id/status   # Update status (operators)
POST   /api/tickets/:id/assign   # Assign operator
PATCH  /api/tickets/:id/close    # Close ticket
```

#### Session Management
```http
GET    /api/sessions             # List active sessions
GET    /api/sessions/history     # Login history
DELETE /api/sessions/:id         # Terminate session
DELETE /api/sessions/others/all  # Terminate all other sessions
```

#### Admin Endpoints
```http
GET  /api/admin/users            # List all users
PUT  /api/admin/users/:id        # Edit user

GET  /api/admin/checks           # List payment checks
PUT  /api/admin/checks/:id       # Approve/reject check

GET  /api/blog/admin/posts       # List all posts
POST /api/blog/admin/posts       # Create post
PUT  /api/blog/admin/posts/:id   # Update post
DELETE /api/blog/admin/posts/:id # Delete post
POST /api/blog/admin/upload-image # Upload image

GET  /api/blog/admin/comments    # List all comments
PATCH /api/blog/admin/comments/:id # Moderate comment
DELETE /api/blog/admin/comments/:id # Delete comment

PUT  /api/storage/plans/:id      # Update pricing plan

POST /api/admin/test/push-notification # Test push
POST /api/admin/test/email-notification # Test email
```

---

## 🐛 Troubleshooting

### Backend Issues

**Prisma Client missing models**
```bash
cd backend
npx prisma generate
npm run build
pm2 restart all
```

**OAuth returns 404**
- Check `.env` for `GOOGLE_CLIENT_ID`, `GITHUB_CLIENT_ID`, `YANDEX_CLIENT_ID`
- Verify `oauthRoutes` is imported in `index.ts`
- Restart server

**Push notifications not working**
- Verify VAPID keys in `.env`
- Ensure `service-worker.js` is registered
- Use HTTPS in production

### Frontend Issues

**Session not persisting**
- Ensure `login()` in `authcontext.tsx` uses async/await
- Verify JWT token is saved to localStorage
- Check `bootstrapSession()` is called after login

**Dark theme not applying**
- Verify `ThemeProvider` wraps `App`
- Check `tailwind.config.js` has `darkMode: 'class'`
- Ensure components use `dark:` classes

**File upload fails**
- Check directory permissions: `chmod 755 uploads/*`
- Verify Nginx serves `/uploads`
- Check Nginx `client_max_body_size 50M;`

### S3 Storage Issues

**Cannot create bucket**
- Verify MinIO connection
- Check MinIO credentials in `.env`
- Ensure user has sufficient balance

**Console credentials don't work**
- Credentials are valid for 7 days
- Generate new credentials from dashboard
- Verify MinIO endpoint is accessible

---

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/AmazingFeature`
3. Commit changes: `git commit -m 'feat: add amazing feature'`
4. Push to branch: `git push origin feature/AmazingFeature`
5. Open a Pull Request

### Commit Convention

We use [Conventional Commits](https://www.conventionalcommits.org/):

```bash
feat(storage): add folder upload support
fix(ticket): auto-unassign on close
docs: update API documentation
refactor(auth): improve error handling
```

### Development Workflow

```bash
# Backend development
cd backend
npm run dev

# Frontend development
cd frontend
npm run dev

# Database migrations
npx prisma migrate dev --name migration_name
npx prisma generate

# Build for production
npm run build
```

---

## 📄 License

MIT License

---

## 📞 Contact

- **Website:** [ospab.host](https://ospab.host)
- **Email:** support@ospab.host
- **Telegram:** [@ospab](https://t.me/ospab)
- **Gitea:** http://localhost:4000/ospab/ospab.host
- **GitHub:** https://github.com/ospab/ospabhost8.1

---

## 🙏 Acknowledgments

- [MinIO](https://min.io/) - S3-compatible object storage
- [Prisma](https://www.prisma.io/) - Next-generation ORM
- [React](https://react.dev/) - UI library
- [Tailwind CSS](https://tailwindcss.com/) - CSS framework
- [Quill](https://quilljs.com/) - Rich text editor
- [Passport.js](https://www.passportjs.org/) - Authentication middleware

---

**Version:** 8.1  
**Updated:** January 5, 2026  
**Git:** ospab <ospab@ospab.host>