title: "GitBucket Setup and Configuration Guide" date: "2025-07-27" updated: "2025-07-27" slug: "setup-gitbucket" published: true layout: "blog-post" tags:

• git
• programming
• coding
• development
• productivity
• tools
• ssh
• database
• mysql
• postgresql
• dns
• server-setup
• java

• war-file

Download the GitBucket WAR File

Download the latest GitBucket WAR file.
Verify the checksum or signature before use when available to ensure the file has not been tampered with.

Running the GitBucket WAR File

You can run GitBucket directly with the Java runtime:

java -jar gitbucket.war

Alternatively, deploy the WAR file to a servlet container (e.g., Tomcat) for integration with existing infrastructure.
Startup may display logging-related warnings (e.g., missing config files or logback fallback notices); these are non-fatal.
Use journalctl or your container logs to monitor the service:

journalctl -u gitbucket -f

Logging and Troubleshooting

System logs provide the most reliable source of error context:

sudo systemctl status gitbucket
journalctl -u gitbucket -f

If GitBucket fails to start or returns generic HTTP errors, check the underlying database logs and JVM output.
Enable debug logging in the GitBucket configuration if you need detailed stack traces.

Configuring GitBucket for Production Use

The default embedded H2 database is not persistent or scalable. For production use:

1. Set up MySQL or PostgreSQL.
2. Configure GitBucket with JDBC connection parameters.

Example for PostgreSQL:

GITBUCKET_HOME=/opt/gitbucket
cat > $GITBUCKET_HOME/database.conf <<EOF
db.url=jdbc:postgresql://localhost:5432/gitbucket
db.user=gitbucket_user
db.password=secure_password
EOF

Ensure the target database exists and credentials are valid.

Database Error Diagnosis

GitBucket will display HTTP 500 errors for most database issues, masking the actual cause.
Inspect the database server logs directly:

# MySQL
sudo tail -f /var/log/mysql/error.log

# PostgreSQL
sudo tail -f /var/log/postgresql/postgresql-*.log

Check for authentication failures, permission denials, invalid schema references, or dropped connections.
Also validate firewall rules and SELinux/AppArmor settings if applicable.

SSH Configuration for GitBucket

GitBucket supports SSH-based Git operations.
Avoid port 22 for GitBucket’s SSH due to system constraints or shared services. Use an unprivileged high-numbered port like 29418.
Redirect standard port 22 to 29418 to maintain client compatibility:

iptables -t nat -A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 29418
iptables -A INPUT -p tcp --dport 29418 -j ACCEPT

Persist firewall rules:

sudo iptables-save > /etc/iptables/rules.v4

Ensure the GitBucket instance listens on the specified SSH port. Configure this in gitbucket.conf:

gitbucket.ssh.port=29418

Restart the service after applying changes.

Network and DNS Setup

If GitBucket is hosted on a VPN, container, or isolated interface, assign a static IP:

ip addr add 10.8.0.2/24 dev tun0

Update your DNS server or /etc/hosts to resolve a proper hostname:

gitbucket.example.com. IN A 10.8.0.2

DNS is essential for:

• Hostname-based Git operations
• SSL certificate issuance
• API and webhook consistency
• Integrations with CI/CD or other tools

Allow for DNS propagation delays before testing public access.

Generating and Adding SSH Keys in GitBucket

To authenticate via SSH:

1. Generate a key pair on the client machine:

ssh-keygen -t rsa -b 4096 -C "user@example.com"

1. Copy the public key:

cat ~/.ssh/id_rsa.pub

1. Log into GitBucket.
2. Navigate to User Settings > SSH Keys.
3. Paste and save the public key.

Ensure:

• The SSH daemon is configured to accept the port used by GitBucket.
• GitBucket's internal SSH service is running and correctly mapped to that port.
• No firewall or SELinux rule is blocking the custom port.

Test with:

ssh -T -p 29418 git@gitbucket.example.com

Summary of Critical Points

• Always use MySQL or PostgreSQL in production; H2 is not durable or scalable.
• Check systemd and database logs for all unexplained HTTP errors.
• Use a non-privileged SSH port and port-forward 22 if compatibility is needed.
• Set a dedicated static IP and configure DNS with proper hostname resolution.
• Upload SSH public keys into GitBucket UI for access control.
• Validate and test each component (JVM, database, SSH, firewall) independently before final deployment.