Learn How To Install GitBucket on Ubuntu 16.04

April 6, 2020

Table of Contents

This guide covers the basic installation and setup of GitBucket for An ITWeb.Services instance running Ubuntu 16.04, and assumes that you are executing commands as a non-root user.


  • An ITWeb.Services server instance with at least 1GB of RAM (smaller instances may work, albeit slowly).
  • openjdk-8-jre Required, older versions will not work.
  • wget Used to download the GitBucket package.
  • nginx Optional, provides a reverse proxy to GitBucket
  • systemd Manages starting and stopping the GitBucket process

Installing prerequisites

GitBucket requires Java 8 or newer to be installed on your server. If you haven’t already installed Java 8, first update your local package lists.

sudo apt update

Then install the Java 8 runtime package.

sudo apt install openjdk-8-jre

Installing GitBucket

Creating a unprivileged user

We’ll need to create an unprivileged user to run GitBucket before going any further. Running GitBucket under an unprivileged user restricts our installation from writing outside its own data directory, strengthening the security of your server. Run the following command to create a system user called gitbucket.

sudo adduser --system gitbucket

Because we created a system user, the default shell is /bin/false, and we will be kicked back to our current shell unless we provide an additional shell argument when running su. Login to the newly created user.

sudo su - gitbucket -s /bin/bash

Your shell’s prompt should change, and you will be logged into the new system user.

Downloading/Updating GitBucket

Navigate to the GitBucket releases page and locate the latest available version. Copy the URL for the gitbucket.war package, verify you are in the new user’s home directory, and download it with wget.

cd ~/
wget https://github.com/gitbucket/gitbucket/releases/download/4.18.0/gitbucket.war

You will need to repeat this step each time you wish to update the GitBucket package.

Initial GitBucket configuration

Once the package has been downloaded, we will need to start GitBucket manually to perform some initial configuration.

java -jar gitbucket.war --port 8080

If the port 8080 is already taken by another process, you can change the port GitBucket will listen on now. This guide assumes throughout that GitBucket is listening on port 8080.

This will start GitBucket on your server’s public network interface, listening at the specified port. You should see, after a few moments, the following message.

INFO:oejs.Server:main: Started @15891ms

https://www.itweb.services/tutorials/linux-guides/itweb.services-firewall”>IT Web Services’s firewall, you will need to open the port GitBucket is listening on, as IT Web Services’s firewall works as a white-list, rejecting traffic to allow ports unless specified otherwise.

Your GitBucket installation should now be online and accessible from the internet. Using a web browser, connect to your server’s public address (being sure to specify the port GitBucket is running on, (i.e. or http://example.com:8080), and you will land at GitBucket’s homepage.

However, the password of the default administrator account needs to be changed. To do so, login to the administrator account through the Sign in button in the top-right of the web interface. The default login for the administrator account is root for the username, and then root again for the password. Once logged in, the button will be replaced with a profile icon and drop-down. Expand the drop-down and select Account Settings, then set a new, more secure password in the account settings wizard.

After you’ve updated the default administrator account’s credentials and verified that GitBucket starts in this minimal configuration, kill the Java process with “CTRL+C” and close the current shell with exit.

Creating the Systemd service

Currently, we can only run GitBucket by accessing our server through SSH and starting the process from a shell manually. Fortunately, Ubuntu comes prepackaged with Systemd, allowing us to create a service with which GitBucket will be auto-started and maintained by the system.

Using nano, create a new unit file in the /etc/systemd/system directory.

sudo nano /etc/systemd/system/gitbucket.service

Then, copy the following contents into the file.

ExecStart=/usr/bin/java -jar /home/gitbucket/gitbucket.war --port 8080
ExecStop=/bin/kill -SIGINT $MAINPID

This unit file defines basic startup and shutdown behavior for GitBucket, and runs the service under our unprivileged system user on the local-only network interface.

If you have changed the port number GitBucket will listen on, change the the --port argument for the ExecStart command.

Save (“CTRL+O“) the new unit file and then exit the editor (“CTRL+X“). You will need to reload Systemd for the new unit file to be discovered.

sudo systemctl daemon-reload

After Systemd has reloaded, verify that the new unit was discovered and loaded.

sudo systemctl status gitbucket

You should see the following output.

gitbucket.service - GitBucket
   Loaded: loaded (/etc/systemd/system/gitbucket.service; disabled; vendor preset: enabled)
   Active: inactive (dead)

Finally, enable the new unit to automatically start when your server boots, and then start the service for the first time.

sudo systemctl enable gitbucket
sudo systemctl start gitbucket

Once the service has started, you will be able to access GitBucket from your browser using the IP address and port number again.

Configuring Nginx reverse proxy

While one can expose GitBucket directly through port 8080, you can improve performance and configure features such as HTTP/2, TLS encryption, and caching rules by exposing GitBucket through Nginx.

Initial Nginx setup

If you haven’t already installed Nginx, update your package lists.

sudo apt update

Then install the Nginx package.

sudo apt install nginx

Once Nginx has been installed, verify you are able to access the web server through your server’s IP address without the port number (i.e. or http://example.com). If successful, you will see the default Nginx landing page for Ubuntu.

Creating the reverse proxy

We’ll be copying the default site configuration in /etc/nginx/sites-available as a starting point for the reverse proxy.

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/gitbucket

Open the newly created configuration file with nano.

sudo nano /etc/nginx/sites-available/gitbucket

Locate the existing location / block on line 43.

location / {
  # First attempt to serve request as file, then
  # as directory, then fall back to displaying a 404.
  try_files $uri $uri/ =404;

Currently, Nginx will attempt to return files located in /var/www/html which match incoming HTTP requests. We’ll need to change this behavior by configuring a reverse proxy in this block, which will send all HTTP requests made to our Nginx server to the GitBucket instance instead. Update the location / block to match the following.

location / {
    proxy_pass              http://localhost:8080; # The address GitBucket is listening on
    proxy_set_header        Host $host;
    proxy_set_header        X-Real-IP $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_connect_timeout   150;
    proxy_send_timeout      100;
    proxy_read_timeout      100;
    proxy_buffers           4 32k;
    client_max_body_size    512m; # Needed for large Git operations over HTTP
    client_body_buffer_size 128k;

If you changed the port number that GitBucket will listen on, update the proxy_pass option to reflect this.

To enable our new configuration, you will need to disable the existing default configuration in /etc/nginx/sites-enabled, then symlink our new configuration to /etc/nginx/sites-enabled through the following.

sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/gitbucket /etc/nginx/sites-enabled/gitbucket

Once the configuration file has been enabled, check for any syntax errors.

sudo nginx -t

Then, restart the Nginx server to enable our new site configuration.

sudo systemctl restart nginx

You should now be able to access your GitBucket installation on your server’s public address without a port number.

Securing the GitBucket process from the public internet

Currently, our GitBucket instance is listening on our server’s public network interface. This will allow users to bypass the Nginx proxy by connecting to the address that GitBucket is currently listening on, which is likely unwanted. We’ll need to modify the unit file we created earlier to resolve this. Open the unit file with nano.

sudo nano /etc/systemd/system/gitbucket.service

Append --host to the ExecStart command, like so.

ExecStart=/usr/bin/java -jar /home/gitbucket/gitbucket.war --port 8080 --host

This will cause GitBucket to only accept connections on our server’s local network interface. Once again, save (“CTRL+O“) the file, close (“CTRL+X“) the editor, reload Systemd, and restart our GitBucket unit.

sudo systemctl daemon-reload
sudo systemctl restart gitbucket

If you’re using IT Web Services’s Firewall, you should also remove any port rules you added to access the GitBucket server during the initial setup.

Need help?

Do you need help setting up this on your own service?
Please contact us and we’ll provide you the best possible quote!