Server Installation

Requirements

OS

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

Environment

• Go 1.17+
• Node.js LTS (16 or 14)
• Yarn 1.x

info

We strongly suggest you use Yarn 1.x to run & build Casdoor frontend, using NPM might cause UI styling issues, see more details at: casdoor#294

caution

For Chinese users, in order to download the Go dependency packages successfully, you need to use a Go proxy by Configuring the GOPROXY environment variable. We strongly recommend: https://goproxy.cn/

Database

Casdoor uses XORM to talk to the database. Based on Xorm Drivers Support, Casdoor currently provides support for following databases:

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

Download

The source code of Casdoor is hosted at GitHub: https://github.com/casdoor/casdoor. Both the Go backend code and React frontend code are inside the 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, you can just simply clone the code via git:

cd path/to/folder
git clone https://github.com/casdoor/casdoor

Configuration

Configure Database

Casdoor supports mysql, mssql, sqlite3, postgres. Casdoor uses mysql by default. If you use another database, please modify the import package in object/adapter.

MySQL:

Casdoor will store its users, nodes and topics information in a MySQL database named: casdoor. If the database does not exist, it needs to 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:

Since we must choose a database when opening Postgres with xorm, you should prepare a database manually before running Casdoor.

Let's assume that you have already prepared a database called casdoor, then you should specify app.conf like this:

driverName = postgres
dataSourceName = "user=postgres password=postgres host=localhost port=5432 sslmode=disable dbname=casdoor"
dbName =

info

For PostgreSQL, make sure dataSourceName has non-empty dbName and leave the standalone dbName field empty like the above example.

CockroachDB:

You can also use cockroachdb with postgres driver. It has same configuration as postgreSQL.

driverName = postgres
dataSourceName = "user=postgres password=postgres host=localhost port=5432 sslmode=disable dbname=casdoor serial_normalization=virtual_sequence"
dbName =

info

For CockroachDB, don't forget to add serial_normalization=virtual_sequence to the dataSourceName like the above example. otherwise you will get error regarding existed database, whenever the service started or restarted. Notice, this must be added before the database created.

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, the content of which by default is:

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

• appname is the application name, which currently has no practical use
• httpport is the port that your back-end application is listening on
• runmode is dev or prod
• SessionOn decides whether to enable session,used by default.
• driverName, dataSourceName and dbName are introduced before, please see Configure Database.
• verificationCodeTimeout set the expiration time of the verification code. After the expiration, the user needs to obtain it again

Despite all the configurable fields, 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, applications and so on.

• tableNamePrefix is prefix of the table when using adapter.
• showSql : show SQL statement or not on logger if log level is great 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 ./tmp folder. For using Redis as Beego session storage, an example for this value would be: redis.example.com:6379. If Redis is deployed in the local machine, you can use localhost:6379. If Redis password is enabled, use redis.example.com:6379,db,password. See more details at: https://beego.run/docs/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 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 Steam as OAuth Provider which will be restricted by the network in some areas.
• initScore is the initial score of each user. Each user has a score attribute. Score is used by Casnode. Score does not control anything in Casdoor.
• logPostOnly is used to identify whether only use post method to add a record.
• origin is the origin backend domain name.
• staticBaseUrl is address of the static image when the system initializes the database.
• enableGzip will accept and response with gzip encoding when the request header including Accept-Encoding=gzip.

Via Environment Variables

All configuration items defined by Casdoor in the ini file mentioned above can be chosen to configuration via environmental variables, so can 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 environmental variables.

appname=casbin go run main.go

Besides, export derivatives are also a possible method. The names of environmental variables should be exactly the same with the names you want to use in the ini file.

Note: configurations in environmental variables can override the configurations in ini file.

Run

There are currently two methods to start, you can choose one according to your own situation.

Development mode

Backend

Casdoor's Go backend runs at port 8000 by default. You can start the Go backend with the following command:

go run main.go

After the server is successfully running, we can start the frontend part.

Frontend

Casdoor's frontend is a very classic Create-React-App (CRA) project. It runs at 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 Casdoor dashboard with the default global admin account: built-in/admin

admin
123

Production mode

Backend

Build Casdoor Go backend code into executable and start it.

For Linux:

go build
./casdoor

For Windows:

go build
casdoor.exe

Frontend

Build 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 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 dev environment, the frontend is run by yarn run in port 7001, so if you want to go to Casdoor login page, you need set Casdoor link as http://localhost:7001.

In prod environment, the frontend files is first built by yarn build and served in port 8000, so if you want to go to Casdoor login page, you need to set Casdoor link as http://SERVER_IP:8000 (If you are using 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 dev environment, we set the serverUrl as http://localhost:7001, so when we test signin and signup functionality using Casdoor, it will go to localhost 7001 which is the Casdoor port.

And when we put Casnode to prod environment, we set the serverUrl as https://door.casdoor.com, so users can signin or signup using Casdoor.