Server Installation
Requirements
Operating System
All major operating systems are supported, including Windows, Linux, and macOS.
Environment
We strongly recommend using Yarn 1.x to run and build the Casdoor frontend. Using NPM might cause UI styling issues. For more details, see: casdoor#294.
If your network fails to directly sync Go dependency packages successfully, you need to use a Go proxy by configuring the GOPROXY environment variable. We strongly recommend using: https://goproxy.cn/
Database
Casdoor uses XORM to communicate with the database. Based on Xorm Drivers Support, Casdoor currently provides support for the following databases:
MySQLMariaDBPostgreSQLCockroachDBSQL ServerOracleSQLite 3TiDB
Download
The source code of Casdoor is hosted on GitHub: https://github.com/casdoor/casdoor. Both the Go backend code and React frontend code are contained in a single repository.
| Name | Description | Language | Source code |
|---|---|---|---|
| Frontend | Web frontend UI for Casdoor | JavaScript + React | https://github.com/casdoor/casdoor/tree/master/web |
| Backend | RESTful API backend for Casdoor | Golang + Beego + XORM | https://github.com/casdoor/casdoor |
Casdoor supports Go Modules. To download the code, simply clone the code using git:
cd path/to/folder
git clone https://github.com/casdoor/casdoor
Configuration
Configure Database
Casdoor supports MySQL, MSSQL, SQLite3, and PostgreSQL. By default, Casdoor uses MySQL.
MySQL
Casdoor stores user, node, and topic information in a MySQL database named casdoor. If the database does not exist, it must be created manually. The DB connection string can be specified at: https://github.com/casdoor/casdoor/blob/master/conf/app.conf
driverName = mysql
dataSourceName = root:123456@tcp(localhost:3306)/
dbName = casdoor
PostgreSQL
Before running Casdoor, you need to manually prepare a database for PostgreSQL, as Casdoor requires a database to be selected when opening Postgres with xorm.
Assuming you have already prepared a database called casdoor, you should specify app.conf like this:
driverName = postgres
dataSourceName = user=postgres password=postgres host=localhost port=5432 sslmode=disable dbname=casdoor
dbName = casdoor
For PostgreSQL, ensure that dataSourceName has a non-empty dbName and also duplicate the database name for the dbname field as shown in the example above.
CockroachDB
CockroachDB can also be used with the PostgreSQL driver and has the same configuration as PostgreSQL.
driverName = postgres
dataSourceName = user=postgres password=postgres host=localhost port=5432 sslmode=disable dbname=casdoor serial_normalization=virtual_sequence
dbName = casdoor
For CockroachDB, remember to add serial_normalization=virtual_sequence to the dataSourceName as shown in the example above. Otherwise, you will get an error regarding an existing database whenever the service starts or restarts. Note that this must be added before the database is created.
SQLite3
To configure SQLite3, you should specify app.conf like this:
driverName = sqlite
dataSourceName = file:casdoor.db?cache=shared
dbName = casdoor
Via Ini file
Casdoor can be configured via a single file: conf/app.conf. As a beginner, you only need to modify driverName and dataSourceName based on your database (see Configure Database). Below is a complete reference of all configuration options:
| Parameter | Default Value | Description |
|---|---|---|
appname | casdoor | Application name (currently has no practical use) |
httpport | 8000 | Port that the backend application listens on |
runmode | dev | Running mode: dev or prod |
copyrequestbody | true | Whether to copy request body for later use |
driverName | mysql | Database driver (e.g., mysql, postgres, sqlite). See Configure Database |
dataSourceName | root:123456@tcp(localhost:3306)/ | Database connection string. See Configure Database |
dbName | casdoor | Database name used by Casdoor |
tableNamePrefix | (empty) | Prefix for table names when using an adapter |
showSql | false | Show SQL statements in logger when log level is greater than INFO |
redisEndpoint | (empty) | Redis endpoint for session storage (e.g., localhost:6379). If empty, sessions are stored locally in ./tmp. For password: host:port,db,password |
defaultStorageProvider | (empty) | Default storage provider name for file uploads (e.g., avatars). See storage |
isCloudIntranet | false | Whether provider endpoints use intranet addresses |
authState | "casdoor" | Authorization application name checked during login |
socks5Proxy | "127.0.0.1:10808" | SOCKS5 proxy address for OAuth providers (Google, GitHub, etc.) that may be blocked |
verificationCodeTimeout | 10 | Verification code expiration time in minutes |
initScore | 0 | Initial score assigned to new users (used by Casnode, not Casdoor) |
logPostOnly | true | Whether to log only POST requests |
isUsernameLowered | false | Whether to convert usernames to lowercase |
origin | (empty) | Backend origin URL (e.g., https://door.casdoor.com) |
originFrontend | (empty) | Frontend origin URL if different from backend |
staticBaseUrl | "https://cdn.casbin.org" | CDN URL for static assets used during database initialization |
isDemoMode | false | Enable demo mode restrictions |
batchSize | 100 | Batch size for bulk operations |
enableErrorMask | false | Whether to mask detailed error messages |
enableGzip | true | Accept and respond with gzip encoding when client supports it |
inactiveTimeoutMinutes | (empty) | Auto-logout timeout in minutes. Empty or ≤0 means no timeout |
ldapServerPort | 389 | Port for LDAP server |
ldapsCertId | "" | Certificate ID for LDAPS connections |
ldapsServerPort | 636 | Port for LDAPS (LDAP over SSL) server |
radiusServerPort | 1812 | Port for RADIUS server |
radiusDefaultOrganization | "built-in" | Default organization for RADIUS authentication |
radiusSecret | "secret" | Shared secret for RADIUS authentication |
quota | {"organization": -1, "user": -1, "application": -1, "provider": -1} | Resource quotas (-1 means unlimited) |
logConfig | {"adapter":"file", "filename": "logs/casdoor.log", "maxdays":99999, "perm":"0770"} | Logging configuration (adapter, file path, rotation, permissions) |
initDataNewOnly | false | Whether to initialize data only for new installations |
initDataFile | "./init_data.json" | Path to data initialization file. See Data Initialization |
frontendBaseDir | "../cc_0" | Base directory for frontend files (only for development) |
Via Environment Variables
All configuration items defined by Casdoor in the ini file mentioned above can be configured via environment variables, as well as some of the beego configurations items (httpport, appname).
For example, when you try to start Casdoor, you can use something like this to pass the configuration via environment variables:
appname=casbin go run main.go
In addition, export derivatives are also a possible method. The names of environmental variables should exactly match the names you want to use in the ini file.
Note: configurations in environmental variables can override the configurations in the ini file.
Run
There are currently two methods to start, and you can choose one according to your situation.
Development Mode
Backend
Casdoor's Go backend runs on port 8000 by default. You can start the Go backend with the following command:
go run main.go
After the server is successfully running, you can start the frontend part.
Frontend
Casdoor's frontend is a very classic Create-React-App (CRA) project. It runs on port 7001 by default. Use the following commands to run the frontend:
cd web
yarn install
yarn start
Visit http://localhost:7001 in your browser. Log into the Casdoor dashboard with the default global admin account: built-in/admin.
admin
123
Production Mode
Backend
Build the Casdoor Go backend code into an executable and start it.
For Linux:
go build
./casdoor
For Windows:
go build
casdoor.exe
Frontend
Build the Casdoor frontend code into static resources (.html, .js, .css files):
cd web
yarn install
yarn build
Visit http://localhost:8000 in your browser. Log into the Casdoor dashboard with the default global admin account: built-in/admin.
admin
123
To use another port, please edit conf/app.conf and modify httpport, then restart the Go backend.
In the dev environment, the frontend is run by yarn run on port 7001, so if you want to go to the Casdoor login page, you need to set the Casdoor link as http://localhost:7001.
In the prod environment, the frontend files are first built by yarn build and served on port 8000, so if you want to go to the Casdoor login page, you need to set the Casdoor link as https://your-casdoor-url.com:8000 (If you are using a reverse proxy, you need to set the link as your domain).
Take Our Official Forum Casnode as an Example
Casnode uses Casdoor to handle authentication.
When we are testing Casnode in the dev environment, we set the serverUrl as http://localhost:7001, so when we test the signin and signup functionality using Casdoor, it will go to localhost 7001, which is the Casdoor port.
And when we put Casnode into the prod environment, we set the serverUrl as https://door.casdoor.com, so users can sign in or sign up using Casdoor.
