Operating System Ubuntu

How to Install GitBucket on Ubuntu 24.04 LTS

Run GitBucket on Ubuntu 24.04 LTS with Java 17, a dedicated user, a systemd service and an Nginx reverse proxy, plus backup and upgrade steps.

GitBucket is a self-hosted Git platform written in Scala, with repositories, issues, pull requests and wikis, and an API compatible with GitHub's. It ships as a single gitbucket.war file that runs on Java. This guide installs it on Ubuntu 24.04 LTS (the same steps apply to 22.04) under its own system user, runs it as a systemd service bound to localhost, and publishes it through Nginx.

Older tutorials on this topic targeted Ubuntu 16.04 and Java 8. Ubuntu 16.04 is out of standard support, and current GitBucket releases require Java 17.

Requirements

  • An Ubuntu 24.04 or 22.04 server with at least 1 GB of RAM and a user with sudo rights.
  • A DNS name for the service. The examples use git.example.com.
  • Java 17. The GitBucket README states this as the requirement; step 1 installs it.

Step 1: Install Java 17

sudo apt update
sudo apt install -y openjdk-17-jre-headless wget

Check the version:

java -version

Step 2: Create a user and download GitBucket

Run GitBucket as an unprivileged system user so that it can write only to its own directory:

sudo useradd --system --create-home --home-dir /opt/gitbucket --shell /usr/sbin/nologin gitbucket

Open the GitBucket releases page and note the latest version number. At the time of writing that is 4.48.0. Download its gitbucket.war and create a data directory:

sudo -u gitbucket wget -O /opt/gitbucket/gitbucket.war https://github.com/gitbucket/gitbucket/releases/download/4.48.0/gitbucket.war
sudo -u gitbucket mkdir /opt/gitbucket/data

Step 3: Create the systemd service

GitBucket's embedded web server takes its settings as --name=value options. Note the equals sign: older tutorials write --port 8080 with a space, which the launcher does not parse. The options used here:

  • --host=127.0.0.1: listen on localhost only. Nginx will be the public entry point.
  • --port=8080: the default port; change it if something else uses 8080.
  • --gitbucket.home=/opt/gitbucket/data: where repositories, the database and settings are stored. Without it GitBucket uses .gitbucket in the user's home directory.

Create the unit file:

sudo nano /etc/systemd/system/gitbucket.service
[Unit]
Description=GitBucket
After=network.target

[Service]
Type=simple
User=gitbucket
WorkingDirectory=/opt/gitbucket
ExecStart=/usr/bin/java -jar /opt/gitbucket/gitbucket.war --host=127.0.0.1 --port=8080 --gitbucket.home=/opt/gitbucket/data
SuccessExitStatus=143
Restart=on-failure

[Install]
WantedBy=multi-user.target

SuccessExitStatus=143 tells systemd that the exit code a Java process returns when it is stopped with SIGTERM is a normal shutdown.

Load the unit, then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now gitbucket

The first start takes a little while because GitBucket creates its database. Check the service and the local port:

sudo systemctl status gitbucket
curl -I http://127.0.0.1:8080/

Step 4: Configure Nginx as a reverse proxy

Install Nginx:

sudo apt install -y nginx

Create a site configuration:

sudo nano /etc/nginx/sites-available/gitbucket
server {
    listen 80;
    server_name git.example.com;

    location / {
        proxy_pass              http://127.0.0.1:8080;
        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_set_header        X-Forwarded-Proto $scheme;
        proxy_connect_timeout   150;
        proxy_send_timeout      100;
        proxy_read_timeout      100;
        proxy_buffers           4 32k;
        client_max_body_size    500m;
    }
}

client_max_body_size is set high on purpose: a git push over HTTP sends its data as one request body, and Nginx's default limit of 1 MB rejects anything but tiny pushes.

Enable the site, test the configuration and reload:

sudo ln -s /etc/nginx/sites-available/gitbucket /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

If the UFW firewall is active, allow web traffic:

sudo ufw allow 'Nginx Full'

Step 5: Sign in and change the default password

Open http://git.example.com/ and sign in with the default administrator account: username root, password root. Change that password immediately under Account Settings in the menu behind your profile icon. Until you do, anyone who can reach the site has full administrative access.

Then open System Administration → System Settings and set the base URL to the public address of the site. GitBucket uses it for the clone URLs it displays and for links in notification emails; behind a reverse proxy it cannot work the address out reliably by itself. The same page controls whether visitors may create accounts and whether SSH access to repositories is enabled.

For anything beyond a test, add a TLS certificate to the Nginx server block, switch the base URL to https://, and only then give out clone URLs. Git credentials sent over plain HTTP can be read in transit.

Step 6: Verify with a test repository

Create a repository in the web interface, copy the HTTP clone URL shown on the repository page, and clone it from your workstation with git clone. Commit a file and push. If the push is accepted and the file appears in the web interface, the installation is complete.

Backups and upgrades

All GitBucket data lives in the home directory you set with --gitbucket.home. Copying that directory while the service is stopped is a complete backup:

sudo systemctl stop gitbucket
sudo tar -czf /root/gitbucket-data-$(date +%F).tar.gz -C /opt/gitbucket data
sudo systemctl start gitbucket

To upgrade, stop GitBucket, replace the .war file with the new release and start it again. Database migrations run on startup. Replace 4.48.0 with the version you are moving to:

sudo systemctl stop gitbucket
sudo -u gitbucket wget -O /opt/gitbucket/gitbucket.war https://github.com/gitbucket/gitbucket/releases/download/4.48.0/gitbucket.war
sudo systemctl start gitbucket

Read the release notes first and take the backup above. Two points from the project's README apply to older installations:

  • Versions 4.47.0 and 4.48.0 contain large database migrations on core tables, so a backup before upgrading is strongly recommended.
  • If you upgrade from 4.42 or earlier to 4.43 or later and use the default embedded H2 database, the database file must be exported and recreated by hand, because H2 1.x and 2.x files are not compatible. The README gives the exact commands.

Troubleshooting

  • The service fails to start: read the log with sudo journalctl -u gitbucket -e. An unsupported class version error means an older Java is being used; check java -version.
  • Port 8080 is already in use: change --port in the unit file and proxy_pass in the Nginx block to the same free port, then run sudo systemctl daemon-reload and restart both services.
  • Pushes fail with HTTP 413: the request is larger than client_max_body_size. Raise it and reload Nginx.
  • Clone URLs show 127.0.0.1:8080: the base URL is not set in System Settings.

Frequently asked questions

Can I run GitBucket in Tomcat instead of the built-in server?

Yes, with a caveat. The README says gitbucket.war can be deployed to a servlet container that supports Servlet 3.0, and that GitBucket does not support Jakarta EE yet. Containers that have moved to the Jakarta namespace, such as Tomcat 10 and later, are therefore not suitable. The standalone mode used in this guide avoids the question.

Which database does GitBucket use?

By default an embedded H2 database stored inside the GitBucket home directory, configured in database.conf there. That is enough for a small team and needs no separate database server. Check the project wiki for the external database options before choosing one for a larger installation.

Can I add features with plugins?

Yes. The project maintains official plugins for gists, emoji, pages and notifications, and the wiki lists community plugins. After a major upgrade, check that your plugins have releases for the new version; the 4.48.0 notes warn that authentication-related API changes may break some of them.

How much memory does GitBucket need?

It runs in a single Java process, and a 1 GB server is a workable minimum for a handful of users. If you host large repositories, give the server more RAM and, if needed, set a heap size by adding an option such as -Xmx1g after /usr/bin/java in the unit file.

Share story:

Continue reading other guides on How VPS.