Skip to main content

Server Installation

Requirements​

Operating System​

All major operating systems, including Windows, Linux, and macOS, are supported.

Environment​

info

We strongly suggest using Yarn 1.x to run and build Casdoor frontend. Using NPM might cause UI styling issues. For more details, see: casdoor#294.

caution

If your network fails to directly sync the 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:

  • MySQL
  • MariaDB
  • PostgreSQL
  • CockroachDB
  • SQL Server
  • Oracle
  • SQLite 3
  • TiDB

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.

NameDescriptionLanguageSource code
FrontendWeb frontend UI for CasdoorJavaScript + Reacthttps://github.com/casdoor/casdoor/tree/master/web
BackendRESTful API backend for CasdoorGolang + Beego + XORMhttps://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 selecting a database 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
info

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
info

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, which by default contains the following content:

appname = casdoor
httpport = 8000
runmode = dev
SessionOn = true
copyrequestbody = true
driverName = mysql
dataSourceName = root:123456@tcp(localhost:3306)/
dbName = casdoor
tableNamePrefix =
showSql = false
redisEndpoint =
defaultStorageProvider =
isCloudIntranet = false
authState = "casdoor"
socks5Proxy = "127.0.0.1:10808"
verificationCodeTimeout = 10
initScore = 2000
logPostOnly = true
origin = "https://door.casdoor.com"
staticBaseUrl = "https://cdn.casbin.org"
enableGzip = true
inactiveTimeoutMinutes =
  • appname is the application name, which currently has no practical use.
  • httpport is the port that your backend application is listening on.
  • runmode can be set to dev or prod.
  • SessionOn determines whether to enable session and is enabled by default.
  • driverName, dataSourceName, and dbName were introduced earlier. Please see Configure Database for details.
  • verificationCodeTimeout sets the expiration time of the verification code. After expiration, the user needs to obtain it again.

As a beginner, you only need to modify two items: driverName and dataSourceName based on your database. This database will be used by Casdoor to store all data, including users, organizations, and applications.

  • tableNamePrefix is the prefix of the table when using an adapter.
  • showSql determines whether to show SQL statements on the logger if the log level is greater than INFO.
  • redisEndpoint is the Redis endpoint used by Beego session storage. If this parameter is empty, the session data will be stored locally as files in the ./tmp folder. To use Redis as Beego session storage, the value would be something like: redis.example.com:6379. If Redis is deployed locally, you can use localhost:6379. If Redis password is enabled, use redis.example.com:6379,db,password. See more details at: https://github.com/beego/beedoc/blob/master/en-US/module/session.md#saving-provider-config.
  • defaultStorageProvider is the default file storage service name. If you need to use file storage services such as avatar upload, you need to set up a storage provider and apply it in your application. See storage for details.
  • isCloudIntranet is used to identify whether your provider endpoint is an intranet endpoint.
  • authState is the authorization application name. This parameter will be checked when logging in.
  • socks5Proxy is the SOCKS proxy server IP address. Set the proxy port because we have Google-related services or use Google, GitHub, Facebook, LinkedIn, or Steam as OAuth Providers, which may be restricted by the network in some areas.
  • initScore is the initial score of each user. Each user has a score attribute. The score is used by Casnode and does not control anything in Casdoor.
  • logPostOnly is used to determine whether only the post method is used to add a record.
  • origin is the origin backend domain name.
  • staticBaseUrl is the address of the static image used when the system initializes the database.
  • enableGzip will accept and respond with gzip encoding if the request header includes Accept-Encoding=gzip.
  • inactiveTimeoutMinutes sets the maximum number of minutes of inactivity. If the inactivity time reaches this value, then casdoor will log the user out. Empty value or value less than or equal to 0 means there is no limit on the user's inactivity time.

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
tip

To use another port, please edit conf/app.conf and modify httpport, then restart the Go backend.

Casdoor Port Details

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.

Casnode Example