Basic configurations - gitbucket/gitbucket GitHub Wiki

CLI options

The following options are available in the standalone mode (java -jar gitbucket.war):

  • --gitbucket.home=[DATA_DIR]
    • Data directory of this GitBucket instance (default is ~/.gitbucket).
  • --connectors=[HTTP,HTTPS] (since v4.37.0)
    • Comma separated list of connectors to activate, accepted values are http and https; case-insensitive, defaults to http.
  • --host=[HOSTNAME]
    • Host name in the standalone mode.
  • --port=[NUMBER]
    • Port number in the standalone mode (default is 8080).
  • --secure_port=[NUMBER] (since v4.37.0)
    • Port number to use with HTTPS; defaults to 8443.
  • --key_store_path=[KEY_STORE_PATH] (since v4.37.0)
    • Path to a supported key store (JKS, P12) used by the HTTPS connector.
  • --key_store_password=[KEY_STORE_PASSWORD] (since v4.37.0)
    • Password for the key store.
  • --key_manager_password=[KEY_MANAGER_PASSWORD] (since v4.37.0)
    • Password for the private key.
  • --redirect_https=[REDIRECT_HTTPS] (since v4.37.0)
    • Boolean, whether to redirect all HTTP request to the HTTPS handler; defaults to false.
  • --prefix=[CONTEXTPATH]
    • Context path in the standalone mode (default is /).
  • --temp_dir=[TEMP_DIR]
    • Used as the temporary directory for the jetty application context. This is the directory into which the gitbucket.war file is unpacked, the source files are compiled, etc. If given this parameter must match the path of an existing directory or the application will quit reporting an error; if not given the path used will be a tmp directory inside the gitbucket home.
  • --plugin_dir=[PLUGIN_DIR]
    • Extra directory for plugins. Mainly used for the plugin development (default is undefined).
  • --save_sessions (since v4.34.0)
    • Serialize HttpSession to the disk
  • --jetty_idle_timeout (since v4.38.0. default is 300000 = 5 min)
    • Idle timeout of the embedded Jetty HTTP server
  • --disable_cache (since v4.39.0)
    • Disable Git related caches (Use if you run GitBucket on multiple servers)
  • --disable_news_feed (since v4.39.0)
    • Disable News Feed (Use if you run GitBucket on multiple servers)

For example, you can specify the data directory as follows:

$ java -jar gitbucket.war --gitbucket.home=/data/gitbucket

Most of these options can be given via environment variables or system properties. Environment variables are convenient for configuring GitBucket when you run it in a docker container.

CLI options Environment variable System property
--gitbucket.home GITBUCKET_HOME gitbucket.home
--connectors GITBUCKET_CONNECTORS -
--host GITBUCKET_HOST -
--port GITBUCKET_PORT -
--secure_port GITBUCKET_SECUREPORT -
--key_store_path GITBUCKET_KEYSTOREPATH -
--key_store_password GITBUCKET_KEYSTOREPASSWORD -
--key_manager_password GITBUCKET_KEYMANAGERPASSWORD -
--redirect_https GITBUCKET_REDIRECTHTTPS -
--prefix GITBUCKET_PREFIX -
--temp_dir GITBUCKET_TEMPDIR gitbucket.tempDir
--plugin_dir GITBUCKET_PLUGINDIR gitbucket.pluginDir
--jetty_idle_timeout GITBUCKET_JETTYIDLETIMEOUT -
--disable_cache. GITBUCKET_DISABLECACHE. gitbucket.disableCache 
# System property
$ java -Dgitbucket.home=/data/gitbucket -jar gitbucket.war

# Environmnet variable
$ export GITBUCKET_HOME=/data/gitbucket
$ java -jar gitbucket.war

Overwrite configuration

Normally, GitBucket configuration which is modified by administrators at the admin page is saved to GITBUCKET_HOME/gitbucket.conf and you need to edit GITBUCKET_HOME/database.conf to configure an external database. All configuration items of these files can be given as system properties or environment variables. In particular, it's useful when running GitBucket in a docker container.

For example, you can run GitBucket with a specified database as follows:

$ java -Dgitbucket.db.url=jdbc:postgresql://localhost/gitbucket \
       -Dgitbucket.db.user=test \
       -Dgitbucket.db.password=test \
       -jar gitbucket.war

While system properties are used in the above example, environment variables can be used instead:

$ export GITBUCKET_DB_URL=jdbc:postgresql://localhost/gitbucket
$ export GITBUCKET_DB_USER=test
$ export GITBUCKET_DB_PASSWORD=test
$ java -jar gitbucket.war

Another example is giving a base url which is normally configured in gitbucket.conf as a system property:

$ java -Dgitbucket.base_url=http://localhost:8080 -jar gitbucket.war

Or as an environment variable:

$ export GITBUCKET_BASE_URL=http://localhost:8080
$ java -jar gitbucket.war

GitBucket looks for each configuration item in the following order:

  1. System property
  2. Environment variable
  3. Configuration file

So you can overwrite specific configuration items by specifying system properties or defining environment variables.