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

1. 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

2. 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

3. 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:

1. 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

2. 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.

1. 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

2. 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

3. 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

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

Supported objects

The init data file can contain the following objects:

Об'єкт	Go Struct	Документація
організації	struct	doc
додатки	struct	doc
користувачі	struct	doc
сертифікати	struct	doc
провайдери	struct	doc
ldaps	struct	документація
моделі	struct
дозволи	struct	документація
платежі	struct	документація
продукти	struct	документація
ресурси	struct	документація
ролі	struct	документація
синхронізатори	struct	документація
токени	struct	документація
вебхуки	struct	документація
групи	struct	документація
адаптери	struct	документація
примусові виконавці	struct
плани	struct	doc
ціноутворення	struct	документація
запрошення	struct	документація
записи	struct
сесії	struct
підписки	struct	документація
транзакції	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.

See also

• Configuration reference
• Terraform provider
• Run Casdoor on Kubernetes with Helm