LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@mamono210(弍百獣 魔物)

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

Posted at

この記事では、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. 既存のテーマフォルダを移動または削除

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

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

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

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

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

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

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

    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 を開き、以下のように修正します。

    /* 修正前：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／画像など）を配信できます。

<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 の再読み込み

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

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

# まず既存の 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 を導入します。

# 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 で動かす場合の例です。

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 に実際のファイルが生成されているか？

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 になります。再度設定を見直してください。

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 など）になります。以下コマンドでコンテキストを再付与してみてください（テスト的に無効化する方法もありますが、本番環境では推奨しません）。

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 環境でテーマ導入に悩んでいる方の参考になれば幸いです。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?