Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

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

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