From d5530cc8076350bb2d25142824b244fbfdc5ef3a Mon Sep 17 00:00:00 2001 From: Billy Chan Date: Tue, 7 Jan 2025 17:56:34 +0800 Subject: [PATCH] [sea-orm-pro] edit --- sea-orm-pro/docs/01-index.md | 8 +- .../docs/01-introduction/01-sea-orm-pro.md | 2 +- .../docs/02-install-and-config/01-database.md | 60 -------- ...-started.md => 01-getting-started-loco.md} | 141 +++++++++--------- .../docs/02-install-and-config/02-frontend.md | 29 ---- .../02-getting-started-axum.md | 2 + sea-orm-pro/docs/03-site-config/01-theme.md | 8 +- .../docs/04-raw-table-config/01-basics.md | 2 +- .../docs/04-raw-table-config/02-table.md | 2 +- sea-orm-pro/docs/06-deployment/01-nginx.md | 2 +- .../docs/06-deployment/02-user-auth.md | 34 ----- sea-orm-pro/docusaurus.config.js | 4 +- sea-orm-pro/src/pages/index.js | 98 ++++++------ 13 files changed, 128 insertions(+), 264 deletions(-) delete mode 100644 sea-orm-pro/docs/02-install-and-config/01-database.md rename sea-orm-pro/docs/02-install-and-config/{03-getting-started.md => 01-getting-started-loco.md} (92%) delete mode 100644 sea-orm-pro/docs/02-install-and-config/02-frontend.md create mode 100644 sea-orm-pro/docs/02-install-and-config/02-getting-started-axum.md delete mode 100644 sea-orm-pro/docs/06-deployment/02-user-auth.md diff --git a/sea-orm-pro/docs/01-index.md b/sea-orm-pro/docs/01-index.md index 9657f4438a..6dfc24f8e3 100644 --- a/sea-orm-pro/docs/01-index.md +++ b/sea-orm-pro/docs/01-index.md @@ -12,11 +12,9 @@ 2. Installation & Configuration - 2.1 [Database & Async Runtime](02-install-and-config/01-database.md) + 2.1 [Getting Started with Loco](02-install-and-config/01-getting-started-loco.md) - 2.2 [Admin Dashboard Frontend](02-install-and-config/02-frontend.md) - - 2.3 [Getting Started](02-install-and-config/03-getting-started.md) + 2.2 [Getting Started with Axum](02-install-and-config/02-getting-started-axum.md) 3. Site Config @@ -47,5 +45,3 @@ 6. Deployment 6.1 [Nginx](06-deployment/01-nginx.md) - - 6.2 [User Authentication](06-deployment/02-user-auth.md) diff --git a/sea-orm-pro/docs/01-introduction/01-sea-orm-pro.md b/sea-orm-pro/docs/01-introduction/01-sea-orm-pro.md index 1dec690e7b..df27eb789b 100644 --- a/sea-orm-pro/docs/01-introduction/01-sea-orm-pro.md +++ b/sea-orm-pro/docs/01-introduction/01-sea-orm-pro.md @@ -1,6 +1,6 @@ # What is SeaORM Pro -SeaORM Pro is an admin dashboard that provides full CRUD interface for your SeaORM entities, includes a GraphQL interface to handles CRUD request. +SeaORM Pro is an admin panel that provides full CRUD interface for your SeaORM entities, includes a GraphQL interface to handles CRUD request. The source code of the frontend and backend are fully customizable and accessible. The tech stack includes a sleek Ant Design React frontend admin panel, Loco.rs Rust backend server, SeaORM object relational mapper to interact with your relational database and Seaography to extends entity that defines in SeaORM to serve as a GraphQL interface. diff --git a/sea-orm-pro/docs/02-install-and-config/01-database.md b/sea-orm-pro/docs/02-install-and-config/01-database.md deleted file mode 100644 index 8ed54303bf..0000000000 --- a/sea-orm-pro/docs/02-install-and-config/01-database.md +++ /dev/null @@ -1,60 +0,0 @@ -# Database & Async Runtime - -First, go to `Cargo.toml` and find the line of `sea-orm` in the `[dependencies]` section. - -```toml title="Cargo.toml" -sea-orm = { version = "1.1.0", features = [ , , "macros" ] } -``` - -You must choose a `DATABASE_DRIVER` and an `ASYNC_RUNTIME`. `macros` is needed if you use SeaORM's generated entities (most likely). - -## DATABASE_DRIVER - -You can choose one or more from: - -+ `sqlz-mssql` - SQLz MSSQL -+ `sqlx-mysql` - SQLx MySQL and MariaDB -+ `sqlx-postgres` - SQLx PostgreSQL -+ `sqlx-sqlite` - SQLx SQLite - -See also: [SQLx docs](https://docs.rs/crate/sqlx/latest/features). - -:::tip SQL Server (MSSQL) backend - -The installation and configuration of MSSQL driver can be found [here](https://www.sea-ql.org/SeaORM-X/docs/install-and-config/database-and-async-runtime/). - -::: - -## ASYNC_RUNTIME - -You have to choose one from: - -`runtime-async-std-native-tls`, `runtime-tokio-native-tls`, `runtime-async-std-rustls`, `runtime-tokio-rustls` - -Basically, they are in the form of `runtime-ASYNC_RUNTIME-TLS_LIB`: - -+ `ASYNC_RUNTIME` can be [`async-std`](https://crates.io/crates/async-std) or [`tokio`](https://crates.io/crates/tokio) -+ `TLS_LIB` can either be [`native-tls`](https://crates.io/crates/native-tls) or [`rustls`](https://crates.io/crates/rustls) - -1. Choose the ASYNC_RUNTIME corresponding to your Rust web framework: - -| ASYNC_RUNTIME | Web Framework | -| :-----------: | :------------: | -| `async-std` | [`Tide`](https://docs.rs/tide) | -| `tokio` | [`Axum`](https://docs.rs/axum), [`Actix`](https://actix.rs/), [`Poem`](https://docs.rs/poem), [`Rocket`](https://rocket.rs/) | - -2. `native-tls` uses the platform's native security facilities, while `rustls` is an (almost) pure Rust implementation. - -## Extra features - -+ `debug-print` - print every SQL statement to logger -+ `mock` - mock interface for unit testing -+ `macros` - procedural macros for your convenient -+ `with-chrono` - support [`chrono`](https://crates.io/crates/chrono) types -+ `with-time` - support [`time`](https://crates.io/crates/time) types -+ `with-json` - support [`serde-json`](https://crates.io/crates/serde-json) types -+ `with-rust_decimal` - support [`rust_decimal`](https://crates.io/crates/rust_decimal) types -+ `with-bigdecimal` - support [`bigdecimal`](https://crates.io/crates/bigdecimal) types -+ `with-uuid` - support [`uuid`](https://crates.io/crates/uuid) types -+ `postgres-array` - support array types in Postgres (automatically enabled when `sqlx-postgres` feature is turned on) -+ `sea-orm-internal` - opt-in unstable internal APIs (for accessing re-export SQLx types) diff --git a/sea-orm-pro/docs/02-install-and-config/03-getting-started.md b/sea-orm-pro/docs/02-install-and-config/01-getting-started-loco.md similarity index 92% rename from sea-orm-pro/docs/02-install-and-config/03-getting-started.md rename to sea-orm-pro/docs/02-install-and-config/01-getting-started-loco.md index 5fefe73f28..7b79d81f44 100644 --- a/sea-orm-pro/docs/02-install-and-config/03-getting-started.md +++ b/sea-orm-pro/docs/02-install-and-config/01-getting-started-loco.md @@ -1,12 +1,12 @@ -# Getting Started - -## Start with Loco Starter Example +# Getting Started with Loco We use the [`loco_starter`](https://github.com/SeaQL/sea-orm/tree/master/examples/loco_starter) example as the base, it contains basic REST API to handle basic user management such as user registration, login and user info of current session. -We will extends the SeaORM entities in the example to define a GraphQL schema, handle GraphQL request and serve SeaORM Pro admin dashboard. +## 1. Setup Admin Endpoint + +We will extends the SeaORM entities in the example to define a GraphQL schema, handle GraphQL request and serve SeaORM Pro admin panel. -## Download Admin Dashboard Frontend +### 1.1 Download frontend assets ```sh # Go to the root of `loco_starter` example @@ -15,13 +15,13 @@ cd sea-orm/examples/loco_starter # Create a directory for the static assets mkdir assets -# Use the `download_frontend.sh` to download SeaORM Pro FREE admin dashboard to `assets/admin` directory +# Use the `download_frontend.sh` to download SeaORM Pro FREE admin panel to `assets/admin` directory curl "https://raw.githubusercontent.com/SeaQL/sea-orm-pro/refs/heads/main/build_tools/download_frontend.sh" -sSf | sh ``` -## Serve Frontend via Static Middleware +### 1.2 Serve frontend via `static` middleware -Open Loco.rs config file, add `static` middlewares. The admin dashboard frontend is located in `/assets/admin` and we want to serve it under `http://localhost:3000/admin`, so we set the path as `assets`. Also, the admin dashboard frontend is a single page application, so we set a fallback route to the index file, `./assets/admin/index.html`. +Open Loco.rs config file, add `static` middlewares. The admin panel frontend is located in `/assets/admin` and we want to serve it under `http://localhost:3000/admin`, so we set the path as `assets`. Also, the admin panel frontend is a single page application, so we set a fallback route to the index file, `./assets/admin/index.html`. ```diff title=loco_starter/config/development.yaml server: @@ -36,7 +36,62 @@ server: + fallback: ./assets/admin/index.html ``` -## Define GraphQL Schema +### 1.3 Setup admin API endpoint + +The admin panel frontend is customizable and it read the configuration from the `api/admin/config` endpoint. + +```rust title=loco_starter/src/controllers/admin.rs +use loco_rs::prelude::*; + +pub async fn config(State(_ctx): State) -> Result { + format::json(serde_json::json!({ + "site": { + "theme": { + "title": "SeaORM Pro FREE", + "logo": "/admin/favicon.ico", + "login_banner": "/admin/logo.png", + } + }, + "raw_tables": {}, + "composite_tables": {}, + })) +} + +pub fn routes() -> Routes { + Routes::new().prefix("admin").add("/config", get(config)) +} +``` + +Use the admin controller and register the `/api/admin` route. + +```diff title=loco_starter/src/controllers/mod.rs ++ pub mod admin; +pub mod auth; +pub mod files; +pub mod notes; +pub mod user; +``` + +```diff title=loco_starter/src/app.rs +pub struct App; + +#[async_trait] +impl Hooks for App { + fn routes(_ctx: &AppContext) -> AppRoutes { + AppRoutes::with_default_routes() + .prefix("/api") + .add_route(controllers::notes::routes()) + .add_route(controllers::auth::routes()) + .add_route(controllers::user::routes()) + .add_route(controllers::files::routes()) ++ .add_route(controllers::admin::routes()) + } +} +``` + +## 2. Setup GraphQL Endpoint + +### 2.1 Define GraphQL schema Add the dependencies for defining GraphQL schema: `async-graphql`, `seaography` and `lazy_static`. @@ -214,7 +269,7 @@ pub mod workers; + pub mod graphql; ``` -## Setup GraphQL Endpoint +### 2.2 Setup GraphQL playground and query root Add dependencies for serving GraphQL playground and handling GraphQL request. @@ -276,68 +331,12 @@ pub fn routes() -> Routes { Use the GraphQL controller and register the `/api/graphql` route. ```diff title=loco_starter/src/controllers/mod.rs +pub mod admin; pub mod auth; pub mod files; -pub mod notes; -pub mod user; + pub mod graphql; -``` - -```diff title=loco_starter/src/app.rs -pub struct App; - -#[async_trait] -impl Hooks for App { - fn routes(_ctx: &AppContext) -> AppRoutes { - AppRoutes::with_default_routes() - .prefix("/api") - .add_route(controllers::notes::routes()) - .add_route(controllers::auth::routes()) - .add_route(controllers::user::routes()) - .add_route(controllers::files::routes()) -+ .add_route(controllers::graphql::routes()) - } -} -``` - -## Setup Library Endpoint - -The admin dashboard frontend is customizable and it read the configuration from the `api/library/config` endpoint. - -```rust title=loco_starter/src/controllers/library.rs -use loco_rs::prelude::*; - -pub async fn config(State(_ctx): State) -> Result { - format::json(serde_json::json!({ - "site": { - "theme": { - "title": "SeaORM Pro FREE", - "logo": "/admin/favicon.ico", - "login_banner": "/admin/logo.png", - "copyright": "Powered by SeaORM Pro", - } - }, - "raw_tables": {}, - "composite_tables": {}, - })) -} - -pub fn routes() -> Routes { - Routes::new() - .prefix("library") - .add("/config", get(config)) -} -``` - -Use the library controller and register the `/api/library` route. - -```diff title=loco_starter/src/controllers/mod.rs -pub mod auth; -pub mod files; pub mod notes; pub mod user; -pub mod graphql; -+ pub mod library; ``` ```diff title=loco_starter/src/app.rs @@ -352,13 +351,13 @@ impl Hooks for App { .add_route(controllers::auth::routes()) .add_route(controllers::user::routes()) .add_route(controllers::files::routes()) - .add_route(controllers::graphql::routes()) -+ .add_route(controllers::library::routes()) + .add_route(controllers::admin::routes()) ++ .add_route(controllers::graphql::routes()) } } ``` -## Compile and Run +## 3. Launch! ```sh $ cargo run start @@ -386,7 +385,7 @@ $ cargo run start 2025-01-03T08:48:32.471041Z INFO app: loco_rs::controller::app_routes: [POST] /api/files/upload/:notes_id environment=development 2025-01-03T08:48:32.471090Z INFO app: loco_rs::controller::app_routes: [GET] /api/files/list/:notes_id environment=development 2025-01-03T08:48:32.471144Z INFO app: loco_rs::controller::app_routes: [GET] /api/files/view/:files_id environment=development -2025-01-03T08:48:32.471195Z INFO app: loco_rs::controller::app_routes: [GET] /api/library/config environment=development +2025-01-03T08:48:32.471195Z INFO app: loco_rs::controller::app_routes: [GET] /api/admin/config environment=development 2025-01-03T08:48:32.471239Z INFO app: loco_rs::controller::app_routes: [GET] /api/graphql environment=development 2025-01-03T08:48:32.471319Z INFO app: loco_rs::controller::app_routes: [POST] /api/graphql environment=development 2025-01-03T08:48:32.472125Z INFO app: loco_rs::controller::app_routes: [Middleware] Adding static environment=development diff --git a/sea-orm-pro/docs/02-install-and-config/02-frontend.md b/sea-orm-pro/docs/02-install-and-config/02-frontend.md deleted file mode 100644 index 113d29da0d..0000000000 --- a/sea-orm-pro/docs/02-install-and-config/02-frontend.md +++ /dev/null @@ -1,29 +0,0 @@ -# Admin Dashboard Frontend - -## SeaORM Pro - -```sh -cd sea-orm-pro - -# Install dependency -npm install - -# Run frontend in development mode -# Visit admin at `http://localhost:8085/` -npm run dev - -# Build frontend artifact -npm run build - -# Copy frontend artifact to backend and serve statically -... -``` - -## SeaORM Pro Free - -```sh -cd sea-orm-pro-free - -# Download frontend artifact -sh build_tools/download_frontend.sh -``` diff --git a/sea-orm-pro/docs/02-install-and-config/02-getting-started-axum.md b/sea-orm-pro/docs/02-install-and-config/02-getting-started-axum.md new file mode 100644 index 0000000000..cc5bda993d --- /dev/null +++ b/sea-orm-pro/docs/02-install-and-config/02-getting-started-axum.md @@ -0,0 +1,2 @@ +# Getting Started with Axum + diff --git a/sea-orm-pro/docs/03-site-config/01-theme.md b/sea-orm-pro/docs/03-site-config/01-theme.md index e76d4a0efb..65a2dbaa23 100644 --- a/sea-orm-pro/docs/03-site-config/01-theme.md +++ b/sea-orm-pro/docs/03-site-config/01-theme.md @@ -5,15 +5,15 @@ ```toml [site.theme] -# Title of admin dashboard +# Title of admin panel title = "SeaORM Pro FREE" -# File path of admin dashboard logo +# File path of admin panel logo logo = "/admin/favicon.ico" -# File path of admin dashboard login banner +# File path of admin panel login banner login_banner = "/admin/logo.png" -# Copyright of admin dashboard +# Copyright of admin panel copyright = "Powered by SeaORM Pro" ``` diff --git a/sea-orm-pro/docs/04-raw-table-config/01-basics.md b/sea-orm-pro/docs/04-raw-table-config/01-basics.md index 26a6dc810e..a0e12b4d9c 100644 --- a/sea-orm-pro/docs/04-raw-table-config/01-basics.md +++ b/sea-orm-pro/docs/04-raw-table-config/01-basics.md @@ -10,7 +10,7 @@ The TOML config file should be named the same as the corresponding name of the d ## Overall Structure of TOML File -The TOML config file of raw table is not compulsory. All database tables and all its columns will be shown on the admin dashboard by default. However, if you wish to customize the display of raw table, a TOML config file is required. +The TOML config file of raw table is not compulsory. All database tables and all its columns will be shown on the admin panel by default. However, if you wish to customize the display of raw table, a TOML config file is required. The TOML config consists of 5 sections, each section will be explained separately in the following. diff --git a/sea-orm-pro/docs/04-raw-table-config/02-table.md b/sea-orm-pro/docs/04-raw-table-config/02-table.md index 79731a3621..77ba19e7bf 100644 --- a/sea-orm-pro/docs/04-raw-table-config/02-table.md +++ b/sea-orm-pro/docs/04-raw-table-config/02-table.md @@ -23,7 +23,7 @@ page_size = 20 By default, the `all_columns` is turned on, meaning all columns will be shown, you can override this in the config. -The sequence of item in which the `columns` array is the same as the table displayed in the admin dashboard. +The sequence of item in which the `columns` array is the same as the table displayed in the admin panel. The `title` is optional, if it's not set it will use the title case of the `field` as the title. diff --git a/sea-orm-pro/docs/06-deployment/01-nginx.md b/sea-orm-pro/docs/06-deployment/01-nginx.md index b3a8e779a0..79a26316ed 100644 --- a/sea-orm-pro/docs/06-deployment/01-nginx.md +++ b/sea-orm-pro/docs/06-deployment/01-nginx.md @@ -1,6 +1,6 @@ # Nginx -You can serve the admin dashboard through Nginx. +You can serve the admin panel through Nginx. First build the frontend artifact. diff --git a/sea-orm-pro/docs/06-deployment/02-user-auth.md b/sea-orm-pro/docs/06-deployment/02-user-auth.md deleted file mode 100644 index c2835fc7fb..0000000000 --- a/sea-orm-pro/docs/06-deployment/02-user-auth.md +++ /dev/null @@ -1,34 +0,0 @@ -# User Authentication - -You can override the login procedure in `src/controllers/auth.rs`. - -```rust -// Login with email and password -async fn login( - State(ctx): State, - Json(params): Json, -) -> Result { - // Database connection - let db = ctx.db; - - // Find user by email - let user = users::Model::find_by_email(db, ¶ms.email).await?; - - // Validate password - let algo = otpshka::Algorithm::SHA256; - let secret = "fxq9rHswDLfFVkdC69FeJPXStVMjwUjP".as_bytes(); - let totp = otpshka::TOTP::new(algo, secret); - let valid = totp.verify_now(¶ms.password); - if !valid { - return unauthorized("unauthorized!"); - } - - // Generate JWT - let jwt_secret = ctx.config.get_jwt_config()?; - let token = user - .generate_jwt(&jwt_secret.secret, &jwt_secret.expiration) - .or_else(|_| unauthorized("unauthorized!"))?; - - format::json(LoginResponse::new(&user, &token)) -} -``` diff --git a/sea-orm-pro/docusaurus.config.js b/sea-orm-pro/docusaurus.config.js index 314257d139..e23a36b6f6 100644 --- a/sea-orm-pro/docusaurus.config.js +++ b/sea-orm-pro/docusaurus.config.js @@ -1,8 +1,8 @@ const tailwindPlugin = require('./plugins/tailwind-config.cjs'); module.exports = { - title: 'SeaORM Pro 🐚 An admin dashboard built on top of SeaORM & Seaography', - tagline: '🐚 SeaORM Pro is an admin dashboard built on top of SeaORM & Seaography', + title: 'SeaORM Pro 🐚 An admin panel built on top of SeaORM & Seaography', + tagline: '🐚 SeaORM Pro is an admin panel built on top of SeaORM & Seaography', url: 'https://www.sea-ql.org', baseUrl: '/sea-orm-pro/', onBrokenLinks: 'throw', diff --git a/sea-orm-pro/src/pages/index.js b/sea-orm-pro/src/pages/index.js index c5ff781b7b..d08a92b4bf 100644 --- a/sea-orm-pro/src/pages/index.js +++ b/sea-orm-pro/src/pages/index.js @@ -17,18 +17,18 @@ function HomepageHeader() {
-

- Harness your data. +

+ Effortless Admin Panel

- Build production-ready admin panels effortlessly with SeaORM Pro. + Build professional admin panels with SeaORM Pro.

- + Getting Started - - Read the docs + + Try the Demo
@@ -59,19 +59,13 @@ function HomepageSlogan() {

- Launch complete Admin Dashboard in minutes. + Launch Admin Panel in minutes.

- Professional, sleek user interface by Ant Design. + Use SeaORM Pro with any Rust web framework, simply follow the 3 easy steps to setup an admin panel for existing SeaORM projects.

- Gone are the days to build GraphQL resolvers by hand! -

-

- Customize the UI easily with a simple, elegant toml syntax. -

-

- Absolutely no generated code bloat. + Or even better, build your next application with our fullstack webapp template!

@@ -104,7 +98,7 @@ function HomepageFeatures() { Out-of-the-box features

- SeaORM Pro simplifies the process of crafting a resilient backend admin panel. + SeaORM Pro takes the hassle out of crafting beautiful backend admin panels.

@@ -115,7 +109,7 @@ function HomepageFeatures() {

- CRUD - Covered + Full CRUD

SeaORM Pro provides a full CRUD interface for your SeaORM models. @@ -135,12 +129,10 @@ function HomepageFeatures() {

- Build on industry standard -
- React + GraphQL + Built on industry standard React + GraphQL

- Professional, sleek user interface by Ant Design. + Build professional, sleek user interface with Ant Design Pro, a feature-rich React component library + framework for building enterprise applications. Use SeaORM Pro as the foundation to bring your vision to life!

@@ -157,10 +149,10 @@ function HomepageFeatures() {

- GraphQL resolver? built-in + GraphQL resolver? Built-in

- Gone are the days to build GraphQL resolvers by hand! + Gone are the days of building GraphQL resolvers by hand! With Seaography, your SeaORM schema is automagically transformed into a fully-functional GraphQL schema, enabling you to write, sort, filter, and join GraphQL queries on the frontend.

@@ -170,6 +162,26 @@ function HomepageFeatures() {
+
+
+
+
+ +
+

+ Dark Mode? Sure! +

+

+ Customize the UI theme easily with light / dark mode support. +

+
+
+
+ + +
+
+
@@ -192,41 +204,19 @@ function HomepageFeatures() {
-
-
-
-
- -
-

- Nested table for relational entities -

-

- Parent-child relations, e.g. Order-OrderItem, presented in a single table. - Every type of SeaORM relationship is fully supported. - Need to visualize the data on your polymorphic many-to-many relationship? - We have you covered. -

-
-
-
- - -
-
-

- It's a big universe... + Start Building Today

-

- SeaORM Pro has much more to offer. To get the full scoop, head over to the documentation to learn about all - the cosmic possibilities. -

- - Read documentation - +
+ + Getting Started + + + Try the Demo + +