🚀 Ospabhost 8.1 - S3 Object Storage Platform

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

🇷🇺 Русская версия

---

📋 Table of Contents

• About
• Features
• Tech Stack
• Quick Start
• Deployment
• Project Structure
• API Documentation
• 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

git clone http://localhost:4000/ospab/ospab.host.git
cd ospab.host/ospabhost

2. Backend Setup

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

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

# 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

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

cd ../frontend
npm install
npm run build

4. Nginx Configuration

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

sudo certbot --nginx -d ospab.host -d api.ospab.host

Update Deployment

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

POST /api/auth/register
POST /api/auth/login
GET  /api/auth/google
GET  /api/auth/github
GET  /api/auth/yandex

QR Authentication

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

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

GET /api/storage/plans           # List pricing plans

Protected Endpoints

All requests require: Authorization: Bearer <JWT_TOKEN>

S3 Storage

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

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

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

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

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:

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

Development Workflow

# 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
• Email: support@ospab.host
• Telegram: @ospab
• Gitea: http://localhost:4000/ospab/ospab.host
• GitHub: https://github.com/ospab/ospabhost8.1

---

🙏 Acknowledgments

• MinIO - S3-compatible object storage
• Prisma - Next-generation ORM
• React - UI library
• Tailwind CSS - CSS framework
• Quill - Rich text editor
• Passport.js - Authentication middleware

---

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