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
sudorights. - 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 wgetCheck the version:
java -versionStep 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 gitbucketOpen 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/dataStep 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.gitbucketin 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.targetSuccessExitStatus=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 gitbucketThe 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 nginxCreate a site configuration:
sudo nano /etc/nginx/sites-available/gitbucketserver {
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 nginxIf 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 gitbucketTo 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 gitbucketRead 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; checkjava -version. - Port 8080 is already in use: change
--portin the unit file andproxy_passin the Nginx block to the same free port, then runsudo systemctl daemon-reloadand 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.