135 lines
3.6 KiB
Markdown
135 lines
3.6 KiB
Markdown
# MadBase
|
|
|
|
**MadBase** is an open-source, high-performance Backend-as-a-Service (BaaS) written in Rust. It serves as a lightweight alternative to Supabase, providing a comprehensive suite of tools for building modern web and mobile applications.
|
|
|
|
## 🚀 Features
|
|
|
|
MadBase consolidates the following services into a single, efficient binary:
|
|
|
|
* **🔐 Authentication (`/auth/v1`)**
|
|
* User Signup & Login (Email/Password).
|
|
* JWT-based Session Management.
|
|
* Row Level Security (RLS) integration with PostgreSQL.
|
|
* **💾 Data API (`/rest/v1`)**
|
|
* Auto-generated REST API for your Postgres tables.
|
|
* CRUD operations (Select, Insert, Update, Delete).
|
|
* Filtering, Pagination, and Ordering.
|
|
* Stored Procedure (RPC) calls.
|
|
* **⚡ Realtime (`/realtime/v1`)**
|
|
* WebSocket-based event streaming.
|
|
* Listen to database changes via Postgres `LISTEN/NOTIFY`.
|
|
* **📦 Storage (`/storage/v1`)**
|
|
* S3-compatible object storage (backed by MinIO).
|
|
* File Upload, Download, and Management.
|
|
* Integrated RLS permissions for buckets and objects.
|
|
* **🎛️ Control Plane (`/platform/v1`)**
|
|
* Project Management.
|
|
* Automatic API Key Generation (`anon` and `service_role`).
|
|
|
|
## 🛠️ Architecture
|
|
|
|
MadBase is built as a modular monolith in **Rust**, utilizing the **Axum** web framework for high performance and low latency.
|
|
|
|
* **Gateway**: The central entry point that routes requests to appropriate internal modules.
|
|
* **PostgreSQL**: The primary database for data, auth, and system state.
|
|
* **MinIO**: S3-compatible object storage.
|
|
|
|
## 🏁 Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
* **Rust** (latest stable)
|
|
* **Docker** & **Docker Compose** (for DB and MinIO)
|
|
* **PostgreSQL Client** (optional, for debugging)
|
|
|
|
### Installation
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone https://github.com/yourusername/madbase.git
|
|
cd madbase
|
|
```
|
|
|
|
2. **Start Infrastructure:**
|
|
Spin up PostgreSQL and MinIO using Docker Compose:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
3. **Run Migrations:**
|
|
Initialize the database schema:
|
|
```bash
|
|
sqlx migrate run
|
|
```
|
|
*(Note: You may need to install sqlx-cli: `cargo install sqlx-cli`)*
|
|
|
|
4. **Start the Gateway:**
|
|
Run the main server:
|
|
```bash
|
|
cargo run -p gateway
|
|
```
|
|
The server will start at `http://0.0.0.0:8000`.
|
|
|
|
## 📖 Usage Guide
|
|
|
|
### 1. Create a Project
|
|
Use the Control Plane to initialize a project and get your API keys.
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/platform/v1/projects \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name": "my-awesome-app"}'
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "...",
|
|
"anon_key": "eyJ...",
|
|
"service_role_key": "eyJ...",
|
|
...
|
|
}
|
|
```
|
|
*Save the `anon_key` and `service_role_key`!*
|
|
|
|
### 2. Authentication
|
|
Sign up a new user:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/auth/v1/signup \
|
|
-H "apikey: <ANON_KEY>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"email": "user@example.com", "password": "securepassword"}'
|
|
```
|
|
|
|
### 3. Data Operations
|
|
Query a table (e.g., `users`):
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:8000/rest/v1/users?select=*" \
|
|
-H "apikey: <ANON_KEY>" \
|
|
-H "Authorization: Bearer <USER_ACCESS_TOKEN>"
|
|
```
|
|
|
|
### 4. Realtime
|
|
Connect via WebSocket:
|
|
`ws://localhost:8000/realtime/v1`
|
|
|
|
### 5. Storage
|
|
Upload a file:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/storage/v1/object/my-bucket/image.png \
|
|
-H "apikey: <ANON_KEY>" \
|
|
-H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
|
|
-F "file=@./local-image.png"
|
|
```
|
|
|
|
## 🗺️ Roadmap
|
|
|
|
See [ROADMAP.md](./ROADMAP.md) for detailed progress and future plans.
|
|
|
|
## 📄 License
|
|
|
|
MIT
|