Source: https://dev-docs.nebula-graph.io/v5.3.2/visualization/studio/configs/
Documentation version: v5.3.2

# NebulaGraph Studio configurations

Configure NebulaGraph Studio with the settings below.

Note

If you modified the configuration file after NebulaGraph Studio is started, you need to restart NebulaGraph Studio for the changes to take effect.

## Default configuration file

The configuration file location depends on the installation method:

- TAR package: `etc/config.yaml` in the extracted directory.
- RPM or DEB package: `/etc/nebula-studio/config.yaml`.
- Docker Compose: the image uses its built-in configuration by default, so you do not need to prepare a file. To customize it, follow the Customize the configuration steps in [Install NebulaGraph Studio](https://dev-docs.nebula-graph.io/v5.3.2/visualization/studio/install/) to mount `config-release.yaml` at `/app/etc/config-release.yaml`. After editing the mounted file, run `docker compose -f studio-compose.yaml restart studio` in the deployment directory.

RPM and DEB packages use these additional paths. See the [Linux package guide](https://github.com/vesoft-inc/nebula-ng-studio/blob/main/deploy/linux-packages.md):

 | Content | Path
 | Application files | `/usr/lib/nebula-studio`
 | Optional environment file | `/etc/nebula-studio/studio.env`
 | SQLite database | `/var/lib/nebula-studio/studio.db`
 | Application logs | `/var/log/nebula-studio`

The following example shows the configuration options. For RPM and DEB packages, use the installed `/etc/nebula-studio/config.yaml` as your starting point. In particular, do not replace its SQLite path with the example's relative path `./data/studio.db`.

````
Name: studio-api
Host: 0.0.0.0
Port: 7001
Timeout: 30000
DefaultHost: '' # Optional default database address shown on the login page
DefaultPort: '' # Optional default database port shown on the login page
Log:
  Mode: file
  Level: info
  KeepDays: 7
Assets:
  Gzip: true
Auth:
  TokenName: 'studio_token'
  TokenSecret: '${STUDIO_TOKEN_SECRET}'
  TokenMaxAge: 86400
  EncryptPassphrase: '${STUDIO_ENCRYPT_PASSPHRASE}'

SSO:
  Oauth2:
    Enable: false
    ServerName: ''
    AuthURL: ''
    AccessTokenURL: ''
    ClientID: ''
    ClientSecret: ''
    RedirectURL: ''
    UserInfoURL: ''
    Scope: 'openid profile email'
    UsernameField: '' # Empty uses the built-in fallback order

Database:
  Enable: true
  Dialect: sqlite3
  AutoMigrate: true
  Host: 127.0.0.1
  Port: 3306
  Username: '' # Required only for MySQL
  Password: '' # Required only for MySQL; inject through deployment-owned configuration
  Name: studio
  LogLevel: 4
  SqliteFilePath: './data/studio.db'
Nebula:
  ClientMaxNum: 200
  ClientPoolMaxWait: 10 # Maximum wait time for the client connection pool, in seconds
  ClientPoolConnsMaxOpen: 100
  ClientPoolConnsMinOpen: 1
  ClientMaxIdleConns: 5
  ClientExpiredDuration: 14400
  ClientRequestTimeout: 10

````

## Authentication secrets

The example supports authentication secrets from the `STUDIO_TOKEN_SECRET` and `STUDIO_ENCRYPT_PASSPHRASE` environment variables. NebulaGraph Studio recognizes these variable names; you choose their values for your deployment. You can leave them unset for the default deployment.

When these values are not configured, the service generates random values. With randomly generated values, restarting the service invalidates existing sessions and users must log in again. For production deployments, configure stable secrets and retain them across restarts. Use separate secrets for different deployments.

When set, `STUDIO_ENCRYPT_PASSPHRASE` must be 16, 24, or 32 bytes long.

## Configuration options

The following table describes the configuration options of NebulaGraph Studio:

 | Option | Description | Default value
 | `Name` | The name of the service, which appears in logs and tracers. | `studio-api`
 | `Host` | The listening address used to access NebulaGraph Studio. | `0.0.0.0`, which means that all network interfaces are listened on.
 | `Port` | The listening port used to access NebulaGraph Studio. | `7001`
 | `Timeout` | The timeout duration for processing requests in milliseconds. | `30000`
 | `DefaultHost` | Optional default NebulaGraph Database Developer Edition address shown on the login page, for example `graph0`. | `""`
 | `DefaultPort` | Optional default NebulaGraph Database Developer Edition port shown on the login page, for example `9669`. | `""`
 | `Log.Mode` | The log output mode. | `file`, which writes logs to a file. For TAR packages, logs are under `logs` in the extracted directory; for RPM and DEB packages, logs are in `/var/log/nebula-studio`. Docker Compose does not mount a log directory on the machine running Docker by default; configure persistent storage if you need to keep file logs.
 | `Log.Level` | The log level. For more information, see [Log configuration](https://go-zero.dev/reference/configuration/log/#definition-of-parameters). | `info`, which means that records with the level of `info` and higher are logged.
 | `Log.KeepDays` | The number of days that logs are retained. | `7`
 | `Assets.Gzip` | Whether to enable Gzip compression for static assets. | `true`
 | `Auth.TokenName` | The name of the authentication token used for login. | `studio_token`
 | `Auth.EncryptPassphrase` | The AES passphrase used to encrypt authentication information. Set it through `STUDIO_ENCRYPT_PASSPHRASE`; when set, it must be 16, 24, or 32 bytes long. | Randomly generated when unset
 | `Auth.TokenSecret` | The secret used to sign authentication tokens. Set it through the `STUDIO_TOKEN_SECRET` environment variable. | Randomly generated when unset
 | `Auth.TokenMaxAge` | The validity period of the authentication token in seconds. | `86400`
 | `Database.Enable` | Whether to enable the metadata database for NebulaGraph Studio. Graph exploration depends on this database. When disabled, requests for exploration snapshots, settings, and related features fail with `studio database is disabled`. | `true`
 | `Database.Dialect` | The database type used to store the metadata of NebulaGraph Studio. Valid values are `mysql` and `sqlite3`. | `sqlite3`
 | `Database.AutoMigrate` | Whether to automatically migrate the database schema. | `true`
 | `Database.Host` | The database address. | `127.0.0.1`
 | `Database.Port` | The port number of the database. | `3306`
 | `Database.Username` | The database username. Required only for MySQL. | `""`
 | `Database.Password` | The database password. Required only for MySQL; inject it through deployment-owned configuration. | `""`
 | `Database.Name` | The name of the database. | `studio`
 | `Database.LogLevel` | The log level for database operations. Valid values are `1` (silent), `2` (error), `3` (warn), and `4` (info). | `4`
 | `Database.SqliteFilePath` | The file path of the SQLite database. This option takes effect only when `Database.Dialect` is set to `sqlite3`. | TAR package and Docker image: `./data/studio.db`; RPM and DEB packages: `/var/lib/nebula-studio/studio.db`.
 | `Nebula.ClientMaxNum` | The maximum number of users that can be simultaneously connected to the service. | `200`
 | `Nebula.ClientPoolMaxWait` | The maximum wait time for the client connection pool, in seconds. | `10`
 | `Nebula.ClientPoolConnsMaxOpen` | The maximum number of connections that can be created in a single connection pool. | `100`
 | `Nebula.ClientPoolConnsMinOpen` | The minimum number of connections that can be created in a single connection pool. | `1`
 | `Nebula.ClientMaxIdleConns` | The maximum number of idle connections in a single connection pool. | `5`
 | `Nebula.ClientExpiredDuration` | The duration in minutes after which an idle connection expires. If a client remains idle for the specified duration, the connection is automatically terminated. The system checks the expiration status of connections every 24 hours. | `14400`
 | `Nebula.ClientRequestTimeout` | The timeout of client connections in seconds. | `10`
 | `SSO.Oauth2.Enable` | Whether to enable OAuth2 SSO. | `false`
 | `SSO.Oauth2.ServerName` | OAuth2 server name, must match the server configured in NebulaGraph Database Developer Edition. | `""`
 | `SSO.Oauth2.AuthURL` | OAuth2 authorization URL. | `""`
 | `SSO.Oauth2.AccessTokenURL` | OAuth2 token exchange URL. | `""`
 | `SSO.Oauth2.ClientID` | OAuth2 client ID. | `""`
 | `SSO.Oauth2.ClientSecret` | OAuth2 client secret. | `""`
 | `SSO.Oauth2.RedirectURL` | Externally reachable NebulaGraph Studio callback URL after OAuth2 authorization. | `""`
 | `SSO.Oauth2.UserInfoURL` | OIDC UserInfo endpoint to get the username. | `""`
 | `SSO.Oauth2.Scope` | OAuth2 scopes to request. | `"openid profile email"`
 | `SSO.Oauth2.UsernameField` | Field to extract username from UserInfo response. When empty, uses the built-in fallback order: `preferred_username` > `username` > `login` > `email` > `sub`. | `""`