Redmine 5.1からRedmine 6.1（Rails 7.2）への移行検証を進めていると、プラグイン以外にもいくつか「以前と同じやり方では動かない」箇所が出てきます。

その中でも、意外と厄介だったのがカスタムテーマの移行でした。

今回、長年使ってきた kodomo テーマをRedmine 6.1環境へ移そうとしたところ、

  • 管理画面のテーマ一覧にカスタムテーマが出てこない
  • 何とか設定を通してみると、今度はCSSが適用されず画面が崩壊する

という、二段構えの問題に遭遇しました。

最初は「テーマをコピーすれば終わりだろう」と考えていたのですが、Redmine 6ではその前提自体が変わっています。

調べていくと、Redmine 6.0で行われたアセットパイプラインの変更、つまりSprocketsからPropshaftへの移行が、この問題の根っこにありました。

今回は、このテーマ移行で実際に引っかかった箇所と、Redmine 6.1側で動く状態まで戻した手順を記録しておきます。

1. まず何が起きたのか

今回の移行では、kodomo テーマをRedmine 5.1環境からRedmine 6.1環境へ持ってきました。

ところが、Redmine 6.1を起動して管理画面の

設定 ＞ 表示 ＞ テーマ

を確認してみても、表示されているのは標準テーマの Alternate と Classic だけ。

カスタムテーマの Kodomo がありません。

テーマそのものは、

public/themes/kodomo

に存在しています。

ディレクトリやファイルの所有者・権限にも問題はありません。Passengerを再起動しても出てこない。

そこでRedmine内部のテーマスキャンを確認すると、どうもそもそもテーマとして認識されていないようでした。

さらに、DB側の設定を直接変更してテーマを適用させてみると、今度は別の問題が発生しました。

テーマ名は設定できた。しかしCSSが適用されない。

ブラウザに表示されるのは、文字とリンクとリストが並んだだけの、いわゆる「素のHTML」。見事に画面が崩壊しました。

つまり今回の問題は、

  1. テーマそのものをRedmineが見つけられない
  2. 見つけさせてもCSSの読み込み方が古い

という二つの問題が重なっていたわけです。

2. 原因はRedmine 6.0からのアセットパイプライン変更

ここで重要になるのが、Redmine 6.0から導入されたPropshaftです。

Redmine 5.xまでの環境では、Railsのアセット管理に主として Sprockets が使われていました。

SprocketsはCSSやJavaScriptなどのアセットを処理・結合・コンパイルする仕組みで、Redmineでも長らく使われてきたものです。

一方、Redmine 6.0ではこの部分がPropshaftへ移行しました。

PropshaftもRailsのアセットパイプラインを担う仕組みですが、Sprocketsとはアセットの探索や扱い方が異なります。

Redmine 5.x時代に作られたテーマは、

「以前のRedmineでは、この場所にテーマがあり、この相対パスなら標準CSSを読み込める」

という前提で作られています。ところがRedmine 6.xでは、その前提が崩れています。今回のテーマ移行で問題になったのも、まさにそこでした。

3. テーマの置き場所が変わっている

Redmine 5.xまで使っていたテーマは、基本的に

public/themes/

以下へ配置していました。ところがRedmine 6.xでは、テーマの標準配置場所が変わっています。

Redmine本体のルートディレクトリから見て、

themes/

です。今回のRedmine 6.1環境は、

/home/www-data/redmine_v6

なので、テーマは最終的に

/home/www-data/redmine_v6/themes/kodomo

となる形です。つまり、Redmine 5.1からそのまま

public/themes/kodomo

をコピーしただけでは、Redmine 6.1側のテーマローダーから見つけてもらえません。これが、最初の

「テーマを置いたのに管理画面に出てこない」

という問題の原因でした。

4. テーマを themes/ へ移す

ということで、まずはRedmine 6.1側にテーマを配置します。

sudo -u www-data cp -pir public/themes/kodomo themes/
sudo chown -R www-data:www-data themes
sudo chmod -R 755 themes

これで、

/home/www-data/redmine_v6/themes/kodomo

という構造になります。テーマの中には、少なくとも今回のケースでは、

themes/
└── kodomo/
    └── stylesheets/
        └── application.css

という構造が必要です。ここまでやってから、もう一度Redmine側からテーマを認識できるか確認します。

5. しかし、これだけではまだ画面は直らない

ここが今回のもう一つの罠でした。テーマを正しい場所へ移したことで、Redmineからテーマとして認識されるようになります。しかし、実際にテーマを適用してみると、

CSSが読み込まれません。

結果として、画面はこうなります。

文字
リンク
箇条書き
フォーム
表

……以上。

ブラウザとしては正しくHTMLを表示しているのですが、Redmineとして見ると完全に「何かがおかしい」。これはテーマ側の application.css が、Redmine本体のCSSを正しく参照できていないためでした。

6. application.css の相対パスも変更する

Redmineのカスタムテーマでは、標準のCSSを読み込んだ上で、自分のテーマ固有のCSSを追加する構造になっているものがあります。今回の kodomo もそのタイプでした。

Redmine 5.x時代のテーマでは、

@import url(../../../stylesheets/application.css);

という指定になっていました。ところが、Redmine 6.xではテーマの配置場所そのものが変わっています。そのため、この相対パスでは標準CSSへ到達できません。

Redmine 6.x側では、

@import url(../../application.css);

へ変更します。今回の場合は、

themes/kodomo/stylesheets/application.css

から見て、Redmine側のCSSを参照するためのパスが変わった、と考えると分かりやすいです。

7. application.css を修正する

まずは念のためバックアップを取得します。

cd /home/www-data/redmine_v6/themes/kodomo/stylesheets
sudo -u www-data cp -p application.css application.css.bak

そして、旧パスを新しいパスへ置き換えます。

sudo -u www-data sed -i \
's|@import url(../../../stylesheets/application.css);|@import url(../../application.css);|g' \
application.css

念のため、修正後の内容も確認しておきます。

grep '@import' application.css

ここで、

@import url(../../application.css);

となっていればOKです。

8. Railsからテーマを認識できるか確認する

ここまで来たら、Webブラウザで確認する前にRails側からテーマを認識できるか確認しておきます。

cd /home/www-data/redmine_v6
sudo -u www-data RAILS_ENV=production bundle exec rails runner "
  Redmine::Themes.rescan
  Redmine::Themes.themes.each do |t|
    puts 'Loaded Theme -> ID: ' + t.id + ' | Name: ' + t.name
  end
"

正常に読み込まれていれば、例えば次のように表示されます。

Loaded Theme -> ID: alternate | Name: Alternate
Loaded Theme -> ID: classic | Name: Classic
Loaded Theme -> ID: kodomo | Name: Kodomo

ここで kodomo が出てくれば、少なくともRedmineのテーマローダーからは認識されています。

9. 最後にPassengerを再起動する

テーマを修正したら、Webアプリケーション側も再起動しておきます。Passenger環境では、

sudo touch /home/www-data/redmine_v6/tmp/restart.txt
sudo systemctl reload apache2

としておきます。その後、Redmineへアクセスして、

管理 ＞ 設定 ＞ 表示 ＞ テーマ

を確認します。ここに、

Alternate
Classic
Kodomo

と表示されれば、テーマ自体は認識されています。あとは Kodomo を選択して画面を確認します。

CSSが正常に読み込まれていれば、今度はRedmine 5.1時代の見慣れた画面が戻ってきます。

10. 今回の問題を整理すると

今回のトラブルは、最初は「Redmine 6.1で古いテーマが使えなくなった」と見えました。

しかし、実際には二つの問題がありました。

問題1：テーマを置く場所が変わった

Redmine 5.xでは、

public/themes/kodomo

でした。Redmine 6.xでは、

themes/kodomo

です。そのため、旧環境からテーマをそのままコピーしただけでは、Redmineから認識されません。

問題2：テーマ内部のCSS参照も古い

さらに、テーマがRedmineから認識されたとしても、古い application.css のままでは標準CSSを読み込めません。

Redmine 5.xでは、

@import url(../../../stylesheets/application.css);

だったものを、Redmine 6.xでは、

@import url(../../application.css);

へ変更する必要がありました。つまり、

「テーマを移動する」だけではなく、「テーマからRedmine本体を参照しているパスも見直す」必要がある

ということです。

11. Redmine 6.xへテーマを移行するときのチェックリスト

今回の作業をチェックリストにすると、こんなところでしょうか。

  • public/themes/ に置きっぱなしになっていないか
  • Redmineルート直下の themes/ にテーマを配置したか
  • themes/<テーマ名>/stylesheets/application.css が存在するか
  • application.css の古い相対パスが残っていないか
  • @import url(../../application.css); になっているか
  • テーマディレクトリの所有者・権限を確認したか
  • Redmine::Themes.rescan でテーマが認識されているか
  • Passengerを再起動したか
  • ブラウザのキャッシュだけでなく、CSSの読み込み自体が成功しているか

まとめ

Redmine 5.1から6.1への移行というと、どうしてもデータベースやプラグインの互換性に目が行きます。

実際、そちらの方が重要ではあるのですが、今回のようにテーマもRedmine本体の変更に巻き込まれることがあります。

特にRedmine 6.0からは、RailsのアセットパイプラインがSprocketsからPropshaftへ移行しています。

その結果として、テーマの配置場所やCSSの参照方法について、Redmine 5.x時代のテーマをそのまま持ってきても動かないケースが出てきます。

今回の kodomo については、

public/themes/kodomo
        ↓
themes/kodomo

への移動と、

@import url(../../../stylesheets/application.css);

から

@import url(../../application.css);

への変更で復旧できました。

Redmine 6.xへの移行では、プラグインだけを確認して「よし、動いた」とするのではなく、テーマもまたバージョンアップの影響を受ける部品として確認しておくのが安全そうです。

今回のように、

「テーマが一覧に出ない」
↓
「何とか指定できた」
↓
「今度はCSSが全部消えた」

という二段コンボを食らうと、原因が同じ場所にあるとはなかなか気づきにくいところでした。

移行作業では、こういう「前のバージョンでは当たり前だった場所」を一つずつ疑っていく必要がありそうです。