Initialize and manage data with a file

This guide explains how to load data into Casdoor from a JSON or YAML file, how to let Casdoor keep its objects in sync with that file, and how to export the data of a running instance.

Learning outcomes

Load organizations, applications, users, and other objects when Casdoor starts.
Keep Casdoor objects in a file in Git and apply changes without a restart.
Export the data of an instance and load it into another instance.

What you need

A Casdoor instance and access to its conf/app.conf or its environment variables
For the Kubernetes sections: kubectl access to the cluster, or the Helm chart

About the init data file

When you ship Casdoor as part of a larger product, you can preload organizations, applications, users, and other objects, so that the product works without manual setup. Casdoor reads these objects from one file, the init data file.

The file serves two purposes:

Initialization: Casdoor loads the file once, when it starts.
Configuration as code: Casdoor watches the file and applies every change while it runs. See Manage configuration as code.

A template is available at init_data.json.template. A file that ends in .yaml or .yml is read as YAML with the same structure.

Load data at startup

Copy init_data.json.template to init_data.json in the directory that Casdoor runs in, and edit it.

To keep the file somewhere else, set initDataFile in conf/app.conf:
```
initDataFile = /path/to/your/init_data.json
```

Choose what happens to objects that already exist. Set at most one of the following options in conf/app.conf:

Option	Objects that already exist
Neither option (default)	Deleted and created again from the file at every start. Changes made in the admin console are lost on restart
`initDataNewOnly = true`	Left as they are. Casdoor only adds objects that don't exist yet
`initDataMerge = true`	Updated with only the fields that the file contains. See Manage configuration as code

Start Casdoor.

Load the file in Docker

Mount the file into the container:

docker run ... -v /path/to/init_data.json:/init_data.json

Load the file in Kubernetes

With the Helm chart, put the objects under initData.data in your values file and set initData.enabled: true. See Manage configuration as code.

Without the chart:

Store the file in a Secret, because it usually holds passwords and client secrets. A ConfigMap also works.

apiVersion: v1
kind: Secret
metadata:
  name: casdoor-init-data
stringData:
  init_data.yaml: |
    organizations:
      - owner: admin
        name: acme
        displayName: Acme

Mount the Secret as a directory and point initDataFile to the file in it:

apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    ...
    spec:
      containers:
      ...
        env:
        - name: initDataFile
          value: /init-data/init_data.yaml
        - name: initDataMerge
          value: "true"
        - name: initDataWatchInterval
          value: "30"
        volumeMounts:
        - mountPath: /init-data
          name: casdoor-init-data-volume
          readOnly: true
      volumes:
      - secret:
          secretName: casdoor-init-data
        name: casdoor-init-data-volume

注意事项

Don't mount the file with subPath. Kubernetes doesn't update a subPath mount when the Secret or ConfigMap changes, so Casdoor never sees the new content.

Manage configuration as code

To keep organizations, applications, users, providers, roles, and permissions in Git and roll out changes like any other configuration, let Casdoor apply the file continuously.

Set the following options in conf/app.conf, or pass them as environment variables with the same names:
```
initDataFile = ./init_data.yaml
initDataMerge = true
initDataWatchInterval = 30
```

Write the objects in the file. For example, init_data.yaml:

organizations:
  - owner: admin
    name: acme
    displayName: Acme
    passwordType: bcrypt
applications:
  - owner: admin
    name: app-acme
    organization: acme
    displayName: Acme Portal
    redirectUris:
      - https://portal.acme.example.com/callback
users:
  - owner: acme
    name: alice
    displayName: Alice
    password: change-me
    signupApplication: app-acme
roles:
  - owner: acme
    name: admins
    displayName: Admins
    users: [acme/alice]
    isEnabled: true

Start Casdoor. From now on, Casdoor applies the file again whenever its content changes.

With the Helm chart, put the same objects under initData.data. The chart stores them in a Secret and turns on merge and watch by default:

initData:
  enabled: true
  data:
    organizations:
      - owner: admin
        name: acme
        displayName: Acme

The running pods apply a helm upgrade that changes initData.data within initData.watchInterval seconds, plus the time that the kubelet needs to update the mounted Secret, which is about a minute.

How Casdoor applies the file

Behavior	Description
Merge	Casdoor updates an existing object with only the fields that the file contains. The other fields keep their values. The file can therefore manage a few settings of an object, such as the redirect URLs of an application, while you edit the rest in the admin console
Watch	Casdoor checks the file every `initDataWatchInterval` seconds and applies it again when the content has changed, without a restart
Passwords	Casdoor uses the `password` of a user only when it creates the user, so users can change their passwords afterward. Casdoor writes organization secrets, such as `masterPassword`, on every apply when the file contains them
Removed objects	Casdoor doesn't delete objects that you remove from the file
Runtime data	Casdoor skips `records` and `sessions` in merge mode
Errors	If an object fails to apply, Casdoor logs the error once and keeps running with the objects that it applied up to that point. It retries the file on every check until the file applies

提示

If you prefer terraform plan, import of existing objects, and drift detection, use the Terraform provider. It manages the same objects through the API.

Export data

Export all data of a Casdoor instance to a JSON file for a backup or a migration.

Export with the binary

Run Casdoor with the -export flag. This is the recommended way. It works with the binary, in Docker, and in Kubernetes, and it doesn't need the Go toolchain.

# Export to default location (init_data_dump.json)
./casdoor -export

# Export to a custom path
./casdoor -export -exportPath /path/to/backup.json

Casdoor initializes the database connection, writes the file, and exits.

Export from source

In the Casdoor source tree, run:

go test ./object -v -run TestDumpToFile

The command creates init_data_dump.json in the object directory.

Load the export into another instance

Rename init_data_dump.json to init_data.json.
Put the file in the directory that the target Casdoor instance runs in.
Start the target instance. It loads the data at startup.

支持的对象

The init data file can contain the following objects:

对象	Go 结构体	文档
组织机构	struct	doc
应用	struct	doc
用户	struct	doc
证书	struct	doc
提供商	struct	doc
ldaps	struct	文档
模型	结构体
权限	结构体	文档
支付	结构体	文档
产品	结构体	文档
资源	结构体	文档
角色	结构体	文档
同步器	结构体	文档
令牌	结构体	文档
webhooks	结构体	文档
组	结构体	文档
适配器	结构体	文档
	结构体
计划	struct	doc
	struct	文档
邀请	结构体	文档
记录	结构体
sessions	struct
subscriptions	结构体	文档
transactions	struct

The JSON shape of each object is the shape that the REST API returns. To see an example, call the corresponding get- endpoint or inspect the responses in the browser while you use the admin console.

Learning outcomes​

What you need​

About the init data file​

Load data at startup​

Load the file in Docker​

Load the file in Kubernetes​

Manage configuration as code​

How Casdoor applies the file​

Export data​

Export with the binary​

Export from source​

Load the export into another instance​

支持的对象​

See also​