Deploy GitBucket

Deploy and Host GitBucket on Railway

GitBucket is an open-source Git platform written in Scala that gives a team its own GitHub: repositories over HTTP and SSH, issues, pull requests with inline review, wikis, releases and a GitHub-compatible REST API. Because that API mirrors GitHub's own /api/v3 surface, tools that already speak GitHub usually need only a base-URL change. Teams pick it for private code hosting they control, with no per-seat cost.

Deploy GitBucket on Railway and this template wires the two pieces it needs together. The gitbucket service runs the application on a JVM behind a public HTTPS domain and keeps repositories, GitLFS objects, plugins and its SSH host key on a persistent 5 GB volume. The Postgres service stores accounts, issues, pull requests and system settings, reachable only over Railway's private network. A TCP proxy publishes GitBucket's SSH daemon, so git push works over SSH as well as HTTPS. The administrator password is generated at deploy time, so the instance is never reachable with the credentials GitBucket ships.

Getting Started with GitBucket on Railway

Open the generated Railway domain and you land on the sign-in page. Sign in as root with the value of GITBUCKET_ADMIN_PASSWORD, which you can read from the gitbucket service's Variables tab. Your first action is the + menu top right: create a repository, tick the add-a-README option, and the viewer opens on a real commit. Add colleagues under Manage Users — self-service registration is off by default, and System settings turns it on.

To push existing work, copy the HTTPS clone URL and authenticate with your GitBucket username and password. For SSH, paste a public key into Account settings → SSH Keys and use the ssh://git@… URL from the same dropdown; the Railway proxy host and port are already filled in. The deployment is working once a push lands and its commit appears in the viewer. Review one setting early: System settings → Anonymous access is on, matching GitBucket's default, so public repositories are readable without an account. Turn it off for a fully private instance.

About Hosting GitBucket

GitBucket ships as one gitbucket.war file. That simplicity is the point: no worker tier, no queue, no cache, no object storage. Relational data goes to a database and Git data to disk, which makes it cheap to run and easy to back up. Self-hosting suits a team wanting private repositories with issue tracking, code that cannot leave its own infrastructure, or a GitHub-shaped API to build against.

Key features:

• Public and private repositories, over HTTP, HTTPS and SSH
• Issues, labels, priorities, milestones and pull requests with inline comments
• Per-repository wiki, releases, file attachments and GitLFS
• Accounts and groups, with optional LDAP or OpenID Connect sign-in
• A plugin system; Gist, Emoji, Notifications and Pages ship bundled
• A GitHub-compatible REST API under /api/v3

The architecture is small. gitbucket is the whole application — web UI, API, Git server and SSH daemon in one process. Postgres is the system of record for everything that is not a Git object. The volume at /gitbucket holds the bare repositories, so snapshot it before an upgrade.

Why Deploy GitBucket on Railway

Railway removes the parts of self-hosting a Git server that are not about Git:

• Managed PostgreSQL, provisioned and connected for you
• A persistent volume that survives every redeploy
• HTTPS on a generated or custom domain
• A TCP proxy publishing the SSH daemon and nothing else
• Private networking between app and database
• Redeploy on push, with logs and metrics in one place

Common Use Cases

• Private team code hosting — repositories with issues and pull-request review, no per-seat cost.
• A GitHub-compatible API to build against — test integrations without spending github.com rate limit.
• An internal mirror for regulated work — source that stays on your infrastructure, with LDAP or OIDC sign-in.
• A lighter alternative to a full forge — for teams that do not want to run GitLab.

Dependencies for GitBucket

• ghcr.io/gitbucket/gitbucket:latest — the application, on Eclipse Temurin 17. The Docker Hub copy has not been rebuilt since 2022; this GHCR image is the current one.
• ghcr.io/railwayapp-templates/postgres-ssl:18 — PostgreSQL 18, storing accounts, issues, pull requests and settings.

Environment Variables Reference

Deployment Dependencies

• Source repository: https://github.com/gitbucket/gitbucket
• Deployment image source: https://github.com/gridalpha/gitbucket-railway
• Documentation and wiki: https://github.com/gitbucket/gitbucket/wiki

Hardware Requirements for Self-Hosting GitBucket

The JVM sizes its heap from the container's memory limit, so more RAM means a bigger heap with no configuration change. Storage is the number to watch: the volume holds every repository and GitLFS object.

Self-Hosting GitBucket

The simplest local run needs Java 17 and the release JAR — a shell session:

curl -LO https://github.com/gitbucket/gitbucket/releases/latest/download/gitbucket.war
java -jar gitbucket.war --port=8080

That uses an embedded H2 database in ~/.gitbucket — fine for a trial, not for a team. To self-host GitBucket properly, point it at PostgreSQL and give it a data volume, as docker run:

docker run -d --name gitbucket \
  -p 8080:8080 -p 29418:29418 \
  -v gitbucket-data:/gitbucket \
  -e GITBUCKET_HOME=/gitbucket \
  -e GITBUCKET_DB_URL="jdbc:postgresql://db:5432/gitbucket" \
  -e GITBUCKET_DB_USER=gitbucket \
  -e GITBUCKET_DB_PASSWORD=change-me \
  ghcr.io/gitbucket/gitbucket:latest

Port 8080 serves the web UI, the REST API and Git over HTTP; 29418 is the SSH daemon. On your own hardware you would add a TLS-terminating proxy in front, which this template already does.

How Much Does GitBucket Cost to Self-Host?

GitBucket is free and open source under the Apache License 2.0 — no paid edition, no seat limit, no feature gating. Self-hosting on Railway costs only infrastructure: the container, the PostgreSQL instance and the volume your repositories occupy. For a small team that is a few dollars a month, and it does not grow as you add engineers.

GitBucket vs Gitea

Choose GitBucket for GitHub API compatibility and a GitHub-shaped UI; choose Gitea when footprint or built-in CI decides it.

FAQ

What is GitBucket? An open-source Git web platform in Scala: repositories, issues, pull requests, wikis and a GitHub-compatible REST API in one Java web application.

What does this Railway template deploy? Two services: gitbucket, with a public HTTPS domain, a TCP proxy for SSH and a 5 GB volume at /gitbucket; and Postgres, managed PostgreSQL 18 on the private network.

Why does the template include a PostgreSQL database? GitBucket defaults to an embedded H2 file database, which is not safe for a container recreated on every deploy. PostgreSQL keeps accounts, issues and pull requests in a managed store with its own backups.

How do I sign in the first time? Username root, password the value of GITBUCKET_ADMIN_PASSWORD in the service's Variables tab. The root/root credential GitBucket ships is replaced before the instance answers a public request.

How do I clone over SSH from self-hosted GitBucket? Add your public key under Account settings → SSH Keys, then use the ssh://git@… URL in the clone dropdown. It already points at the Railway TCP proxy host and port.

Can I run more than one replica of GitBucket? No. It writes repositories directly to its data directory and a Railway volume attaches to one instance, so keep one replica and scale vertically.

How do I back up a self-hosted GitBucket instance? Take a PostgreSQL dump and copy the /gitbucket volume. Both are needed; either alone is incomplete.