---
title: "Deploy GitBucket"
description: "Git hosting with issues, pull requests and a GitHub-compatible API"
category: "Other"
url: https://railway.com/deploy/gitbucket
---

# Deploy GitBucket

Git hosting with issues, pull requests and a GitHub-compatible API

**[Deploy GitBucket on Railway](https://railway.com/template/gitbucket)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/gitbucket/manifest.json

- **Creator:** A3A
- **Category:** Other
- **Total deploys:** 1

## Template content

### gitbucket https://raw.githubusercontent.com/gridalpha/gitbucket-railway/main/logo.svg

- **Source:** https://github.com/gridalpha/gitbucket-railway
- **Health check:** /signin
- **Public domain:** Yes

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# 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.

![GitBucket and Postgres services on Railway, each with a volume](https://res.cloudinary.com/rroe4rtk/image/upload/v1788985800/gitbucket-architecture.png)

## 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.

![GitBucket repository viewer showing a rendered README and file tree](https://res.cloudinary.com/rroe4rtk/image/upload/v1788985802/gitbucket-repository-viewer.png)
![Syntax-highlighted Python source file in the GitBucket code browser](https://res.cloudinary.com/rroe4rtk/image/upload/v1788985804/gitbucket-source-file.png)
![An open GitBucket issue with its description and comment box](https://res.cloudinary.com/rroe4rtk/image/upload/v1788985806/gitbucket-issue.png)

## 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

| Variable | Purpose |
|---|---|
| `GITBUCKET_ADMIN_PASSWORD` | Password for the built-in `root` administrator, applied on the first boot only |
| `GITBUCKET_HOME` | Data directory; must match the volume mount, `/gitbucket` |
| `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD` | PostgreSQL connection, referenced from the database service |
| `PORT` | Port the web UI and Git-over-HTTP endpoint listen on |
| `GITBUCKET_BASE_URL` | Public URL; set it only for a custom domain |
| `GITBUCKET_DB_URL`, `GITBUCKET_DB_USER`, `GITBUCKET_DB_PASSWORD` | Set all three to use your own database |

### 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

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2 vCPU |
| RAM | 1 GB | 2 GB |
| Storage | 5 GB volume | 20 GB or more, sized to your repositories |
| Runtime | Java 17 | Java 17 |

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

| | GitBucket | Gitea |
|---|---|---|
| Runtime | Java 17 (JVM) | Single Go binary |
| Memory footprint | ~1 GB | ~256 MB |
| API | GitHub `/api/v3` compatible | Own API, GitHub-compatible subset |
| Extensibility | Plugin system with a registry | Webhooks and integrations |
| Built-in CI | No | Gitea Actions |

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.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/gitbucket