From 694b981bfd94fdf34d8aa60037a82a3e69afe08e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 16:37:02 +0000 Subject: [PATCH 1/5] Initial plan From 0845a228eafb6b1131fcd562c86761c0aa3d27a8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 16:41:48 +0000 Subject: [PATCH 2/5] docs: rewrite overview.mdx to be more engaging and user-friendly Co-authored-by: hsluoyz <3787410+hsluoyz@users.noreply.github.com> --- docs/overview.mdx | 185 +++++++++++++++++++++++++++++----------------- 1 file changed, 119 insertions(+), 66 deletions(-) diff --git a/docs/overview.mdx b/docs/overview.mdx index a6fb193dd..d5464609f 100644 --- a/docs/overview.mdx +++ b/docs/overview.mdx @@ -10,7 +10,9 @@ import styles from './styles.module.css'; import CasdoorCard from "@site/src/components/CasdoorCard"; ``` -Casdoor is a UI-first [Identity Access Management (IAM)](https://en.wikipedia.org/wiki/Identity_management) / [Single-Sign-On (SSO)](https://en.wikipedia.org/wiki/Single_sign-on) platform with a web UI that supports OAuth 2.0, OIDC, SAML, CAS, LDAP, SCIM, WebAuthn, TOTP, MFA, RADIUS, Google Workspace, Active Directory, and Kerberos. +## What is Casdoor? + +Casdoor is a modern, UI-first [Identity Access Management (IAM)](https://en.wikipedia.org/wiki/Identity_management) and [Single-Sign-On (SSO)](https://en.wikipedia.org/wiki/Single_sign-on) platform that makes authentication and user management simple and secure. Whether you're building a small app or managing enterprise-scale authentication, Casdoor provides everything you need in one elegant package. ```mdx-code-block
@@ -18,132 +20,183 @@ Casdoor is a UI-first [Identity Access Management (IAM)](https://en.wikipedia.or
``` -Casdoor serves both the web UI and the login requests from application users. +With support for OAuth 2.0, OIDC, SAML, LDAP, and many more protocols, Casdoor seamlessly integrates with your existing infrastructure while providing a beautiful web interface for managing users, applications, and authentication flows. -## Casdoor features +## Why Choose Casdoor? -1. Casdoor follows a frontend-backend separation architecture and is developed in Golang. It supports high concurrency, provides a web-based UI for management, and supports localization in over 10 languages. +### ๐ŸŒ Built for Global Teams -2. Casdoor supports third-party application login options, such as GitHub, Google, QQ, and WeChat, and supports extending third-party login capabilities with plugins. +Available in 10+ languages with internationalization support out of the box, Casdoor ensures your users feel at home no matter where they are. The intuitive web-based UI makes managing authentication a breeze for administrators and developers alike. -3. Casdoor supports authorization management based on [Casbin](https://casbin.org/). It supports ACL, RBAC, ABAC, and RESTful access control models. +### ๐Ÿ” Comprehensive Authentication -4. Casdoor provides phone verification codes, email verification codes, and password retrieval functionality. +**Social Login Made Easy**: Let your users sign in with their favorite platforms - GitHub, Google, Facebook, WeChat, and 50+ other providers. Extend with custom OAuth providers whenever you need. -5. Casdoor supports auditing and recording of access logs. +**Enterprise-Ready Security**: Support for advanced authentication including WebAuthn, TOTP, multi-factor authentication (MFA), and RADIUS ensures your organization meets the highest security standards. -6. Casdoor integrates with Alibaba Cloud, Tencent Cloud, and Qiniu Cloud for image CDN and cloud storage. +**Multiple Protocols**: Whether your infrastructure uses OAuth 2.0, OIDC, SAML, CAS, LDAP, or SCIM, Casdoor speaks your language. Integrate with Google Workspace, Active Directory, and Kerberos without breaking a sweat. -7. Casdoor allows customization of registration, login, and password retrieval pages. +### ๐Ÿ›ก๏ธ Powerful Authorization -8. Casdoor supports integration with existing systems through database synchronization, enabling a smooth transition to Casdoor. +Built on [Casbin](https://casbin.org/), Casdoor delivers flexible authorization management supporting ACL, RBAC, ABAC, and RESTful access control models. Define who can do what with precision and clarity. -9. Casdoor supports mainstream databases such as MySQL, PostgreSQL, and SQL Server, and supports extending to new databases with plugins. +### ๐ŸŽจ Fully Customizable -## How it works +Make it yours! Customize registration, login, and password recovery pages to match your brand. From colors to logos, create a seamless authentication experience that feels native to your application. -![Principle](/img/principles.gif) +### ๐Ÿ“Š Complete Audit Trail -### Step 0 (Pre-knowledge) +Track every authentication event with comprehensive access logs. Know who logged in, when, and from where - essential for compliance and security monitoring. -1. Casdoor follows the authorization process built upon the OAuth 2.0 protocol. We highly recommend gaining a brief understanding of how OAuth 2.0 works. You can refer to this [introduction](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2) to OAuth 2.0. +### ๐Ÿ”„ Seamless Migration -![image](/img/oauth.png) +Already have users in an existing system? No problem! Casdoor integrates through database synchronization, allowing you to migrate smoothly without disrupting your users. -### Step 1 (Authorization Request) +### ๐Ÿš€ Production-Ready Performance -Your Application (which could be a website or any other application) should compose a URL in the following format: `endpoint/login/oauth/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&scope=read&state=xxx`. Replace `endpoint` with your Casdoor host URL and `xxx` with your own information. +Built in Golang with a modern frontend-backend architecture, Casdoor handles high concurrency effortlessly. Deploy with confidence using mainstream databases like MySQL, PostgreSQL, or SQL Server, with plugin support for custom data stores. -:::note Hints +### โ˜๏ธ Cloud Native -How to fill out the `xxx` parts? +Integrate with leading cloud providers including Alibaba Cloud, Tencent Cloud, and Qiniu Cloud for CDN and storage. Casdoor fits perfectly into your cloud infrastructure. -+ For `client_id`: you can find this under each individual Application. +## How Casdoor Works -+ For `redirect_uri`: you should set this to your own Application's callback URL. Casdoor will use this information to send the response back after authorization. +![Authentication Flow](/img/principles.gif) -+ For `state`: you should fill this out with your Application name. +Understanding how Casdoor works is easier than you might think! At its core, Casdoor implements the OAuth 2.0 authorization flow, which might sound complex but is actually quite intuitive. Let's walk through it step by step. -::: +### Before We Begin + +Casdoor uses the OAuth 2.0 protocol for authorization. If you're new to OAuth, don't worry - we'll explain everything you need to know. For a deeper dive, check out this excellent [introduction to OAuth 2.0](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2). -The Application will prompt the user: *"Hey, I need some resources and I need your permission to access these resources. Can you go to this URL and enter your username and password for me?"* +![OAuth 2.0 Overview](/img/oauth.png) -With the correctly composed URL, your Application will make the user launch a request to this URL, and the `Authorization Request` is completed. +### The Authentication Dance: A Step-by-Step Story -### Step 2 (Authorization Grant) +Think of OAuth as a conversation between three parties: your application, Casdoor (the authentication server), and your user. Here's how they work together: -This step is straightforward: the user is redirected to the URL composed in Step 1, and the user will see the login page from Casdoor. By entering the correct username and credentials into the login page, Casdoor now knows the identity of the user and is about to send two pieces of information back to the callback URL set in Step 1: `code` and `state`. +#### Step 1: Your App Asks for Permission -The user opens the URL and provides credentials to Casdoor. Casdoor will say: "Looking good ~ this is the user (who is authorizing the Application to receive the `code` and `state`) I know in my database, and I will send the `code` and `state` back to the Application using the callback URL (`redirect_uri`)". +Your application needs to access user resources, so it creates a special URL that looks like this: -With these two pieces of information sent back to your Application, the authorization is granted to the app, and the `Authorization Grant` is completed. +```url +https://your-casdoor-url.com/login/oauth/authorize? + client_id=YOUR_CLIENT_ID + &response_type=code + &redirect_uri=https://yourapp.com/callback + &scope=read + &state=YOUR_APP_NAME +``` + +:::note Quick Reference -:::tip +**Where do I find these values?** -Casdoor also provides third-party logins. In this case, instead of seeing the credential entry page, you will see a list of third-party providers. You can log in to your app using these providers, with Casdoor acting as middleware. +- **`client_id`**: Found in your Application settings in Casdoor +- **`redirect_uri`**: Your application's callback URL where users return after logging in +- **`state`**: Your application name (helps prevent CSRF attacks) ::: -### Step 3 (Authorization Grant) +Your app essentially tells the user: *"I need access to some of your information. Please go to this URL and log in so I can get permission."* + +#### Step 2: User Grants Permission -In this step, your Application already has the code from Step 2, and it will speak to Casdoor: *"Hey, the user agreed to give me the `code`. Can you verify this `code` and give me the `access_token`?"* +The user clicks the link and lands on Casdoor's login page. After entering their credentials, Casdoor verifies their identity and sends back two important pieces of information to your app's callback URL: + +- **`code`**: A temporary authorization code +- **`state`**: The application identifier (for security verification) + +Casdoor is saying: *"I recognize this user! Here's a special code proving they gave your app permission. Use it wisely!"* + +:::tip Social Login Option + +Users can also log in using third-party providers like Google or GitHub. Instead of entering credentials, they'll see a list of login options. Casdoor acts as the middleman, making social login integration a breeze. + +::: -### Step 4 (Access Token) +#### Step 3: Exchanging the Code for an Access Token -Casdoor responds to your Application: *"You know what, this `code` seems legit. You must be the authorized Application. Here's the `access_token` for you."* With this `code`, Casdoor confirms that it is an authorized Application (authorized by the correct user in Step 2) trying to obtain the `access_token` (which will be used later to access more resources). +Now your application has the authorization code. It makes a server-to-server request to Casdoor saying: *"Hey, I have this code from a user. Can you verify it and give me an access token?"* -### Step 5 (Access Token) +#### Step 4: Casdoor Issues the Access Token -In this step, your Application says: *"Nice! I just got the fresh `access_token`. Now I can use it to access something more valuable from the `Resource Server`!"* +Casdoor validates the code and responds: *"This code checks out! Here's your access token. Use it to access the user's information."* -Your Application then turns to the `Resource Server` and says: *"Hey buddy, can you check out this `access_token`? I received it from Casdoor. Do you want to verify if this is the correct token you issued to Casdoor?"* +This access token is like a temporary key that proves your app has been authorized to access specific user resources. -### Step 6 (Protected Resource) +#### Step 5: Accessing Protected Resources -The `Resource Server` responds to your Application: *"Not bad. It seems just like the one I issued to Casdoor, and Casdoor says whoever holds this `access_token` can access these `Protected Resources`. So go ahead and take it!"* +With the fresh access token in hand, your application can now request user data from Casdoor's resource server (or any other resource server that trusts Casdoor). -And that's basically how Casdoor works with your Application. +Your app says: *"I have this access token from Casdoor. Can I please access the user's profile information?"* -:::note Hint +#### Step 6: Getting the Data -Casdoor can act as both an `Authorization Server` and a `Resource Server`. In other words, Casdoor authorizes your Application to access resources, usually the currently logged-in user's information, from Casdoor's database. +The resource server validates the token and responds: *"Token verified! Here's the user data you requested."* + +And that's it! Your application now has the user information it needs, and the user has securely authenticated without you having to build complex authentication systems. + +:::note Casdoor's Dual Role + +Casdoor acts as both an **Authorization Server** (handling the login and token issuance) and a **Resource Server** (storing and providing user information). This means you get a complete authentication solution in one package! ::: -## Online demo +## Try Casdoor Now + +### Live Demo + +The best way to understand Casdoor is to try it yourself! We've set up a live demo that you can explore right now: + +**[๐Ÿš€ Launch Casdoor Demo](https://door.casdoor.com/)** -### Casdoor +Want admin access? Use these credentials to explore all features: -Here is an online demo deployed by Casbin. +- **Username**: `admin` +- **Password**: `123` -+ [Casdoor official demo](https://door.casdoor.com/) +Feel free to click around, create test applications, and see how everything works. It's a sandbox environment - you can't break anything! -Global admin login: +### Real-World Examples -+ Username: `admin` -+ Password: `123` +See Casdoor in action with these production applications: -### Casbin-OA +#### Casbin-OA -Casbin-OA is one of the Casbin web apps. It uses Casdoor for authentication. +A complete office automation system using Casdoor for authentication. -+ [Casbin-OA](https://oa.casbin.com) -+ Source code: +- **Live Site**: [oa.casbin.com](https://oa.casbin.com) +- **Source Code**: [github.com/casbin/casbin-oa](https://github.com/casbin/casbin-oa) -### Casnode +#### Casnode -Casnode is the official forum developed by the Casbin community. +The official Casbin community forum, powered by Casdoor for member management. -It uses Casdoor as the authentication platform and manages members. +- **Live Site**: [casnode.org](https://casnode.org) +- **Source Code**: [github.com/casbin/casnode](https://github.com/casbin/casnode) -+ [Casnode](https://casnode.org) -+ Source code: +These aren't just demos - they're real applications serving real users with Casdoor. ## Architecture -Casdoor consists of two parts: +Casdoor is built with a modern, scalable architecture that separates concerns for maximum flexibility: + +| Component | Description | Technology Stack | Source Code | +|-----------|-------------|------------------|-------------| +| **Frontend** | Beautiful, responsive web UI for managing users, apps, and settings | JavaScript + React | [View Code](https://github.com/casdoor/casdoor/tree/master/web) | +| **Backend** | Powerful RESTful API handling authentication, authorization, and data management | Golang + Beego + SQL | [View Code](https://github.com/casdoor/casdoor) | + +This separation means you can scale each component independently, customize the frontend without touching the API, or integrate Casdoor's backend into your own UI. + +## Next Steps + +Ready to get started? Here's your roadmap: + +1. **[Quick Start with Docker](/docs/basic/try-with-docker)** - Get Casdoor running in minutes +2. **[Core Concepts](/docs/basic/core-concepts)** - Understand organizations, users, and applications +3. **[Connect Your App](/docs/how-to-connect/oauth)** - Integrate Casdoor with your application +4. **[Deployment Guide](/docs/deployment/overview)** - Deploy Casdoor to production -Name | Description | Language | Source code -----|------|----|---- -Frontend | Web frontend UI for Casdoor | JavaScript + React | -Backend | RESTful API backend for Casdoor | Golang + Beego + SQL | +Questions? Join our [Discord community](https://discord.gg/5rPsrAzK7S) or check out [GitHub Discussions](https://github.com/casdoor/casdoor/discussions) for help from the community! From 73dea4cd19063a56f0bf2ea24f612c0734c65d98 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 16:45:41 +0000 Subject: [PATCH 3/5] docs: rewrite core-concepts.md with engaging explanations and examples Co-authored-by: hsluoyz <3787410+hsluoyz@users.noreply.github.com> --- docs/basic/core-concepts.md | 283 +++++++++++++++++++++++++++++------- 1 file changed, 233 insertions(+), 50 deletions(-) diff --git a/docs/basic/core-concepts.md b/docs/basic/core-concepts.md index dca25e169..96042bb01 100644 --- a/docs/basic/core-concepts.md +++ b/docs/basic/core-concepts.md @@ -1,11 +1,13 @@ --- title: Core Concepts -description: Learn about the core concepts of Casdoor. +description: Master the fundamental building blocks of Casdoor keywords: [core concepts, organization, user, application, provider] authors: [hsluoyz] --- -As a Casdoor administrator, you should be familiar with at least four core concepts: `Organization`, `User`, `Application`, and `Provider`. +Think of Casdoor as a toolkit for authentication. To use it effectively, you need to understand four core concepts that work together like pieces of a puzzle: **Organizations**, **Users**, **Applications**, and **Providers**. Once you grasp these, everything else clicks into place. + +Let's see how they connect: ```mermaid flowchart LR; @@ -66,15 +68,31 @@ flowchart LR; Applications-2<-->Providers; ``` -:::tip +:::tip Follow Along -In the following parts, we will use the demo site as an example. +We'll use the demo site at throughout this guide. Feel free to explore it as you read! ::: -## Organization +## ๐Ÿข Organization: Your Container for Everything + +An **organization** is like a workspace that groups related users and applications together. Think of it as: + +- **For a company**: All your employees +- **For a SaaS product**: All your customers +- **For a multi-tenant app**: Each tenant gets their own organization + +### Why Organizations Matter -In Casdoor, an organization is a container for users and applications. For example, all the employees of a company or all the customers of a business can be abstracted as one organization. The `Organization` class definition is shown below: +Organizations keep things separate and secure. Users in `company-a` can't accidentally access applications in `company-b`. It's perfect for: + +- **Multi-tenancy**: Each client gets their own isolated space +- **Departmental separation**: HR, Engineering, and Sales can have their own orgs +- **Brand customization**: Each org can have its own look and feel + +### What's Inside an Organization? + +Let's peek under the hood. Here's the data structure (don't worry if you're not a programmer - the table below explains what matters): ```go type Organization struct { @@ -98,22 +116,52 @@ type Organization struct { } ``` -## User +**Key Fields Explained:** + +| Field | What It Does | Example | +|-------|-------------|---------| +| `DisplayName` | The friendly name shown to users | "Acme Corporation" | +| `WebsiteUrl` | Your organization's website | "" | +| `Favicon` | Custom icon for login pages | Your company logo | +| `PasswordType` | How passwords are hashed | bcrypt, argon2, etc. | +| `EnableSoftDeletion` | Deleted users go to trash instead of being permanently removed | Useful for compliance | +| `AccountItems` | Custom fields for user profiles | Employee ID, Department, etc. | -In Casdoor, a user can log into an application. Each user can belong to only one organization but can log into multiple applications owned by the organization. Currently, there are two types of users in Casdoor: +## ๐Ÿ‘ค User: The People in Your System -- `built-in` organization users, such as `built-in/admin`: global administrators who have full administrative power on the Casdoor platform. -- Other organizations' users, such as `my-company/alice`: normal users who can sign up, sign in, sign out, change their own profile, etc. +**Users** are the people who log in. Simple, right? In Casdoor, every user belongs to exactly one organization but can access multiple applications within that org. -In the Casdoor API, a user is typically identified as `/`. For example, the default administrator of Casdoor is denoted as `built-in/admin`. Additionally, the `User` class definition includes an `id` property, which is a UUID like `d835a48f-2e88-4c1f-b907-60ac6b6c1b40` and can be chosen as a user's ID by an application. +### Two Types of Users -:::tip +Casdoor has a special hierarchy: -For applications that are only for one organization, it's possible to use `` instead of `/` as the user ID across the application for simplicity. +1. **๐Ÿ”ง Platform Administrators** (`built-in/admin`) + - Lives in the special `built-in` organization + - Has god-mode access to everything + - Manages Casdoor itself + +2. **๐Ÿ™‹ Regular Users** (`my-company/alice`) + - Belong to your organizations + - Can sign up, sign in, and manage their own profiles + - Access applications based on permissions + +### User Identifiers + +Users are identified by a format: `/`. For example: + +- `built-in/admin` - The default Casdoor administrator +- `acme-corp/john` - John from Acme Corporation +- `startup-inc/sarah` - Sarah from Startup Inc + +Each user also gets a unique UUID (like `d835a48f-2e88-4c1f-b907-60ac6b6c1b40`) which you can use as a stable identifier in your application. + +:::tip Simplify for Single-Org Apps + +If your application only serves one organization, you can use just the username (e.g., `alice`) instead of the full identifier (`my-company/alice`). Much cleaner! ::: -Here's the `User` class definition: +### The User Data Structure ```go type User struct { @@ -182,15 +230,34 @@ type User struct { } ``` -:::tip +**What All These Fields Mean:** + +- **Basic Info**: Name, email, phone, avatar - the usual suspects +- **Profile Details**: Bio, location, birthday, education - make profiles rich +- **Security Tracking**: Login times, IP addresses, forbidden status - know what's happening +- **Social Connections**: GitHub, Google, WeChat, etc. - linked accounts from OAuth providers +- **Admin Flags**: `IsAdmin`, `IsGlobalAdmin` - permission levels at a glance +- **Custom Data**: The `Properties` field - your escape hatch for extra data! -The `Properties` field is a flexible key-value map for storing custom user attributes. See the [User Properties documentation](/docs/user/overview#using-the-properties-field) for detailed usage examples and best practices. +:::tip Custom User Properties + +Need to store custom fields like "Employee ID" or "Department"? Use the `Properties` field - it's a flexible key-value map for any extra data. Check out the [User Properties documentation](/docs/user/overview#using-the-properties-field) for examples. ::: -## Application +## ๐Ÿ“ฑ Application: What Users Access + +An **application** represents any web service or app that needs authentication. This could be: + +- ๐Ÿ—จ๏ธ A forum (like Casnode) +- ๐Ÿ“Š An office automation (OA) system +- ๐Ÿ’ผ A CRM platform +- ๐Ÿ›๏ธ An e-commerce site +- ๐ŸŽฎ A gaming portal + +Each application is essentially a "door" that users walk through to access your service. When users log in, they're logging in through a specific application. -An **application** represents a web service that needs to be protected by Casdoor, such as a forum site, an OA system, or a CRM system. +### Application Structure ```go type Application struct { @@ -226,43 +293,83 @@ type Application struct { } ``` -Each application can have its own customized sign-up page, sign-in page, and more. The root login page `/login` (e.g., ) is the sign-in page only for Casdoor's built-in application: `app-built-in`. +**Key Features of Applications:** + +- **OAuth Credentials**: Each app gets `ClientId` and `ClientSecret` for secure API calls +- **Custom Pages**: You can fully customize signup, signin, and password recovery pages +- **Flexible Auth**: Toggle password login, code-based signin, or social providers +- **Token Control**: Set token expiration times that fit your security requirements + +### Applications are Entry Points + +Think of an application as the front door. Users must enter through an application's login page to access Casdoor. Here are some examples from the demo site: + +| Application | Sign-up Page | Sign-in Page | +|-------------|-------------|--------------| +| **app-built-in** | [door.casdoor.com/signup](https://door.casdoor.com/signup) | [door.casdoor.com/login](https://door.casdoor.com/login) | +| **app-casnode** | [door.casdoor.com/signup/app-casnode](https://door.casdoor.com/signup/app-casnode) | OAuth flow with client_id | +| **app-casbin-oa** | [door.casdoor.com/signup/app-casbin-oa](https://door.casdoor.com/signup/app-casbin-oa) | OAuth flow with client_id | + +### Building Login URLs + +You'll need to construct URLs for signup and signin. Here are three ways to do it: + +#### Option 1: Manual URL Construction + +Build URLs yourself using this pattern: + +**For Sign-up:** + +- Standard signup: `/signup/` +- OAuth signup: `/signup/oauth/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&scope=read&state=casdoor` +- Auto-signup: `/auto-signup/oauth/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&scope=read&state=casdoor` + +**For Sign-in:** -An application is a "portal" or "interface" for a user to log into Casdoor. A user must go through one application's sign-in page to log into Casdoor. +- Organization signin: `/login/` +- OAuth signin: `/login/oauth/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&scope=read&state=casdoor` -| Application | Sign-up page URL | Sign-in page URL | -|---------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| app-built-in | | | -| app-casnode | | | -| app-casbin-oa | | | +#### Option 2: Use Frontend SDK -### Login URLs +For JavaScript/React/Vue/Angular applications, use helper functions: -It's very easy to log into Casdoor via Casdoor's built-in application; simply visit Casdoor server homepage (e.g., for demo site) and it will automatically redirect you to `/login`. But how do you get the URLs for other applications in frontend and backend code? You can either concatenate strings manually or call some utility functions provided by Casdoor SDKs to get the URLs: +```javascript +import { getSignupUrl, getSigninUrl } from 'casdoor-js-sdk'; -#### 1. Manually concatenating strings +const signupUrl = getSignupUrl(); +const signinUrl = getSigninUrl(); +``` + +See the [casdoor-js-sdk documentation](https://github.com/casdoor/casdoor-js-sdk/blob/3d08d726bcd5f62d6444b820596e2d8472f67d97/src/sdk.ts#L50-L63) for details. + +#### Option 3: Use Backend SDK + +For server-side code in Go, Java, Python, etc.: -- Sign-up page URL - - Signup for the specified application: `/signup/` - - Signup by OAuth: `/signup/oauth/authorize?client_id=&response_type=code&redirect_uri=&&scope=read&state=casdoor` - - Signup automatically: `/auto-signup/oauth/authorize?client_id=&response_type=code&redirect_uri=&&scope=read&state=casdoor` -- Sign-in page URL - - Sign-in for the specified organization: `/login/` - - Sign-in by OAuth: `/login/oauth/authorize?client_id=&response_type=code&redirect_uri=&&scope=read&state=casdoor` +```go +import "github.com/casdoor/casdoor-go-sdk/auth" + +signupUrl := auth.GetSignupUrl() +signinUrl := auth.GetSigninUrl() +``` -#### 2. Using frontend SDK (for frontend JavaScript code using React, Vue, or Angular) +See the [casdoor-go-sdk documentation](https://github.com/casdoor/casdoor-go-sdk/blob/f3ef1adff792e9a06af5682e0a3af9436ed24ed3/auth/url.go#L23-L39) for details. -`getSignupUrl()` and `getSigninUrl()`: [casdoor-js-sdk](https://github.com/casdoor/casdoor-js-sdk/blob/3d08d726bcd5f62d6444b820596e2d8472f67d97/src/sdk.ts#L50-L63) +## ๐Ÿ”Œ Provider: Connecting External Services -#### 3. Using backend SDK (for backend code using Go, Java, etc.) +**Providers** are like plugins that connect Casdoor to external services. Need to send verification emails? Use an email provider. Want users to log in with GitHub? Add an OAuth provider. -`GetSignupUrl()` and `GetSigninUrl()`: [casdoor-go-sdk](https://github.com/casdoor/casdoor-go-sdk/blob/f3ef1adff792e9a06af5682e0a3af9436ed24ed3/auth/url.go#L23-L39) +Casdoor supports providers for: -## Provider +- **๐Ÿ” OAuth/OIDC/SAML**: Social login (Google, GitHub, Facebook, etc.) +- **๐Ÿ“ง Email**: SendGrid, Azure ACS, SMTP, and more +- **๐Ÿ“ฑ SMS**: Twilio, Amazon SNS, Alibaba Cloud, etc. +- **โ˜๏ธ Storage**: AWS S3, Azure Blob, Aliyun OSS for file uploads +- **๐Ÿ’ณ Payment**: Stripe, PayPal, Alipay for subscription handling -Casdoor is a federated single sign-on system that supports multiple identity providers via OIDC, OAuth, and SAML. Casdoor can also send verification codes or other notifications to users via email or SMS. Casdoor uses the concept of `Provider` to manage all these third-party connectors. +See the complete list at [Provider Overview](/docs/provider/overview). -A list of all providers supported by Casdoor can be found at **[provider/overview](/docs/provider/overview)**. +### Provider Structure ```go type Provider struct { @@ -303,18 +410,94 @@ type Provider struct { } ``` -## How does Casdoor manage itself? +**Providers are Flexible:** + +The Provider struct has many fields because it needs to support dozens of different services. Depending on the `Category` and `Type`: + +- **OAuth providers** use `ClientId` and `ClientSecret` +- **Email providers** use `Host`, `Port`, and credentials +- **SMS providers** use `AppId`, `SignName`, and `TemplateCode` +- **Storage providers** use `Endpoint`, `Bucket`, and access keys + +Don't be intimidated - you only fill in the fields relevant to your specific provider type! + +## ๐ŸŽฏ How Casdoor Manages Itself + +When you first start Casdoor, it creates some special "built-in" objects to bootstrap itself: + +### The Built-in Organization + +- **Name**: `built-in` +- **Purpose**: Houses Casdoor's administrators +- **Special Power**: All users in this org have god-mode access to the entire platform + +### The Default Admin User + +- **Username**: `built-in/admin` +- **Default Password**: `123` (โš ๏ธ change this immediately!) +- **Access**: Full control over Casdoor -Upon running Casdoor for the first time, some built-in objects are created to facilitate its management: +### The Built-in Application -- A built-in organization named `built-in`. -- A user named `admin` in the `built-in` organization. -- A built-in application named `app-built-in`, administered by the `built-in` organization, representing Casdoor itself. +- **Name**: `app-built-in` +- **Purpose**: Represents Casdoor's own admin interface +- **Access URL**: The root path (e.g., `https://door.casdoor.com`) -All users under the `built-in` organization, including `admin`, will have full administrator privileges on the Casdoor platform. Therefore, if there are multiple administrators, it is advisable to create new accounts under the `built-in` organization. Alternatively, the sign-up channel for the `app-built-in` application should be closed to prevent unwanted access. +### Adding More Administrators -:::caution +Want to add more admins? Simply create new users under the `built-in` organization. Each one will automatically have full administrative privileges. -It is not possible to rename or delete the built-in objects via both the web UI or the RESTful API. Casdoor has hardcoded these reserved names in many places; attempting to rename or delete them by modifying the DB may cause the entire system to crash. +:::caution Don't Delete Built-in Objects! + +The `built-in` organization, admin user, and app-built-in application are hardcoded into Casdoor's core. **Never** try to: + +- Rename them +- Delete them +- Modify them directly in the database + +Doing so will break your entire Casdoor installation. These objects are sacred - treat them with respect! ::: + +## ๐ŸŽ“ Putting It All Together + +Let's recap how everything connects: + +1. **Organizations** contain **Users** and **Applications** +2. **Users** belong to one **Organization** but can access multiple **Applications** +3. **Applications** use **Providers** for authentication methods (social login, email, SMS) +4. **Providers** connect Casdoor to external services + +Here's a real-world scenario: + +```text +Acme Corporation (Organization) +โ”œโ”€โ”€ Users: alice, bob, charlie +โ”œโ”€โ”€ Applications +โ”‚ โ”œโ”€โ”€ Employee Portal (for internal staff) +โ”‚ โ”œโ”€โ”€ Customer Dashboard (for clients) +โ”‚ โ””โ”€โ”€ Admin Panel (for IT team) +โ””โ”€โ”€ Providers + โ”œโ”€โ”€ Google OAuth (for social login) + โ”œโ”€โ”€ SendGrid (for email verification) + โ””โ”€โ”€ Twilio (for SMS 2FA) +``` + +When Alice logs into the Employee Portal: + +1. She visits the app's login URL +2. Chooses to sign in with Google (an OAuth provider) +3. Google authenticates her and returns to Casdoor +4. Casdoor creates/updates her user record in Acme Corp organization +5. She gets access to the Employee Portal! + +## Next Steps + +Now that you understand the core concepts, you're ready to: + +- **[Try Casdoor with Docker](/docs/basic/try-with-docker)** - Get hands-on experience +- **[Configure Your First Application](/docs/application/overview)** - Set up authentication +- **[Add Providers](/docs/provider/overview)** - Enable social login and notifications +- **[Manage Users](/docs/user/overview)** - Learn about user management + +Questions? Head to our [Discord community](https://discord.gg/5rPsrAzK7S) where fellow Casdoor users and maintainers are ready to help! From ec1f4193bacc5cc33e4c542c547e424dd4f2676f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 16:47:35 +0000 Subject: [PATCH 4/5] docs: rewrite try-with-docker.md with step-by-step guidance and troubleshooting Co-authored-by: hsluoyz <3787410+hsluoyz@users.noreply.github.com> --- docs/basic/try-with-docker.md | 242 ++++++++++++++++++++++++++-------- 1 file changed, 188 insertions(+), 54 deletions(-) diff --git a/docs/basic/try-with-docker.md b/docs/basic/try-with-docker.md index 3657c4393..72c40b96a 100644 --- a/docs/basic/try-with-docker.md +++ b/docs/basic/try-with-docker.md @@ -1,118 +1,252 @@ --- -title: (Optional) Try with Docker -description: Try Casdoor with Docker -keywords: [Casdoor, Docker] +title: Quick Start with Docker +description: Get Casdoor running in minutes with Docker +keywords: [Casdoor, Docker, Quick Start, Getting Started] authors: [hsluoyz] --- -## Requirements +Docker is the fastest way to get Casdoor up and running. Whether you're exploring Casdoor for the first time or setting up a development environment, you'll be logging in within minutes! -### Hardware +## Before You Begin -If you want to build the Docker image yourself, please ensure that your machine has at least **2GB** of memory. Casdoor's frontend is an NPM project of React. Building the frontend requires at least **2GB** of memory. Having less than **2GB** of memory may result in a frontend build failure. +### System Requirements -If you only need to run the pre-built image, please ensure that your machine has at least **100MB** of memory. +**To Run Pre-built Images** (quickest option): -### OS +- ๐Ÿ’พ At least **100MB** of RAM +- ๐Ÿ–ฅ๏ธ Any OS: Linux, Windows, or macOS +- ๐Ÿณ Docker Engine 17.05+ or Docker Desktop -All operating systems (Linux, Windows, and macOS) are supported. +**To Build Images Yourself** (optional): -### Docker +- ๐Ÿ’พ At least **2GB** of RAM (needed for React frontend compilation) +- ๐Ÿ–ฅ๏ธ Any OS: Linux, Windows, or macOS +- ๐Ÿณ Docker Engine 17.05+ or Docker Desktop -You can use **Docker (docker-engine version >= 17.05)** in Linux or **Docker Desktop** in Windows and macOS. +:::tip Why 17.05+? -* [Docker](https://docs.docker.com/get-docker/) +We use Docker's multi-stage build feature introduced in version 17.05. Learn more about [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/). -Regardless of the operating system, users must ensure that they have **docker-engine version >= 17.05**. This is because we utilize the multi-stage build feature in the docker-compose.yml, which is supported in versions 17.05 and above. For more information, see . +::: + +### Install Docker + +Don't have Docker yet? No problem! -If you are also using docker-compose, please ensure that you have **docker-compose version >= 2.2**. For Linux users, you also need to make sure that docker-compose is installed, as it is separate from docker-engine. +- **Download**: [Get Docker](https://docs.docker.com/get-docker/) +- **Linux users**: Make sure `docker-compose` is installed separately (it's not bundled with Docker Engine) +- **Version check**: Run `docker --version` and ensure it's 17.05 or newer -## Get the image +## Choose Your Docker Image -We have provided two DockerHub images: +We provide two official images on DockerHub. Pick the one that fits your needs: -Name | Description | Suggestion -----|------|---- -[casdoor-all-in-one](https://hub.docker.com/r/casbin/casdoor-all-in-one) | Both Casdoor and a MySQL database are included in the image | This image already includes a toy database and is only for testing purposes -[casdoor](https://hub.docker.com/r/casbin/casdoor) | Only Casdoor is included in the image | This image can be connected to your own database and used in production +| Image | What's Inside | Best For | Production Ready? | +|-------|--------------|----------|------------------| +| [**casdoor-all-in-one**](https://hub.docker.com/r/casbin/casdoor-all-in-one) | Casdoor + MySQL database | Quick testing & demos | โŒ No (toy database) | +| [**casdoor**](https://hub.docker.com/r/casbin/casdoor) | Just Casdoor | Production use with your own DB | โœ… Yes | -1. casbin/casdoor-all-in-one: This image includes the casdoor binary, a MySQL database, and all the necessary configurations. It is designed for new users who want to try Casdoor quickly. With this image, you can start Casdoor immediately with just one or two commands, without any complex configuration. However, please note that we **do not recommend** using this image in a production environment. +## ๐Ÿš€ Option 1: Fastest Start (All-in-One) -### **Option-1**: Use the toy database +Perfect for trying out Casdoor without any configuration hassle. -Run the container with port `8000` exposed to the host. The image will be automatically pulled if it doesn't exist on the local host. +### Start Casdoor -```shell +Just run this command: + +```bash docker run -p 8000:8000 casbin/casdoor-all-in-one ``` -Visit [**http://localhost:8000**](http://localhost:8000) in your browser. Log into the Casdoor dashboard with the default global admin account: `built-in/admin` +Docker will automatically download the image if you don't have it yet. Once it starts, you'll see logs indicating that Casdoor is ready. -```bash -admin -123 +### Access Casdoor + +Open your browser and visit: **[http://localhost:8000](http://localhost:8000)** + +### Login + +Use the default admin credentials: + +```text +Username: admin +Password: 123 ``` -### **Option-2**: Try directly with the standard image +:::caution Change Default Password + +For security, change this password immediately after logging in! Go to your user profile and update it. + +::: + +**That's it!** You're now running Casdoor. Explore the dashboard, create test users, and see how it works. + +## ๐Ÿ”ง Option 2: Standard Image with Custom Configuration -:::tip +Use this when you want more control over configuration or need to connect to your own database. -If it is not convenient to mount the configuration file to a container, using environment variables is also a possible solution. +### Using Environment Variables (Easiest) -```bash title="example" +No config file? No problem! Pass settings via environment variables: +```bash docker run \ -e driverName=mysql \ - -e dataSourceName='user:password@tcp(x.x.x.x:3306)/' \ + -e dataSourceName='user:password@tcp(your-db-host:3306)/' \ -p 8000:8000 \ casbin/casdoor:latest +``` +Replace `user`, `password`, and `your-db-host` with your actual database credentials. + +### Using a Configuration File (More Options) + +For advanced configuration, mount an `app.conf` file into the container. + +**Step 1: Create your configuration** + +Download the sample config file from [Casdoor's GitHub](https://github.com/casdoor/casdoor/blob/master/conf/app.conf) and save it locally as `conf/app.conf`. + +For configuration details, see [Server Installation - Via INI File](/docs/basic/server-installation#via-ini-file). + +**Step 2: Run with volume mount** + +```bash +docker run -p 8000:8000 -v /path/to/your/conf:/conf casbin/casdoor:latest ``` -::: +Replace `/path/to/your/conf` with the actual path to your `conf` directory. + +:::note Permission Tip -Create `conf/app.conf`. You can copy it from [conf/app.conf](https://github.com/casdoor/casdoor/blob/master/conf/app.conf) in Casdoor. For more details about `app.conf`, you can see [Via Ini file](/docs/basic/server-installation#via-ini-file). +The Casdoor container runs as user ID 1000. If you're using SQLite or any file-based storage, make sure the mounted directory is readable/writable by UID 1000 to avoid `permission denied` errors. -Then run +**Fix permissions if needed:** ```bash -docker run -p 8000:8000 -v /folder/of/app.conf:/conf casbin/casdoor:latest +sudo chown -R 1000:1000 /path/to/your/conf ``` -:::note -The default user of Casdoor has a uid and gid of 1000. When using volume mapping with SQLite (or any storage requiring file permissions), ensure that the path (e.g., `/folder/of/app.conf` in the example above) is accessible to uid 1000. This avoids permission errors like `permission denied` when Casdoor writes to mapped volumes. ::: -Anyway, just **mount the app.conf to /conf/app.conf** and start the container. +**Step 3: Access Casdoor** -Visit [**http://localhost:8000**](http://localhost:8000) in your browser. Log into the Casdoor dashboard with the default global admin account: `built-in/admin` +Visit **[http://localhost:8000](http://localhost:8000)** and login with: -```bash -admin -123 +```text +Username: admin +Password: 123 ``` -### **Option-3**: Try with docker-compose +## ๐Ÿณ Option 3: Docker Compose (Recommended for Development) + +Docker Compose makes it easy to run Casdoor with a dedicated database in a multi-container setup. -Create a `conf/app.conf` directory in the same directory level as the `docker-compose.yml` file. Then, copy [app.conf](https://github.com/casdoor/casdoor/blob/master/conf/app.conf) from Casdoor. For more details about `app.conf`, you can see [Via Ini file](/docs/basic/server-installation#via-ini-file). +### Setup Steps -Create a separate database using docker-compose: +**Step 1: Get the docker-compose file** + +Create a `docker-compose.yml` file. You can find examples in the [Casdoor repository](https://github.com/casdoor/casdoor). + +**Step 2: Create configuration** + +In the same directory as your `docker-compose.yml`, create a `conf/` folder and add `app.conf`: ```bash -docker-compose up +mkdir conf +cd conf +# Download app.conf from GitHub or create your own +wget https://raw.githubusercontent.com/casdoor/casdoor/master/conf/app.conf +cd .. ``` -That's it! :small_airplane: +For configuration details, see [Server Installation - Via INI File](/docs/basic/server-installation#via-ini-file). -Visit [**http://localhost:8000**](http://localhost:8000) in your browser. Log into the Casdoor dashboard with the default global admin account: `built-in/admin` +**Step 3: Start everything** ```bash -admin -123 +docker-compose up +``` + +Docker Compose will: + +1. ๐Ÿ—„๏ธ Create and start a MySQL database container +2. ๐Ÿš€ Start the Casdoor container +3. ๐Ÿ”— Connect them together + +Watch the logs as everything spins up. Once you see "Casdoor is running...", you're ready! + +**Step 4: Access Casdoor** + +Visit **[http://localhost:8000](http://localhost:8000)** and login: + +```text +Username: admin +Password: 123 ``` -:::note +:::tip Understanding the Magic -If you dig deeper into the docker-compose.yml file, you may be puzzled by the environment variable we created called "RUNNING_IN_DOCKER". When the database 'db' is created via docker-compose, it is available on your PC's localhost but not the localhost of the Casdoor container. To prevent you from running into troubles caused by modifying app.conf, which can be quite difficult for a new user, we provided this environment variable and pre-assigned it in the docker-compose.yml. When this environment variable is set to true, localhost will be replaced with host.docker.internal so that Casdoor can access the database. +If you peek inside the `docker-compose.yml`, you'll notice an environment variable called `RUNNING_IN_DOCKER`. Here's why it exists: + +When Docker Compose creates the database container, it's accessible at `localhost` from your PC, but **not** from inside the Casdoor container. To solve this, we use this environment variable to automatically replace `localhost` with `host.docker.internal`, allowing Casdoor to reach the database. + +This saves you from manually editing `app.conf` - one less thing to worry about! ::: + +## ๐ŸŽ‰ You're All Set! + +Casdoor is now running. Here's what to explore next: + +### First Steps + +1. **๐Ÿ” Change the Admin Password** + Click on your profile in the top-right corner and update your password. + +2. **๐Ÿ‘ฅ Create Your First Organization** + Navigate to "Organizations" and create one for your project. + +3. **๐Ÿ“ฑ Add an Application** + Go to "Applications" and register your app that will use Casdoor for authentication. + +4. **๐Ÿ”Œ Configure Providers** (Optional) + Add OAuth providers like GitHub or Google to enable social login. + +### Common Tasks + +- **Stop Casdoor**: Press `Ctrl+C` in the terminal (or `docker-compose down` for compose setups) +- **View Logs**: `docker logs ` or `docker-compose logs` +- **Restart**: `docker-compose restart` or restart the container + +### Troubleshooting + +**Port 8000 already in use?** + +```bash +# Use a different port +docker run -p 8080:8000 casbin/casdoor-all-in-one +# Then visit http://localhost:8080 +``` + +**Can't connect to database?** + +- Check that your database is running +- Verify connection credentials in `app.conf` +- Ensure firewall allows database connections + +**Permission denied errors?** + +- Make sure mounted volumes are accessible to UID 1000 +- Run: `sudo chown -R 1000:1000 /path/to/conf` + +## Next Steps + +Now that Casdoor is running, dive deeper: + +- **[Core Concepts](/docs/basic/core-concepts)** - Understand organizations, users, and applications +- **[Connect Your App](/docs/how-to-connect/oauth)** - Integrate Casdoor with your application +- **[Production Deployment](/docs/deployment/overview)** - Deploy Casdoor for real-world use +- **[Configuration Guide](/docs/basic/configuration)** - Fine-tune settings for your needs + +Questions? Join our [Discord community](https://discord.gg/5rPsrAzK7S) - we're here to help! ๐Ÿš€ From 03f83a549988e57eef18ca1f4a849f7e522020b5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 16:50:19 +0000 Subject: [PATCH 5/5] docs: rewrite contributing.md with welcoming tone and clear guidelines Co-authored-by: hsluoyz <3787410+hsluoyz@users.noreply.github.com> --- docs/contributing.md | 373 +++++++++++++++++++++++++++++++++---------- 1 file changed, 287 insertions(+), 86 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 8e0d1c919..598dcac3d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,66 +1,163 @@ --- -title: Contributor Guide -description: A guide on how to contribute to Casdoor -keywords: [Contributor, guide] +title: Contributing to Casdoor +description: Join our community and help make Casdoor better! +keywords: [Contributing, Contributor, Guide, Open Source] authors: [leo220yuyaodog] --- -Welcome to Casdoor! This document serves as a guide on how to contribute to Casdoor. +We're thrilled that you're interested in contributing to Casdoor! Whether you're fixing a typo, adding a feature, or helping others in discussions, every contribution makes a difference. -If you find any incorrect or missing information, please leave your comments or suggestions. +This guide will help you get started. Don't worry if you're new to open source - we were all beginners once, and we're here to help you every step of the way! -## Get Involved +## Ways to Contribute -There are many ways to contribute to Casdoor. Here are some ideas to get started: +You don't need to be a coding expert to contribute! Here are some ways you can help: -- Use Casdoor and report issues. When using Casdoor, report any issuesโ€”whether they're bugs or proposalsโ€”on [GitHub Discussions](https://github.com/casdoor/casdoor/discussions) or on [Discord](https://discord.gg/5rPsrAzK7S) before filing an issue on GitHub. +### ๐Ÿ› Report Bugs and Suggest Features -:::info +Found something that doesn't work? Have an idea for a cool feature? We want to hear about it! -Please use English to describe the details of your problem when reporting an issue. +**Before filing an issue:** -::: +1. ๐Ÿ’ฌ Discuss it first on [GitHub Discussions](https://github.com/casdoor/casdoor/discussions) or our [Discord](https://discord.gg/5rPsrAzK7S) +2. ๐Ÿ” Check if someone else already reported it +3. โœ๏ธ Write your report in English (so everyone can understand) -- Help with documentation. Starting your contribution with documentation is a good choice. +This helps us understand your needs and may save you time if there's already a solution! -- Help solve issues. We have a table containing easy tasks suitable for beginners under [Casdoor Easy Tasks](https://github.com/orgs/casdoor/projects/1), with different levels of challenges labeled with different tags. +### ๐Ÿ“ Improve Documentation -## Contributing +Documentation is crucial, and it's a fantastic way to start contributing! You can: -If you are ready to create a PR, here is the workflow for contributors: +- Fix typos or clarify confusing explanations +- Add examples to make concepts clearer +- Write tutorials for common use cases +- Translate docs to other languages -1. Fork to your own repository. +**Why start here?** It helps you learn the project while making immediate impact. Plus, great docs help thousands of users! -2. Clone your fork to a local repository. +### ๐Ÿ’ป Fix Issues -3. Create a new branch and work on it. +Ready to code? Check out our [Easy Tasks Board](https://github.com/orgs/casdoor/projects/1) where we've curated beginner-friendly issues with labels like: -4. Keep your branch in sync. +- `good first issue` - Perfect for newcomers +- `help wanted` - We'd love assistance on these +- `documentation` - Doc improvements needed +- `bug` - Something's broken and needs fixing -5. Commit your changes. Make sure your commit message is concise. +Pick one that interests you and let us know you're working on it! -6. Push your commits to your forked repository. +### ๐ŸŒŸ Help Others -7. Create a pull request from your branch to our **master** branch. +Answer questions in Discussions or Discord. Share your Casdoor setup. Write a blog post about your experience. Community building is contribution too! -## Pull Requests +## Making Your First Contribution -### Before You Get Started +Ready to submit code or documentation? Here's the step-by-step process: -Casdoor uses GitHub as its development platform, and pull requests are the primary source of contributions. +### Step 1: Fork the Repository -Here are some things you need to know before opening a pull request: +Click the "Fork" button on the [Casdoor repository](https://github.com/casdoor/casdoor) to create your own copy. -- You need to sign the **CLA** when you first create a pull request. +### Step 2: Clone Your Fork -- Explain why you are submitting the pull request and what it will do to the repo. +```bash +git clone https://github.com/YOUR-USERNAME/casdoor.git +cd casdoor +``` -- Only one commit is allowed per pull request. If the PR does more than one thing, please split it into multiple PRs. +Replace `YOUR-USERNAME` with your GitHub username. -- If there are any newly added files, please include the Casdoor license at the top of the new file(s). +### Step 3: Create a Feature Branch -```text -// Copyright 2022 The Casdoor Authors. All Rights Reserved. +Never work directly on `master`! Create a branch for your changes: + +```bash +git checkout -b my-awesome-feature +``` + +Use a descriptive name that explains what you're working on. + +### Step 4: Make Your Changes + +Now the fun part - write your code or docs! Remember to: + +- Keep changes focused (one feature or fix per PR) +- Write clear, readable code +- Test your changes locally +- Follow existing code style + +### Step 5: Keep Your Branch Updated + +While you work, the main repository might get new commits. Stay in sync: + +```bash +git remote add upstream https://github.com/casdoor/casdoor.git +git fetch upstream +git rebase upstream/master +``` + +### Step 6: Commit Your Changes + +Write a clear, concise commit message: + +```bash +git add . +git commit -m "feat: add email verification for signup" +``` + +We'll cover commit message format in the next section! + +### Step 7: Push to Your Fork + +```bash +git push origin my-awesome-feature +``` + +### Step 8: Create a Pull Request + +Go to your fork on GitHub and click "New Pull Request". Fill in: + +- **Title**: Clear, descriptive (follow our format below) +- **Description**: Explain what and why +- **Linked Issues**: Reference related issues with `fixes #123` + +Then hit "Create Pull Request" and wait for review! ๐ŸŽ‰ + +## Pull Request Guidelines + +To keep things organized and make reviews faster, please follow these guidelines: + +### Sign the CLA + +On your first PR, you'll be asked to sign our Contributor License Agreement (CLA). It's quick and only needed once! + +### Write Good PR Descriptions + +Help reviewers understand your changes: + +```markdown +## What does this PR do? +Adds email verification to the signup process + +## Why is this needed? +Prevents fake accounts and improves security + +## How was it tested? +- Manually tested signup flow +- Added unit tests for email verification +``` + +### One PR, One Purpose + +Keep PRs focused! If you're adding multiple features, split them into separate PRs. This makes review easier and faster. + +### Add License Headers to New Files + +Any new file you create needs our license header: + +```go +// Copyright 2024 The Casdoor Authors. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -75,105 +172,209 @@ Here are some things you need to know before opening a pull request: // limitations under the License. ``` -### Semantic PRs +Just copy and paste this at the top, updating the year as needed. + +## Commit Message Format -Your pull requests should follow the Conventional Commits spec. The basic requirement is that only the PR title or at least one commit message. For example, three commonly used PR titles are given below: +We use [Conventional Commits](https://www.conventionalcommits.org/) to keep our git history clean and generate changelogs automatically. :::caution -PR titles must be in lowercase. +PR titles and commit messages **must be in lowercase**. ::: -1. **fix**: a commit of the _type_ `fix` patches a bug in your codebase. +| Type | When to Use | Example | +|------|------------|---------| +| `feat:` | Adding a new feature | `feat: add oauth provider for twitter` | +| `fix:` | Fixing a bug | `fix: prevent race condition in token refresh` | +| `docs:` | Documentation changes | `docs: update installation guide` | +| `style:` | Code formatting (no logic change) | `style: fix indentation in auth.go` | +| `refactor:` | Code refactoring | `refactor: simplify user validation logic` | +| `test:` | Adding or updating tests | `test: add tests for email verification` | +| `chore:` | Maintenance tasks | `chore: update dependencies` | + +### Examples + +**Good:** - ```text - fix: prevent racing of requests - ``` +```text +fix: resolve database connection timeout +docs: add examples for custom providers +feat: implement rate limiting for api endpoints +``` -2. **feat**: a commit of the _type_ `feat` introduces a new feature to the codebase. +**Bad:** - ```text - feat: allow provided config object to extend other configs - ``` +```text +Fix: Database issue (uppercase) +update docs (missing type) +Added new feature for users (not concise) +``` -3. **docs**: a commit of the _type_ `docs` adds or improves documentation. +## Updating a Pull Request - ```text - docs: correct spelling of CHANGELOG - ``` +Got review feedback? No problem! Here's how to update your PR: -For more details, please refer to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) page. +### Make Changes Locally -### Linking PRs with Issues +Edit your files based on the feedback. -You can link a pull request to an issue to show a fix is in progress and to automatically close the issue when the pull request is merged. +### Amend Your Commit -#### Linking a Pull Request to an Issue Using a Keyword +Instead of creating a new commit, update the existing one: -You can link a pull request to an issue by using a supported keyword in the pull request's description or in a commit message. The pull request **must be** on the default branch. +```bash +git add . +git commit --amend +``` -- close -- fix -- resolve +This keeps your PR to a single, clean commit. -An issue in the same repository, for instance: +### Force Push -```text -Fix: #902 +Since you've rewritten history, use force push: + +```bash +git push --force origin my-awesome-feature ``` -For more details, please refer to [Linking a Pull Request to an Issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). +Your PR will automatically update! The reviewer will see your changes. -### Modifying PRs +## Linking PRs to Issues -Your PR may need revision. Please modify the same PR when the code needs changes; don't close the PR and open a new one. Here is an example: +Connecting your PR to an issue helps track progress and automatically closes issues when merged. -- Modify the code on your local. +### How to Link -- Modify your commit. +Use keywords in your PR description or commit message: -```shell -git commit --amend -``` +- `fixes #123` - Closes issue #123 when merged +- `resolves #456` - Closes issue #456 when merged +- `closes #789` - Closes issue #789 when merged + +**Example PR description:** -- Push to your remote repository. +```markdown +## Summary +Add email verification for new users -```shell -git push --force +This PR fixes #234 and resolves #256 + +## Changes +- Implemented email sending service +- Added verification code generation +- Updated signup flow ``` -Then, you will have successfully modified the PR! +When this PR merges, issues #234 and #256 will automatically close! -## Code Related +Learn more: [Linking PRs to Issues (GitHub Docs)](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) -Some Principles: +## Code Guidelines -- Readability: important code should be well-documented. Code style should comply with the existing one. +Follow these principles to keep our codebase clean and maintainable: -### Naming Convention +### Write Readable Code -For instance, `signupUrl` for variable names, `Signup URL` for UI. +- **Document complex logic**: Add comments explaining *why*, not just *what* +- **Follow existing style**: Match the formatting and patterns already in use +- **Use meaningful names**: `getUserByEmail()` is better than `get()` -### How to Update i18n Data? +### Naming Conventions -Please note that we use [Crowdin](https://crowdin.com/project/casdoor-site) as a translating platform and i18next as a translating tool. When you add strings using i18next in the `web/` directory, you can run the `i18n/generate_test.go` to auto-generate `web/src/locales/**/data.json`. +Be consistent with naming across the codebase: -Run `i18n/generate_test.go`: +- **Variables**: `camelCase` - e.g., `signupUrl`, `emailProvider` +- **UI Text**: `Title Case` - e.g., "Signup URL", "Email Provider" +- **Functions**: `camelCase` - e.g., `validateUser()`, `sendEmail()` +- **Constants**: `UPPER_SNAKE_CASE` - e.g., `MAX_RETRY_COUNT` -```shell -cd i18n && go test -``` +### Working with Internationalization (i18n) -All languages are filled in English by default. After your PR has been merged, you are encouraged to help translate the newly added -strings in `web/src/locales/zh/data.json` by [Crowdin](https://crowdin.com/project/casdoor-site). +Casdoor supports multiple languages using [Crowdin](https://crowdin.com/project/casdoor-site) and i18next. -:::caution +**When adding new UI strings:** + +1. Add them to your code using i18next + +2. Generate translation files: + + ```bash + cd i18n + go test + ``` -If you are not familiar with a language, please do not translate it; keep the file as it is. + This auto-generates `web/src/locales/**/data.json` files with English defaults. + +3. After your PR merges, help translate at [Crowdin](https://crowdin.com/project/casdoor-site) + +:::caution Translation Etiquette + +**Only translate languages you know well!** Machine translations can be misleading or incorrect. If unsure, leave it in English - native speakers will translate it properly. ::: +## Getting Help + +Stuck? Have questions? We're here to help! + +### Before Asking + +1. ๐Ÿ“– Check the [documentation](https://casdoor.org/docs) +2. ๐Ÿ” Search [existing issues](https://github.com/casdoor/casdoor/issues) +3. ๐Ÿ’ฌ Browse [GitHub Discussions](https://github.com/casdoor/casdoor/discussions) + +### Ask the Community + +- **๐Ÿ’ฌ Discord**: [Join our server](https://discord.gg/5rPsrAzK7S) for real-time chat +- **๐Ÿ’ญ GitHub Discussions**: [Ask questions](https://github.com/casdoor/casdoor/discussions) that help others too +- **๐Ÿ› GitHub Issues**: For verified bugs only (discuss first!) + +### Response Time + +We're a global community, so responses might take a bit. Usually: + +- Discord: A few hours +- GitHub Discussions: 1-2 days +- Pull Request reviews: 2-5 days + +Please be patient - we're all volunteers! โค๏ธ + +## Code of Conduct + +Be respectful, inclusive, and helpful. We're building software together, and kindness makes everything better. + +- **Be welcoming**: Everyone was a beginner once +- **Be patient**: Not everyone has the same experience level +- **Be constructive**: Criticism should be about code, not people +- **Be collaborative**: We're on the same team! + ## License -By contributing to Casdoor, you agree that your contributions will be licensed under the Apache License. +By contributing to Casdoor, you agree that your contributions will be licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0). + +This ensures Casdoor remains open source and free for everyone. + +## Thank You! ๐Ÿ™ + +Every contribution, no matter how small, makes Casdoor better for thousands of users worldwide. We appreciate your time and effort! + +### Recognition + +Contributors are recognized in: + +- Our [Contributors page](https://github.com/casdoor/casdoor/graphs/contributors) +- Release notes for significant features +- The project's history forever! + +### What's Next? + +Ready to start? Here's your roadmap: + +1. **๐Ÿ‘€ Browse [Good First Issues](https://github.com/orgs/casdoor/projects/1)** +2. **๐Ÿ’ฌ Say hi on [Discord](https://discord.gg/5rPsrAzK7S)** +3. **๐Ÿด Fork the repo and start coding!** +4. **๐Ÿ“ Submit your first PR** + +Welcome to the team! ๐Ÿš€