Skip to main content

Install Guide

Requirement

caution

We strongly suggest you use Yarn to install Casdoor, using npm might cause wrong position of widgets, for more details, please see casdoor#294

Installation

It is very simple to install Casdoor, you can use go get

go get github.com/casbin/casdoor

or use git clone

git clone https://github.com/casbin/casdoor

Config

All configures are placed in conf/, including app.conf and oss.conf. The former stores application-related information, while the latter only stores OSS-related configuration. You can modify two files to set all configures.

But for the first time of use, you don’t need to figure out everything, which will be introduced later. Now you just need a few simple configures to run casdoor on your personal computer.

Nevertheless, the database info should be configured first. Casdoor uses XORM framework to connect to DB, so all DBs supported by XORM can also be used.

  • Setup database (MySQL):

    Casdoor will store its users, nodes and topics information in a MySQL database named: casdoor, will create it if not existed. The DB connection string can be specified at: https://github.com/casbin/casdoor/blob/master/conf/app.conf

    driverName = mysql
    dataSourceName = root:123@tcp(localhost:3306)/
    dbName = casdoor
  • Setup database (Postgres):

    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=xxx sslmode=disable dbname="
    dbName = casdoor

    Please notice: You can add Postgres parameters in dataSourceName, but please make sure that dataSourceName ends with dbname=. Or database adapter may crash when you launch Casdoor.

  • Other database...

Run

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

Manully

According to actual needs, it is divided into dev mode and prod mode

Dev Environment

After completing the above simple configuration steps, you can run Casdoor. Casdoor has a front-end back-end separation architecture. The frontend uses javascript and React, backend uses beego and xorm.

Backend

You can start the backend server with this command,

go run main.go

After the server is successfully running on the specific port, then we can start the frontend part.

Frontend

Casdoor's package management tool uses npm and yarn, so you can choose any. Open a new terminal and run:

yarn install
yarn run start

Open your favorite browser and visit http://localhost:7001, you will see the login page of Casdoor.

Input admin and 123 to test login functionality is working fine.

Produnction Environment

Frontend

Build static pages:

yarn run build
Backend

We build the project and there will be an executable file casdoor, then we start the service:

go build && ./casdoor

Well done, next visit http://SERVER_IP:8000 in your favorite browser, if you can see login page of Casdoor, and you can login using admin and 123 as user and password, it means everything is ok!

tip

To customize the port, please edit the conf/app.conf file to set another port to set up Casdoor.

casdoor port details

In dev environment, the frontend is run by npm 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 npm 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.casbin.com, so users can signin or signup using Casdoor.

Casnode Example

Docker

  • Install Docker and Docker-compose, refer to docker and docker-compose

  • Edit conf/app.conf

  • Modify dataSourceName = root:123@tcp(localhost:3306)/ to dataSourceName = root:123@tcp(db:3306)/

  • Execute the following command

    docker-compose up
  • Open browser:

    http://localhost:8000/

    tip
    • MySQL and Casdoor server are in different docker containers.
    • After modifying conf/app.conf, re-execute docker-compose up

Some details

  • Github corner

    We added a Github icon in the upper right corner, linking to your Github repository address. You could set ShowGithubCorner to hidden it.

    Configuration:

    export const ShowGithubCorner = true

    export const GithubRepo = "https://github.com/casbin/casdoor" //your github repository
  • OSS conf

    We use an OSS to store and provide user avatars. You must modify the file conf/oss.conf to tell the backend your OSS info. For OSS providers, we support Aliyun([aliyun]), awss3([s3]) now.

    [provider]
    accessId = id
    accessKey = key
    bucket = bucket
    endpoint = endpoint

    Please fill out this conf correctly, or the avatar server won't work!

  • App conf

    conf/app.conf stores the important configuration of casdoor, which is very helpful for you to use Casdoor better.

    appname = casdoor
    httpport = 8000
    runmode = dev
    SessionOn = true
    copyrequestbody = true
    driverName = mysql
    dataSourceName = root:123@tcp(localhost:3306)/
    dbName = casdoor
    authState = "casdoor"
    useProxy = false
    verificationCodeTimeout = 10
    • 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 Config.
    • useProxy set the proxy port, because we have google-related services, which will be restricted by the network in some areas
    • verificationCodeTimeout set the expiration time of the verification code. After the expiration, the user needs to obtain it again
  • If casdoor needs to be publicly accessible(possess public IP), also need to modify web/src/auth/Auth.js:

    export let authConfig = {
    serverUrl: "http://example.com", // your Casdoor URL, like the official one: https://door.casbin.com, or http:1.1.1.1:8000
    ...
    }