Required dependencies

This is a Go + React project. The frontend lives in source/web/.

# Frontend (run inside source/web/)
npm install

For the Go backend, use the Go toolchain directly:

# Install Go 1.20+ then:
go mod download

Native / additional build steps:

• Go 1.20 or later is required to build the backend.
• Run npm run build inside source/web/ to produce the static frontend assets before embedding them into the Go binary.
• Docker: docker-compose up in source/ starts Casdoor + a MySQL instance with no further manual steps.
• source/build.sh orchestrates the full frontend + backend build in CI.

Project setup

1. Clone or copy the source/ directory into your project root (e.g. ./casdoor-src/).
2. Copy source/conf/app.conf to your working directory and edit the database DSN, HTTP port, and runmode:

   httpport = 8000
   runmode = dev
   driverName = mysql
   dataSourceName = root:password@tcp(localhost:3306)/casdoor
   dbName = casdoor
   

3. Set the following environment variables (or keep them in app.conf):

   export CASDOOR_DB_DRIVER=mysql
   export CASDOOR_DB_DSN="root:password@tcp(127.0.0.1:3306)/casdoor"
   

4. Build and start the backend:

   cd casdoor-src
   go run main.go
   

5. Build the frontend separately if you want to serve static assets from Go:

   cd casdoor-src/web
   npm install && npm run build
   

6. For TypeScript projects that call Casdoor's REST API, use the official casdoor-js-sdk npm package as the HTTP client; the source here is the server, not a client library.

Public API

The symbols below are from the actual file excerpts provided.

App (React root component)

// web/src/App.js (default export, used in web/src/index.js)
import App from "./App";

The App component is the root of the React SPA. It is mounted in index.js via createRoot inside a BrowserRouter. Reference this when you need to understand the top-level routing structure or when embedding Casdoor's frontend into a micro-frontend shell.

createRoot + BrowserRouter wiring

// Mirrors web/src/index.js exactly
import React from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import App from "./App";

const container = document.getElementById("root");
const app = createRoot(container);

app.render(
  <BrowserRouter>
    <App />
  </BrowserRouter>
);

This is the canonical bootstrap pattern from index.js. Use it when re-hosting the Casdoor frontend inside your own shell app or when upgrading the project from ReactDOM.render to the React 18 createRoot API.

FetchFilter (request interceptor)

// web/src/backend/FetchFilter.js  (imported as side-effect in index.js)
import "./backend/FetchFilter";

FetchFilter is imported purely for its side effects: it patches the global fetch to add CSRF tokens and session headers to every outbound API request. Import it once, at application entry, before any API calls are made. Do not import it more than once; duplicate imports produce duplicate interceptor registrations.

Working examples

Scenario - Bootstrapping the Casdoor server locally with Docker

Start a fully-wired Casdoor instance (MySQL + server) with a single command. Useful for local development against a real auth endpoint.

# From source/
docker-compose up -d
# Casdoor is now available at http://localhost:8000
# Default admin: admin / 123

// After the server is up, verify it responds:
const response = await fetch("http://localhost:8000/api/health");
const data = await response.json();
console.log(data); // { "status": "ok" }

Scenario - Embedding Casdoor frontend in a React host app

Reuse the Casdoor React entry point inside a host application that already controls its own router.

// host-app/src/AuthShell.tsx
import React from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";

// Point the alias to your copy of source/web/src
import App from "../../casdoor-src/web/src/App";
// Must be imported once to register fetch interceptors
import "../../casdoor-src/web/src/backend/FetchFilter";

export function mountCasdoorUI(containerId: string): void {
  const el = document.getElementById(containerId);
  if (!el) throw new Error(`Container #${containerId} not found`);
  const root = createRoot(el);
  root.render(
    <BrowserRouter>
      <App />
    </BrowserRouter>
  );
}

Scenario - Calling Casdoor REST API from a TypeScript backend

Authenticate a machine-to-machine request using Casdoor's OAuth2 client credentials flow.

// services/auth.ts
async function getClientCredentialsToken(
  casdoorBaseUrl: string,
  clientId: string,
  clientSecret: string,
  scope: string
): Promise<string> {
  const params = new URLSearchParams({
    grant_type: "client_credentials",
    client_id: clientId,
    client_secret: clientSecret,
    scope,
  });

  const res = await fetch(`${casdoorBaseUrl}/api/login/oauth/access_token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: params.toString(),
  });

  if (!res.ok) {
    throw new Error(`Token request failed: ${res.status}`);
  }

  const json = await res.json();
  return json.access_token as string;
}

// Usage
const token = await getClientCredentialsToken(
  "http://localhost:8000",
  "your-client-id",
  "your-client-secret",
  "read"
);
console.log("access_token:", token);

File walkthrough

• .github/workflows/ - GitHub Actions pipelines for building binaries and syncing translations via Crowdin.
• .vscode/launch.json - VSCode debug configuration for attaching the Go debugger to a running Casdoor process.
• authz/authz.go - Initializes the Casbin enforcer; defines the enforce function used in middleware to check permissions.
• captcha/ - One file per captcha vendor; each implements the Provider interface defined in captcha/provider.go.
• certificate/ - ACME/Let's Encrypt account management, DNS challenge helpers, and ECC key pair generation.
• conf/conf.go - Reads app.conf via beego's config system and exposes typed accessors for all settings.
• controllers/base.go - Base controller with helper methods for JSON response writing and session extraction, embedded by all other controllers.
• controllers/auth.go - Handles /api/login, token issuance, and OAuth2/OIDC authorize endpoint logic.
• object/ - The persistence layer; contains ORM structs and CRUD functions for every domain entity (User, Org, App, Token, etc.).
• routers/ - Registers all HTTP routes against beego's router, applying auth middleware and CORS headers.
• web/src/index.js - React application entry point; mounts <App> into #root using React 18 createRoot.
• main.go - Parses flags, initializes database connections, starts the HTTP server, and registers routes.
• docker-compose.yml - Defines casdoor and db services; the fastest path to a running environment.
• k8s.yaml - Production-ready Kubernetes Deployment + Service + ConfigMap manifests.

Common pitfalls and fixes

• Database not initialized: Casdoor auto-migrates but requires an empty database to exist first. Fix: CREATE DATABASE casdoor; before first run.
• app.conf not found at runtime: The server looks for conf/app.conf relative to the working directory, not the binary location. Fix: always run go run main.go from source/, or set --conf flag to an absolute path.
• Frontend build artifacts missing: The Go binary embeds web/build/ at compile time; if the directory is absent the UI returns 404. Fix: run cd web && npm run build before go build.
• CORS errors calling the API from a different origin: Casdoor's CORS whitelist is application-scoped. Fix: add your frontend origin in the Casdoor admin UI under the target Application's "CORS origins" field.
• React 18 createRoot double-render in StrictMode: Casdoor's index.js does not wrap in <StrictMode>, so effects fire once. Fix: do not add StrictMode without auditing all useEffect hooks for idempotency.
• FetchFilter imported multiple times: Bundler tree-shaking does not deduplicate side-effect-only imports when referenced from multiple entry chunks. Fix: import FetchFilter only in the top-level index.js/entry file.

Vibe-coding prompt template

I have the Casdoor IAM server source code in the `source/` directory of my project.
I also have a USAGE.md file that documents the real exports, file layout, and integration patterns.

My project is a [describe your stack, e.g. "Node.js + Express API with a React frontend"].

Please read USAGE.md and the relevant files under source/ and then:
1. Set up the Casdoor backend (Go) to run alongside my project using docker-compose.
2. Configure my React frontend to redirect unauthenticated users to Casdoor's login page using the OAuth2 authorization code flow.
3. Add a middleware to my Express API that validates Casdoor-issued JWTs using the JWKS endpoint at /api/get-jwks.
4. Show me how to call Casdoor's /api/get-users endpoint with an admin token to list all users.
5. Point out any environment variables I need to set and where they map to in source/conf/app.conf.

Work step-by-step and use only the real API surface documented in USAGE.md.
Do not invent endpoints or configuration keys that are not shown there.

License and credit

Casdoor is released under the Apache License 2.0. See source/LICENSE for the full text.

Upstream repository: https://github.com/casdoor/casdoor Official documentation: https://casdoor.ai/docs/overview

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Keycloak Identity and Access Management Platform

Automation, Utilities & Developer Tools

Free