Linux（Ubuntu 22.04 LTS）上に、GitBucket を Tomcat9、Apache（リバースプロキシ）、PostgreSQL と連携させて構築した手順のまとめです。
単体で動かすだけでなく、ウェブサーバー連携やデータベース連携を行った本格的なソース管理サーバーの構成となります。
サーバー構成概要
- OS: Ubuntu Desktop 22.04 LTS
- Webサーバー: Apache2 (AJP / HTTP プロキシ)
- APサーバー: Tomcat9 (Java 11)
- DB: PostgreSQL
- アプリケーション: GitBucket
1. OSおよび基本ネットワークの設定
固定IPアドレスの設定
サーバー用途として運用するため、固定IPアドレスを割り当てます。
- ホスト名:
your-gitserver（任意のホスト名） - 固定IP:
192.168.x.xxx
2. 必要なパッケージのインストール
管理者権限で作業を行います。
sudo su -
apt update && apt upgrade -ySSHの導入
外部端末（TeraTerm等）から操作できるようにSSHサーバーを導入します。
apt install openssh-server -ySambaおよびWSDDの導入（共有フォルダ・NetBIOS代替）
ファイル共有用にSambaおよびWindowsからの探索用パッケージ（wsdd）をインストールします。
apt install samba wsdd -y
# ユーザーの追加（例: your_user）
pdbedit -a your_user
# 共有フォルダの作成
mkdir /var/samba
chmod 777 /var/samba/etc/samba/smb.conf の末尾に共有設定を追記します。
[homes]
comment = Home Directories
browseable = no
read only = no
create mask = 0700
directory mask = 0700
valid users = %S
[public]
comment = public anonymous access
path = /var/samba/
browsable = yes
create mask = 0660
directory mask = 0771
writable = yes
guest ok = yesサービスの再起動：
systemctl restart smbd.service nmbd.service3. GitBucket サーバーの構築
① Java JRE のインストール
GitBucketの動作に必要なJava環境をインストールします。
apt install default-jre -y② Tomcat9 のインストールと各種設定
APサーバーとしてTomcat9を導入します。
apt install tomcat9 tomcat9-admin -y
systemctl stop tomcat9.service1. /etc/default/tomcat9 の編集
Java環境変数とGitBucketのホームディレクトリを設定します。
#JAVA_HOME=/usr/lib/jvm/java-8-openjdk
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
# GitBucketホームディレクトリ指定
GITBUCKET_HOME=/var/gitbucket2. /var/lib/tomcat9/conf/server.xml の編集
Apacheとの連携に必要な AJP 1.3 コネクタのコメントアウトを解除・修正します。
<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector address="::1" port="8009" protocol="AJP/1.3" redirectPort="8443" secretRequired="false"/>3. /var/lib/tomcat9/conf/tomcat-users.xml の編集
Tomcat Webアプリケーションマネージャ接続用の管理ユーザーを設定します。末尾の </tomcat-users> の直前に追記します。
<role rolename="tomcat"/>
<role rolename="manager-gui"/>
<role rolename="admin-gui"/>
<user username="admin" password="your_secure_password" roles="tomcat,manager-gui,admin-gui"/>4. /lib/systemd/system/tomcat9.service の設定確認
Tomcatサービスが /var/gitbucket へアクセスできるように読み書きパスを設定します。
[Service]
# Configuration
Environment="CATALINA_HOME=/usr/share/tomcat9"
EnvironmentFile=/etc/default/tomcat9
# Security
User=tomcat
Group=tomcat
ReadWritePaths=/var/gitbucket5. /usr/share/tomcat9-admin/manager/WEB-INF/web.xml の編集
Tomcatマネージャ経由で大きなWARファイル（GitBucket）を配備できるよう、アップロード上限サイズを500MBに引き上げます。
<multipart-config>
<!-- 500MB max -->
<max-file-size>524288000</max-file-size>
<max-request-size>524288000</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>6. ディレクトリの作成と権限設定
# tomcatユーザーのホーム作成
mkdir /home/tomcat
chown tomcat:tomcat /home/tomcat
usermod -d /home/tomcat tomcat
# GitBucket用ディレクトリの作成
mkdir /var/gitbucket
chown tomcat:tomcat /var/gitbucket
chmod 775 /var/gitbucket
# Tomcatの起動
systemctl start tomcat9.service③ GitBucket (gitbucket.war) の配備
- GitBucket Releases (GitHub) から最新の
gitbucket.warをダウンロードします。 - ブラウザでTomcatの管理ページ（
http://192.168.x.xxx:8080/manager/）にアクセスします。- ユーザー名:
admin - パスワード: 上記設定で指定したパスワード
- ユーザー名:
- 「WAR ファイルの配備」の「ファイルを選択」で
gitbucket.warを選び、「配備」ボタンを押下します（/var/lib/tomcat9/webapps/に配置されます）。 http://192.168.x.xxx:8080/gitbucket/でGitBucketの初期画面が表示されることを確認します。
4. Apache (Webサーバー) との連携
80番ポート（標準HTTP）でアクセスできるようにApacheをリバースプロキシとして設定します。
apt install apache2 -y
a2enmod proxy proxy_http proxy_ajp/etc/apache2/sites-available/001-gitserver.conf を作成します。
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
ProxyPreserveHost On
ProxyPass /gitbucket http://localhost:8080/gitbucket
ProxyPassReverse /gitbucket http://localhost:8080/gitbucket設定を有効化して再起動します。
a2ensite 001-gitserver.conf
systemctl restart apache2.service tomcat9.serviceこれで http://192.168.x.xxx/gitbucket/ からアクセス可能になります。
5. PostgreSQL (データベース) との連携
デフォルトのH2データベースから、パフォーマンスと信頼性の高いPostgreSQLに変更します。
PostgreSQLのインストールとデータベース作成
apt install -y postgresql
# PostgreSQL管理ユーザーに切替
sudo -u postgres -i
psqlpsql コンソール上でロールとDBを作成します。
CREATE USER gitbucket WITH PASSWORD 'your_secure_password';
CREATE DATABASE gitbucket;
GRANT ALL PRIVILEGES ON DATABASE gitbucket TO gitbucket;
ALTER DATABASE gitbucket OWNER TO gitbucket;
\q💡 Tips: 最新版のPostgreSQLを使いたい場合 Ubuntu標準のバージョンではなく最新版を利用したい場合は、公式リポジトリを追加して導入することもできます。
sudo apt install curl ca-certificates gnupg -y curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/apt.postgresql.org.gpg >/dev/null sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' sudo apt update sudo apt install -y postgresql
GitBucket側のDB接続設定
/var/gitbucket/database.conf を修正（または作成）します。
db {
url = "jdbc:postgresql://localhost/gitbucket"
user = "gitbucket"
password = "your_secure_password"
}サービスを再起動して設定を反映します。
systemctl restart apache2.service tomcat9.service6. 初期設定およびSSHアクセスの有効化
http://192.168.x.xxx/gitbucket/にアクセス。- 初期管理者アカウント（ユーザー名:
root/ パスワード:root）でログイン。 (※ ログイン後、安全のため必ず管理者のパスワードを変更してください) - System Administration > System settings から SSH アクセス設定（
SSH access）を有効化して保存します（/var/gitbucket/gitbucket.confに保存されます）。- これにより各ユーザーの設定画面（Account settings）で SSH Keys の登録項目が表示されるようになります。
⚠️ トラブルシューティング
Tomcat9のアップデート後にリポジトリが表示されなくなる問題
症状
ある日突然 http://192.168.x.xxx/gitbucket/ にアクセスしてもリポジトリが何も表示されず、ユーザーのログインもできなくなる現象が発生。
管理者（root）でログインして System settings を確認すると、GITBUCKET_HOME のパスが本来設定していた /var/gitbucket から /home/tomcat/.gitbucket に変わってしまっていた。
原因
Ubuntuのパッケージ更新により Tomcat9 がアップデートされた際、systemd のセキュリティ機能（サンドボックス化）が有効になり、Tomcatプロセスが /var/gitbucket への書き込み権限を失ったことが原因。 書き込みに失敗したため、デフォルトのホームディレクトリ（~/.gitbucket）にフォールバックして動いていた。
解決策
systemd の override 設定を作成し、Tomcat9 に /var/gitbucket への書き込み権限を明示的に許可します。
# override用ディレクトリの作成
mkdir -p /lib/systemd/system/tomcat9.service.d/
# 設定ファイルの作成
nano /lib/systemd/system/tomcat9.service.d/override.confoverride.conf に以下の内容を記述します。
[Service]
# Configuration
EnvironmentFile=/etc/default/tomcat9
ReadWritePaths=/var/gitbucketDaemonを再読み込みしてTomcat9を再起動します。
systemctl daemon-reload
systemctl restart tomcat9.service再起動後、無事に /var/gitbucket が読み込まれ、リポジトリやユーザー情報が復旧します。
💡 Tips: GitBucketのバージョンアップ手順と注意点（トラブル回避）
GitBucketをマイナーバージョンアップ（例: v4.43 → v4.47.1）する際の手順と、実際にハマりがちな注意点・トラブルシューティングです。
1. バージョンアップの基本手順
- Tomcat9サービスの停止
sudo systemctl stop tomcat9- WARファイルの差し替え
Tomcat Manager（Web画面）から配備するのではなく、ダウンロードした新しいgitbucket.warを/var/lib/tomcat9/webapps/gitbucket.warに直接上書き配置します。 - Tomcat9サービスの再起動
sudo systemctl restart tomcat92. アップデート時の2大ハマりどころと対策
① Web管理画面（Tomcat Manager）からの動的リロード（ホットデプロイ）は避ける
Tomcat Manager画面から .war ファイルを配備・再起動（ホットデプロイ）しようとすると、GitBucket内部のSSHサーバーやDB接続スレッドの解放漏れが原因で IllegalStateException などのクラスローダーエラーが発生し、起動に失敗することがあります。
- 対策: WARファイルの更新や設定変更後は、Web画面からリロードせず、必ずOS側のコマンド（
sudo systemctl restart tomcat9）でTomcatサービスごと再起動してください。
② 古いプラグイン（.jar）の残留と競合エラー
本体をアップデートした際、/var/gitbucket/plugins 内に古いバージョンの標準プラグイン（例: gitbucket-gist-plugin-*.jar）が残っていると、新旧プラグインが競合して起動エラーの原因になります。
- 対策: 起動に失敗する場合は、一旦プラグインフォルダを退避して切り分けを行います。
# プラグインフォルダを一時退避
sudo mv /var/gitbucket/plugins /var/gitbucket/plugins_backup
sudo mkdir /var/gitbucket/plugins
sudo chown tomcat:tomcat /var/gitbucket/plugins
# Tomcatを再起動（本体のみで無事起動するか確認）
sudo systemctl restart tomcat9- 本体が正常起動すれば、新しい標準プラグインが自動生成されます。自作・サードパーティ製のプラグインのみ最新版を取得して元の位置に戻し、不要になった過去のバックアップは削除します。
sudo rm -rf /var/gitbucket/plugins_backup教訓: エラーが起きた際に「新しい設定ファイル（Context XMLなど）を増やす」前に、「古いキャッシュや残存ファイルを削ぎ落としてシンプルにする」ことで解決できるケースが多くあります。
💡 補足：Tomcat Manager経由でアップデートを行う場合
Tomcat Managerの「WARファイルの配備」を使用する場合でも、事前に
/var/gitbucket/plugins内を空にしておき、配備後にTomcat9およびApache2を再起動することで正常に更新できるケースがあります。ただし、クラスロードの競合やDBマイグレーションの安全性を最優先する場合は、Tomcatサービスを一度停止して手動でWARファイルを置き換える方法が最も確実です。
コメント