This guide covers the basic installation and setup of GitBucket for a Vultr instance running Ubuntu 16.04, and assumes that you are executing commands as a non-root user.
Prerequisites
- A Vultr server instance with at least 1GB of RAM (smaller instances may work, albeit slowly).
openjdk-8-jreRequired, older versions will not work.wgetUsed to download the GitBucket package.nginxOptional, provides a reverse proxy to GitBucketsystemdManages 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
If you’re using Vultr’s firewall, you will need to open the port GitBucket is listening on, as Vultr’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. http://203.0.113.0:8080 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.
[Unit]
Description=GitBucket
After=network.target
[Service]
ExecStart=/usr/bin/java -jar /home/gitbucket/gitbucket.war --port 8080
ExecStop=/bin/kill -SIGINT $MAINPID
Type=simple
User=gitbucket
[Install]
WantedBy=multi-user.target
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. http://203.0.113.0 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 127.0.0.1 to the ExecStart command, like so.
...
ExecStart=/usr/bin/java -jar /home/gitbucket/gitbucket.war --port 8080 --host 127.0.0.1
...
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 Vultr’s Firewall, you should also remove any port rules you added to access the GitBucket server during the initial setup.
Want to contribute?
You could earn up to $300 by adding new articles
Suggest an update
Request an article
