Docker Compose で Gitea を導入する手順と、つまずきやすい設定

Gitea を試す方法として、いちばん手軽なのが Docker Compose です。設定ファイルを一つ書き、一つのコマンドで起動すれば、数分でブラウザーから初期設定の画面が開きます。専用のサーバーを用意しなくても、手元のパソコンで同じ構成を再現できるので、本番に近い形で操作を確かめるのにも向いています。

ただし、手軽に起動できることと、長く安全に運用できることは別の話です。この記事では、ドキュメントに載っている設定をもとに、起動までの手順と、あとから困りやすい点を順に説明します。確認した時点の最新の安定版は 28.3.0 です（2026年11月15日時点）。

使うもの

Docker と Docker Compose。設定ファイルは一つです。

データベース

何も指定しなければ SQLite。MySQL と PostgreSQL は設定を足して使います。

ポート

画面は 3000、SSH は 22 をコンテナ側で使います。

注意

通常版と rootless 版のイメージは互換性がありません。

起動はすぐでも、あとで直しにくい設定がある

導入で後悔しやすいのは、起動したあとに直しにくい選択を、深く考えずに決めてしまうことです。代表的なものを三つ挙げます。

データベースの種類です。 何も指定しないと SQLite が使われます。試用にはちょうどよい反面、規模が大きくなる用途には向かないとされ、別のデータベースへ移す作業は十分に検証された手順ではないと説明されています。長く使う予定なら、最初に決めておくほうが安全です。
データの保存場所です。 Gitea のリポジトリ、設定、添付ファイルなどは、コンテナ内の /data に保存されます。ここをホストのディレクトリやボリュームに結び付けていないと、コンテナを作り直した時にデータを失います。
鍵の扱いです。 設定にある SECRET_KEY は、インストール後に変更すると、暗号化されたデータが読めなくなると警告されています。後から気軽に変えられる値ではありません。

この三つを押さえておけば、残りの設定は後から調整できます。以降は、この前提で手順を見ていきます。

最小構成で起動する

ドキュメントに載っている基本の設定を、次に示します。ファイル名は docker-compose.yml とし、任意の空のディレクトリに置きます。

networks:
  gitea:
    external: false
services:
  server:
    image: docker.gitea.com/gitea:28.3.0
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

主な項目の意味は、次のとおりです。

項目	意味
`image`	使うイメージとバージョンです。バージョンを固定すると、意図しない更新を防げます
`USER_UID` / `USER_GID`	コンテナ内の Gitea が使うユーザーとグループの番号です。ホストのディレクトリを使う場合は、その所有者に合わせます
`volumes`	`./gitea:/data` が、データの保存先です。時刻の設定は、ログの時刻をホストに合わせるためのものです
`ports`	`3000` が Web 画面、`222:22` が SSH です。ホスト側の 222 番を、コンテナ内の 22 番に結び付けています

起動は、同じディレクトリで次のコマンドを実行します。

docker compose up -d

起動したら、ブラウザーで http://localhost:3000 を開きます。初回は初期設定の画面が表示され、データベースの種類やサイトの名前、管理者のアカウントなどを入力します。データベースの欄で SQLite を選べば、追加の準備は要りません。

イメージのタグは、安定版として latest、メジャーバージョンを示す 1、バージョンを固定する 28.3.0 が用意されています。開発中のものは main-nightly、リリースの枝ごとの開発版は 1.27-nightly のような形です。運用では、latest ではなくバージョンを固定したタグを選び、更新するときに自分で書き換えるやり方をおすすめします。更新のタイミングを自分で決められ、更新前のバックアップも計画に入れやすくなります。

MySQL や PostgreSQL を使う

本番で使う、あるいは利用者が増える見込みがあるなら、別のデータベースを併設します。ドキュメントには、MySQL と PostgreSQL の設定例が載っています。

MySQL を使う場合

server の environment に、次の項目を加えます。

      - GITEA__database__DB_TYPE=mysql
      - GITEA__database__HOST=db:3306
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea

server には depends_on で db を指定し、services に db を追加します。

  db:
    image: docker.io/library/mysql:8
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=gitea
      - MYSQL_USER=gitea
      - MYSQL_PASSWORD=gitea
      - MYSQL_DATABASE=gitea
    networks:
      - gitea
    volumes:
      - ./mysql:/var/lib/mysql

PostgreSQL を使う場合

DB_TYPE を postgres、HOST を db:5432 にし、db には次のように PostgreSQL のイメージを指定します。

  db:
    image: docker.io/library/postgres:18
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql

PostgreSQL には、押さえておきたい特性があります。データのディレクトリは、新しいメジャーバージョンに自動では移行されません。メジャーバージョンを上げるときは、pg_upgrade を使うか、ダンプを取って入れ直す必要があります。イメージのタグを書き換えるだけで更新が済む、とは考えないでください。

例のパスワードは、すべて説明用の gitea です。実際に使うときは、推測されにくい値に必ず置き換えてください。パスワードをファイルに直接書きたくない場合は、設定名の末尾に __FILE を付けると、値をファイルから読み込めます。

ポートと設定ファイルの扱い

家庭や社内のサーバーでは、3000 番や 22 番がほかのサービスと重なることがあります。その場合は、ports の左側（ホスト側）だけを変更します。たとえば "8080:3000" や "2221:22" とすれば、コンテナ内の番号は変わりません。

ただし、HTTP のポートに 3000 番以外を使う場合は、設定ファイル app.ini の LOCAL_ROOT_URL を、実際の内部の URL（たとえば http://localhost:3000/）に合わせる必要があります。コンテナ内部の通信で使われる値のため、ホスト側のポートを変えただけでは足りないことがあります。

Gitea の設定は、app.ini に書く方法のほかに、環境変数で渡す方法があります。形式は、GITEA__セクション名__キー名=値 です。上で見たデータベースの設定も、この形式でした。設定ファイルを別に管理せずに済むため、Docker Compose との相性がよい方法です。

鍵の生成も、コンテナで行えます。SECRET_KEY と INTERNAL_TOKEN は、gitea generate secret コマンドで作れます。ただし、SECRET_KEY を後から変えると暗号化したデータが読めなくなるため、最初に決めて、安全な場所に控えておきます。

ボリュームと権限の落とし穴

ホストのディレクトリを /data に結び付ける場合は、USER_UID と USER_GID を、そのディレクトリの所有者に合わせます。合っていないと、Gitea がファイルを書き込めず、起動に失敗したり、リポジトリを作成できなかったりします。

権限の調整が面倒な場合は、名前付きボリュームを使う方法があります。volumes の最上位に gitea: を定義し、gitea:/data として結び付けます。名前付きボリュームは、ホスト側の権限を設定しなくても使えます。なお、/data に対しては、ディレクトリの結び付けと名前付きボリュームのどちらか一方だけを使います。両方を指定しないでください。

もう一つ、見落としやすいのが、通常版と rootless 版の違いです。Gitea には、通常のイメージと、root 権限を使わない rootless のイメージがあり、この二つは互換性がありません。image の値を、途中でもう一方に切り替えてはいけません。rootless の手順は別に用意されているので、最初にどちらを使うかを決めてから始めます。

設定ファイルとデータの置き場所を整える

最小構成の設定ファイルを置くディレクトリは、あとから見て分かりやすい形にしておくと、運用が楽になります。たとえば、gitea という専用のディレクトリを作り、その中に docker-compose.yml を置きます。設定の中の ./gitea:/data は、設定ファイルと同じ場所にできる gitea ディレクトリを、コンテナの /data に結び付けるという意味です。MySQL や PostgreSQL を使う場合は、./mysql や ./postgres が同じ階層にできます。

こうしておくと、バックアップの対象が、設定ファイルのあるディレクトリにまとまります。サーバーを入れ替えるときにも、ディレクトリごと移せばよいので、移行の見通しが立ちます。逆に、データがホストの複数の場所に散らばっていると、何を移せばよいのかが分かりにくくなります。

設定ファイルそのものも、大切な資産です。パスワードを含む場合は、アクセスできる人を限定します。また、設定ファイルをリポジトリで管理する場合は、パスワードをそのまま書かず、環境変数の外部ファイルなどに分けて、公開される場所に載せない工夫が必要です。

起動しないときに、順に確かめること

初めての起動では、思いどおりに動かないことも珍しくありません。そのようなときは、原因を一つずつ切り分けます。

コンテナが動いているかを確認します。 docker compose ps で、状態を表示します。すぐに終了している場合は、設定に問題があります。
ログを読みます。 docker compose logs で、起動の途中で出ている、エラーの内容を確認します。多くの原因は、ここに書かれています。
ポートの重なりを疑います。 3000 番や 22 番が、ほかのサービスで使われていると、起動に失敗します。その場合は、ホスト側のポート番号を変えます。
権限を疑います。 ホストのディレクトリを使っているなら、USER_UID と USER_GID が、そのディレクトリの所有者と合っているかを確認します。
データベースへの接続を疑います。 MySQL や PostgreSQL を併用しているなら、HOST の名前と、ポート、ユーザー名、パスワードが、データベース側の設定と一致しているかを見ます。

この順序で確認すれば、ほとんどの問題は、原因を絞り込めます。特にログは、最初に読む習慣をつけておくと、調査の時間が大きく減ります。

本番に近づけるときの考え方

手元で動いたものを、そのまま本番にするのは避けたほうが安全です。本番に使う前に、次の点を見直します。

バージョンを固定します。 latest ではなく、特定のバージョンのタグを使い、更新は自分で判断して行います。
データベースを見直します。 SQLite のまま本番に進まず、MySQL か PostgreSQL に切り替えるかを検討します。
パスワードを置き換えます。 例に使われている簡単な値を、すべて推測されにくいものに変えます。
バックアップを決めます。 取り方、頻度、保存先を決め、一度戻せることを確かめます。
ポートの公開範囲を決めます。 インターネットに公開する場合は、通信を暗号化し、必要なポートだけを開けます。

起動したあとの確認と、次にやること

起動後は、まず次の点を確認します。

ブラウザーで画面が開き、初期設定を完了できるか。
管理者でログインし、テスト用のリポジトリを一つ作れるか。
docker compose down のあと、もう一度 docker compose up -d を実行しても、作ったリポジトリが残っているか。

三つ目は、データの保存先が正しく設定されているかを確かめる、大切な確認です。コンテナを止めて起動し直しても、データが残っていれば、/data の結び付けは正しく機能しています。

そのうえで、本番運用に向けて、バックアップの手順を決めておきます。ここまで見てきたとおり、Docker Compose での導入は短時間で済みますが、データベースの選択、鍵の管理、ボリュームの設計は、あとから変えにくい項目です。時間をかけて決めるのはこの三点にして、残りは動かしながら整える進め方が、無理がありません。

データベースの選び方はデータベースの選び方で、バックアップはバックアップとリストアで、それぞれ詳しく扱います。この記事の設定は、動作を実際の環境で確認したものではなく、ドキュメントに載っている内容に基づいています。お使いの環境で、テスト用に起動して確かめたうえで、本番に反映していただくことをおすすめします。