Redmine（RedMica）に「Bleuclair」テーマを導入するまでの道のり

この記事では、CentOS Stream 9＋Apache（httpd）＋Passenger 環境で Redmine（RedMica 3.2.0.devel／Redmine 6.0.5）を動かし、Farend 氏提供の「Bleuclair」テーマを適用する一連の流れをまとめます。
実際に僕が直面した以下のようなトラブルを順に解決しながら、最終的にテーマが正しく反映されるまでの手順を解説します。

1. テーマを置くディレクトリが合わず、管理画面から選べない状態
2. Apache の Alias 設定を修正
3. Rails 7＋Propshaft（RedMica）でのアセットプリコンパイル用ツール（Node.js/Yarn）の導入
4. `rake assets:precompile` タスクの実行方法
5. 404 エラーが消えずに悩んだ原因と解決ポイント
6. 最終的にテーマが無事反映された確認

---

## 1. テーマを設置するディレクトリに注意

### 1.1 Redmine 6（RedMica 3系）では `/themes` 配下を使う

Redmine 6 以降（RedMica 3.2.0.devel ＝ Rails 7.2.2.1）は、従来の Redmine（Rails 5 〜 6）と異なり、テーマを配置する標準パスが以下のように変わっています。

```
<Redmineのルートフォルダ>/themes/<テーマ名>/
```

* **従来（Redmine 5 以前）**
  → `public/themes/<テーマ名>/…`
* **Redmine 6（RedMica）以降**
  → `<Redmineルート>/themes/<テーマ名>/…`

今回、最初は勘違いで `/var/lib/redmine/public/themes/bleuclair` にクローンしていたため、管理画面の「管理 > 設定 > 表示」で選択できない…という状態に陥りました。
Redmine 6 系では自動的に `<Redmineルート>/themes/` 配下をスキャンするようになっているので、下記の手順で設置ディレクトリを変更する必要があります。

### 1.2 正しい配置手順

1. **既存のテーマフォルダを移動または削除**

   ```bash
   sudo rm -rf /var/lib/redmine/public/themes/bleuclair
   ```

   または安全のために別の場所へバックアップしておく：

   ```bash
   sudo mv /var/lib/redmine/public/themes/bleuclair ~/backup/bleuclair_backup
   ```

2. **`<Redmineルート>/themes/` ディレクトリを作成（存在しない場合）**

   ```bash
   cd /var/lib/redmine
   sudo mkdir -p themes
   sudo chown -R apache:apache themes
   sudo chmod 755 themes
   ```

   ※ Apacheユーザーを `apache`、グループを `apache` と仮定しています。環境に合わせて適宜置き換えてください。

3. **GitHub からクローンして配置**

   ```bash
   cd /var/lib/redmine/themes
   sudo git clone https://github.com/farend/redmine_theme_farend_bleuclair.git bleuclair
   sudo chown -R apache:apache bleuclair
   sudo chmod -R 755 bleuclair
   ```

   これで `/var/lib/redmine/themes/bleuclair/` 以下に、テーマの `images/`、`stylesheets/` などが正しく配置されます。

4. **CSS 内の `@import` を Redmine 6 向けに修正（必要に応じて）**
   Rails 7（Propshaft）では、テーマ内 CSS で標準の `application.css` をインポートする際の相対パスが変わっています。
   `/var/lib/redmine/themes/bleuclair/stylesheets/application.css` を開き、以下のように修正します。

   ```css
   /* 修正前：Redmine 5 以前でよく見られた import 文 */
   /* @import url('../../../stylesheets/application.css'); */

   /* 修正後：Redmine 6（Rails 7 向け） */
   @import url('../../application.css');
   ```

   この相対パスを正しくしないと、ビルド時に CSS が取り込まれず 404 になることがあります。

5. **管理画面でテーマが選択可能になっているか確認**

   * 管理者ユーザーで Redmine にログインし、
     **管理 > 設定 > 表示** のプルダウンを開くと、「bleuclair」が候補に現れます。
   * もし候補に出てこなければ、再度ディレクトリ構造・権限をチェックしてください。

---

## 2. Apache（httpd）＋Passenger の設定

テーマが正しく配置されたら、Apache が `/redmine` のリクエストを Redmine の `public` 配下へマッピングできているかを確認します。

### 2.1 `redmine.conf` のイメージ

以下のように設定すれば、`http://<ホスト>/redmine/...` で Redmine の静的ファイル（CSS／JS／画像など）を配信できます。

```apache
<Directory "/var/lib/redmine/public">
  Require all granted
</Directory>

Alias /redmine /var/lib/redmine/public

<Location /redmine>
  PassengerBaseURI /redmine
  PassengerAppRoot /var/lib/redmine
</Location>

# Passengerモジュールのロードと設定
LoadModule passenger_module /usr/local/lib/ruby/gems/3.3.0/gems/passenger-6.0.27/buildout/apache2/mod_passenger.so
<IfModule mod_passenger.c>
  PassengerRoot /usr/local/lib/ruby/gems/3.3.0/gems/passenger-6.0.27
  PassengerDefaultRuby /usr/local/bin/ruby
</IfModule>

PassengerMaxPoolSize       20
PassengerMaxInstancesPerApp 4
PassengerPoolIdleTime      864000
PassengerStatThrottleRate  10

Header always unset "X-Powered-By"
Header always unset "X-Runtime"
```

* **注意点**

  * 最初に `/var/lib/redmine/public/themes` を Alias してしまう設定を入れていたときは、`Alias /redmine /var/lib/redmine/themes` が重複しており静的ファイルが正しく配信されない原因になっていました。
  * 外部に公開すべきは `/var/lib/redmine/public` フォルダのみであり、テーマは Redmine が内部的に参照するため、直接 Alias を貼る必要はありません。

### 2.2 Apache の再起動と Passenger の再読み込み

設定を変更したら、必ず以下を実行して反映させます。

```bash
# Passenger アプリケーションの再読み込み
sudo touch /var/lib/redmine/tmp/restart.txt

# Apache の再起動
sudo systemctl restart httpd
```

---

## 3. アセットプリコンパイル環境の整備（Node.js＋Yarn）

Rails 7＋Propshaft（RedMica 3 以降）では、JavaScript／CSS のビルドに Node.js（と Yarn または npm）が必須です。CentOS Stream 9 では最初からインストールされていないため、下記手順で追加します。

### 3.1 Node.js のインストール（CentOS 9）

```bash
# まず既存の nodejs モジュール設定をリセット（無効化）
sudo dnf module reset nodejs -y

# Node.js 16 を有効化
sudo dnf module enable nodejs:16 -y

# Node.js 本体をインストール
sudo dnf install -y nodejs

# バージョン確認
node -v    # 例: v16.x.x
npm -v     # 例: 8.x.x
```

### 3.2 Yarn のインストール（必要に応じて）

もしプリコンパイル時に Yarn の警告やエラーが出る場合は、公式リポジトリから Yarn を導入します。

```bash
# Yarn リポジトリを追加
curl -sL https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo

# Yarn をインストール
sudo dnf install -y yarn

# バージョン確認
yarn -v    # 例: 1.x.x や 3.x.x
```

* Node.js／Yarn の導入により、モダンな JavaScript/CSS アセットをビルドするための環境が整います。

---

## 4. Rails アセットのプリコンパイル

Redmine（Rails 7）では、rake タスクとして `assets:precompile` を実行します。以下はサブURI `/redmine` で動かす場合の例です。

```bash
cd /var/lib/redmine

# 環境変数の設定
export RAILS_ENV=production
export RAILS_RELATIVE_URL_ROOT=/redmine   # サブURI を使っているなら必須

# Gem が揃っていることを確認（初回のみ）
bundle install --without development test

# 既存アセットの削除（クリーンビルドしたい場合）
bundle exec rake assets:clobber

# プリコンパイル実行
bundle exec rake assets:precompile
```

* **成功すると**
  `public/assets/` の中に以下のような指紋付きファイルが生成されます（例）。

  ```
  application-0da21c69.css
  application-0da21c69.js
  theme-180018be.css
  theme-180018be.js
  …
  stimulus.min-e528a1de.js
  tribute.min-e98831eb.js
  theme-125551e5.js
  ```

* **もし `redmine:assets:precompile` でエラーになる場合**
  Rails 7 ではタスク名が変わっており、`rake assets:precompile` を使います。
  当初 `"Don't know how to build task 'redmine:assets:precompile'"` というエラーが出たのは、タスク名を間違えていたためです。

---

## 5. 404 エラーが出た原因と対策

プリコンパイル後もブラウザ側で以下のように 404 エラーが出るケースがあります。

```
Failed to load resource: the server responded with a status of 404 (Not Found) (application-0da21c69.css, line 0)
Failed to load resource: the server responded with a status of 404 (Not Found) (theme-180018be.css, line 0)
...
```

主にチェックすべきポイントは以下のとおりです。

### 5.1 `public/assets` に実際のファイルが生成されているか？

```bash
ls -l /var/lib/redmine/public/assets | head -n 20
```

* 上記で `application-xxxxx.css` や `theme-xxxxx.css` が存在しなければ、プリコンパイルが失敗しています。
* 成功していても、HAML/SCSS のビルドエラーや Node.js の問題でファイル生成まで至らない場合があるため、`rake` 実行時のログを必ず確認しましょう。

### 5.2 Apache の Alias 設定に間違いはないか？

Apache は `/redmine` → `/var/lib/redmine/public` をマッピングしています。
もし `/assets` 以下のリクエストが `/var/lib/redmine/public/assets` に届いていない場合、404 になります。再度設定を見直してください。

```apache
Alias /redmine /var/lib/redmine/public

<Directory "/var/lib/redmine/public">
  Require all granted
</Directory>
```

* 余計な `Alias /redmine /var/lib/redmine/themes` が残っていると、テーマやアセットが正しく配信されません。
* Apache 設定変更後は必ず `sudo systemctl restart httpd` で再起動してください。

### 5.3 `RAILS_RELATIVE_URL_ROOT` の設定漏れ

サブURI `/redmine` で動かしているのにプリコンパイル時に `RAILS_RELATIVE_URL_ROOT=/redmine` を設定していないと、生成されたアセット内の参照パスが `/assets/...` となり、実際の URL `/redmine/assets/...` と合わず 404 になります。

逆にドキュメントルート直下で動かしているのに `RAILS_RELATIVE_URL_ROOT=/redmine` を設定していると、参照先が `/redmine/assets/...` となり、やはり 404 になります。環境に合わせて正しくエクスポートしましょう。

### 5.4 SELinux の設定

CentOS Stream 9 など SELinux が有効な環境では、静的ファイルに正しいコンテキストが付与されていないとアクセス禁止（403 など）になります。以下コマンドでコンテキストを再付与してみてください（テスト的に無効化する方法もありますが、本番環境では推奨しません）。

```bash
sudo restorecon -Rv /var/lib/redmine/public/assets
```

---

## 6. Safari（macOS）で開発者ツールを使う方法

404 エラーの状況を可視化するために、MacOS Safari の「開発者ツール（Web インスペクタ）」を開く手順も紹介しました。

1. **Safari を起動** → メニューの「Safari > 環境設定…（⌘ + ,）」を開く
2. 「**詳細**」タブをクリック
3. 一番下の 「**メニューバーに“開発”メニューを表示**」 にチェックを入れる
4. メニューバーに「開発」が追加されるので、そこから「**Web インスペクタを表示（⌥⌘I）**」を選択
5. 開いた開発者ツールの「ネットワーク」タブで、対象ページをリロードし、 `/assets/...` が 404 になっていないか確認する

これにより、どのパスが 404 になっているか一目瞭然となり、原因切り分けが容易になります。

---

## 7. 最終的にテーマが反映できた確認

上記の手順をすべて正しく踏んだ結果、以下を確認してテーマの適用が完了しました。

1. **Redmine 管理画面 → 設定 → 表示** で「bleuclair」が選択できる
2. ブラウザの開発者ツールで、`/redmine/assets/application-xxxxx.css` および `/redmine/assets/theme-xxxxx.css` がステータス 200 で取得できる
3. Safari や Chrome でページを再読み込みすると、Bleuclair テーマの配色・レイアウトが正しく反映されている

実際、404 エラーは完全に消え、テーマの CSS／画像も問題なく読み込まれている状態を確認しています。

---

## 8. まとめとポイント

1. **Redmine 6（RedMica）ではテーマの置き場所が `<Redmineルート>/themes/<テーマ名>`**
   └ `/public/themes` は使われないので要注意。

2. **Apache の Alias 設定は `/public` のみを公開**
   └ `Alias /redmine /var/lib/redmine/public` が必須。

3. **Rails 7（Propshaft）でアセットをビルドするには Node.js（＋Yarn など）が必要**
   └ CentOS 9 では `dnf module enable nodejs:16` で導入。

4. **プリコンパイル時は `bundle exec rake assets:precompile`（`redmine:assets:precompile` ではない）**
   └ サブURI を使うなら `RAILS_RELATIVE_URL_ROOT=/redmine` を忘れずに。

5. **パーミッションや SELinux を確認**
   └ `chown -R apache:apache themes`、`chmod -R 755 public/assets`、必要なら `restorecon -Rv /var/lib/redmine/public/assets`。

6. **ブラウザのキャッシュをクリアしてネットワークタブで 200 を確認**
   └ 404 が消えれば成功。

以上を押さえれば、CentOS Stream 9＋Apache＋Passenger 上の Redmine で「Bleuclair」テーマを無事に適用できます。
同じように RedMica／Redmine 6 環境でテーマ導入に悩んでいる方の参考になれば幸いです。