ＦｒｅｅＢＳＤにおけるＲｅｄｍｉｎｅのアップグレード

# はじめに
Ｒｅｄｍｉｎｅバージョン、１．０（別システムで稼働）→４．１（以後ＦｒｅｅＢＳＤ）、３．４→４．０→４．１→４．２とアップグレードしてみた。手順としては変わりなかったので、まとてみた。

- 事前にｐｋｇ／ｐｏｒｔｓシステムがサポートしているＦｒｅｅＢＳＤバージョンを確認する必要がある。
- あまりにも古い環境では、先にＯＳをアップデートしてから作業する必要がある。
- あるいは新環境を新たに用意し、バックアップ／リストアにより、旧環境より移行するのもアリと思われる。
- 通常、バックアップ／リストアによる移行は面倒ではあるのだが、この手の作業としては十分以上に楽であることを確認している。
- Ｒｅｄｍｉｎｅのアップグレード方法については、[本家資料](https://www.redmine.org/projects/redmine/wiki/RedmineUpgrade)にて詳しく説明が存在する（[日本語版](http://guide.redmine.jp/RedmineUpgrade/)）。
- ただし `ruby` や `subversion`、`bundler` といった仕組みを知った上での作業となるのだが、これはｐｋｇ／ｐｏｒｔｓシステムとの作法（仕組み）とは以下の点で違いすぎる。
    - `bundler` を（直接）触っている。
    - `subversion` でデプロイしている。
- この辺りの事情を考慮して上記資料を補完する。元資料の流れを流用しつつ、以下のように変えていく。
    - 動作環境の確認（ニュアンスが変わる）
    - バックアップ（若干手順を詳細に）
    - アップグレード（完全入れ替え）
    - データベースの更新
    - クリーンナップ

# 動作環境の確認

ＦｒｅｅＢＳＤ版Ｒｅｄｍｉｎｅ（`ports/www/redmine`）は長らく（2017/07/16～2020/06/25）、３．４をベースをベースにアップデートが行われてきた関係で、古いＲｕｂｙ（２．４）、古いＲａｉｌｓ（４．２）で稼働していた。またＲｕｂｙ２．４のＦｒｅｅＢＳＤでのサポートは、２０２０年０３月３１日をを最後に削除されたため、それ以後の新規インストールは事実上不可能であった。

Ｒｕｂｙ２．６、Ｒａｉｌｓ５．２ベースのＲｅｄｍｉｎｅ４（`ports/www/redmine4`）をインストールすることになるわけであるが、こちらはＲｅｄｍｉｎｅ４．０／４．１の流れとなる。

そしてＲｅｄｍｉｎｅ４．２（`ports/www/redmine42`）では、Ｒｕｂｙ２．７／Ｒａｉｌｓ５．２ベースとなるため、別途分岐している。

※ここではＲｕｂｙへの依存はＲｅｄｍｉｎｅのみであることを前提とし、それ以外のＲｕｂｙ依存ｐｏｒｔｓについては取り扱いを想定しない（整合性付くかは不明なので）。

※特にｐｋｇでの話となるが、デフォルトのＲｕｂｙバージョンはその時点でのｐｏｒｔｓデフォルトに準拠するため、ＲｅｍｄｉｎｅのＲｕｂｙサポートバージョンの状況によらず、変更になっている場合がある。例えば公式にはＲｅｄｍｉｎｅ４．１ではＲｕｂｙ２．６までのサポートとなっているが、現在（２０２１年１２月）はＲｕｂｙ２．７環境での稼動となる。

# バックアップ

バックアップに当たり、以下の点を確認する。

 - インストールバージョン・環境
 - インストールプラグインおよびそのバージョン
 - バックアップ対象となるデータの確認

## インストールバージョン

厳密に確認しなくても良いが、更新前後で何が変わったかを把握するため、記録に残しておくことをお勧めする。
具体的には管理者権限でＲｅｄｍｉｎｅにログインして「管理」→「情報」を表示する。

## インストールプラグイン

上記の手順と同じく「管理」→「プラグイン」を表示する。

ここでの確認はインストールされているプラグインが何であるか、そのバージョンは…といった情報を記録に残しておくことが重要であるが、それよりも、Ｒｅｄｍｉｎｅ４に対応しているかどうかが問題になる。

ただしその確認は一概には難しいので、プラグインの作者ページのリンクをたどって調べる必要がある。あるいは[プラグインディレクトリ](https://www.redmine.org/plugins)のページで、サポート状態を確認する。

プラグインが存在することに対する対応は難しいところがあるので、入れてるなら、最後、入れ忘れないようにしよう、としか言いようがないのでそのユースケースについては書かない。

## バックアップ

バックアップについては[Redmineのバックアップとリストア](http://guide.redmine.jp/RedmineBackupRestore/)を見てもらうとして、文中の「インストールディレクトリ直下の `files` ディレクトリ」は `/usr/local/www/redmine/files` を意味する。

`config/configuration.yml` は `/usr/local/www/redmine/config/configuration.yml` にある。

また各々使用しているデータベースでのバックアップを実行する。原典の資料に異存はないため、ここでは詳細は扱わない。[そちら](http://guide.redmine.jp/RedmineBackupRestore/)をチェックして欲しい。

あと個人的、別途テーマを入れてるなら、そちらのバックアップも必要であると考える。具体的には `/usr/local/www/redmine/public/themes` ディレクトリである。ただし、Ｒｅｄｍｉｎｅ本体からインストールされているテーマもあるので、要否を確認すること。

取り急ぎチェックすべきは以下のパスである。

- 確認すべきファイル
    - `/usr/local/www/redmine/config/configuration.yml`
    - `/usr/local/www/redmine/config/databases.yml`
    - `/usr/local/www/redmine/config/secrets.yml`
    - `/usr/local/www/redmine/config/initializers/secret_token.rb` ※generate_secret_tokenで生成されたファイル
- 確認すべきディレクトリ
    - `/usr/local/www/redmine/public/themes/*` ※`alternate`、`classic` を除く
    - `/usr/local/www/redmine/files/*`

`config/initializers/secret_token.rb` については[本家資料](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html#config-secrets-yml)によると `config/secrets.yml` にあるべきファイルのようであるが、指示通り差作業すると起動しない罠が…。何が正しいのか。

# アップグレード

いよいよここからｐｋｇ／ｐｏｒｔｓシステム固有となる部分。ここに関しては元の資料への参照はゼロになります。

## Ｒｅｄｍｉｎｅ３．４のアンインストール

```shell-session
pkg delete -y ruby
```

全部アンインストールしましょう。
また、`/etc/make.conf` 中の `DEFAULT_VERSIONS` から `ruby=2.4` の設定を削除すること。

## Ｒｅｄｍｉｎｅ４．１または４．２のインストール

### ｐｋｇの場合

```shell-session
pkg install -y redmine4
  または
pkg install -y redmine42
```

### ｐｏｒｔｓの場合
事前に `/etc/make.conf` 中の `DEFAULT_VERSIONS` に `ruby=2.6` または `ruby=2.7` の設定を追加すること。

```shell-session
cd /usr/ports/www/redmine4 && make install
  または
cd /usr/ports/www/redmine42 && make install
```

片っ端からインストールしましょう。
Ｘ１１が不要であれば（サーバーユースでは不要だと思うが）、`/etc/make.conf` に `OPTIONS_UNSET=X11` という行を追加しておく。

## 別途プラグインのインストール

※ｐｋｇ／ｐｏｒｔｓとしては現在存在しない点に注意

```shell-session
cd /usr/ports/www/redmine-なにか && make install
```

必要に応じて追加インストールを実施します。またこの時、インストール後の手順についてメッセージが表示されていること（ＤＢのマイグレーションなど）があるので、メッセージの指示に基づいて作業する。

自前でプラグインをインストールしている場合は、説明しようが無いため、詳細は省略。

## 注意点

- Ｒｅｄｍｉｎｅ４．０時点ではＲＭＡＧＩＣＫは使えない。
- Ｒｅｄｍｉｎｅ４．１ではＲＭＡＧＩＣＫを別の実装（ＭＩＮＩ＿ＭＡＧＩＣＫ）に置き換えたので再び使えるようになっている。

# データベースの更新

```shell-session
cd /usr/local/www/redmine && bundle exec rake db:migrate RAILS_ENV=production
```

プラグインのマイグレーションも合わせて実施する。

```shell-session
cd /usr/local/www/redmine && bundle exec rake redmine:plugins:migrate RAILS_ENV=production
```

Ｒａｉｌｓの作法に則って、何度実行しても問題無いので、サクサク実行しましょう。

# クリーンナップ

```shell-session
cd /usr/local/www/redmine && bundle exec rake tmp:cache:clear RAILS_ENV=production
```

# 再起動

キャッシュのクリアが終ったら、Ｒｅｄｍｉｎｅを再起動する。

```shell-session
service redmine stop
rm -f /usr/local/www/redmine/tmp/pids/thin.pid
service redmine start
```

まぁ大きな変更もあったことだし、一度全部、再起動してしまうのもアリ。

# よくあるトラブルとその対応

## Ｑ．５００エラーが表示されます！ どうすればいいですか？

Ａ．まずは、ログファイル（`/usr/local/www/redmine/log/production.log`）を確認しよう。
下記のようなメッセージ（特に `Completed 500 Internal Server Error`）が得られたら、問題は特定できています。

```
Started POST "/login" for XXX.XXX.XXX.XXX at 2021-12-30 03:39:36 +0900
Processing by AccountController#login as HTML
  Parameters: {"utf8"=>"✓", "authenticity_token"=>"XXXXXXXXXXXXXXXXX", "back_url"=>"/", "username"=>"nork", "password"=>"[FILTERED]", "login"=>"ログイン"}
  Current user: anonymous
Completed 500 Internal Server Error in 29ms (ActiveRecord: 2.3ms)

NameError (undefined local variable or method `twofa_scheme' for #<User:0x000000080ccbe2b0>
Did you mean?  twofa_active?):

app/models/user.rb:406:in `twofa_active?'
app/controllers/account_controller.rb:321:in `password_authentication'
app/controllers/account_controller.rb:307:in `authenticate_user'
app/controllers/account_controller.rb:41:in `login'
lib/redmine/sudo_mode.rb:61:in `sudo_mode'
```

上記ケース（`NameError (undefined local variable or method 'twofa_scheme'`）では、データベースの更新を実施していなかったのが原因（未定義を参照しようとしたエラー）なので、下記のコマンドを実行して解決する。

```shell-session
cd /usr/local/www/redmine && bundle exec rake redmine:plugins:migrate RAILS_ENV=production
```

## Ｑ．そもそもＲｅｄｍｉｎｅが立ち上がってくれません！

Ａ．まずは、ログファイル（`/log/thin.log`）を確認しよう。
下記のようなメッセージ（特に `tmp/pids/thin.pid (Errno::EACCES)`）が得られたら、問題は特定できています。

```
/usr/local/lib/ruby/gems/2.7/gems/thin-1.8.1/lib/thin/daemonizing.rb:177:in `delete': Permission denied @ apply2files - tmp/pids/thin.pid (Errno::EACCES)
        from /usr/local/lib/ruby/gems/2.7/gems/thin-1.8.1/lib/thin/daemonizing.rb:177:in `remove_pid_file'
        from /usr/local/lib/ruby/gems/2.7/gems/thin-1.8.1/lib/thin/daemonizing.rb:66:in `block in daemonize'
Exiting!
```

Ｒｅｄｍｉｎｅが立ち上がってないこと、あるいは動いている場合は停止した後、下記の通りファイルを削除します。

```console
rm -f /usr/local/www/redmine/tmp/pids/thin.pid
```

## Ｑ．ログファイルが `/log/thin.log` ってなんですか！まともな位置に置かれないのですが？

Ａ．起動ディレクトリ（＝ `/`）直下に `log/thin.log` ファイルが作成されます。これが嫌なら下記のコマンドを実行します。

```console
sysrc redmine_flags+=" -l /usr/local/www/redmine/log/thin.log"
```

# よくある質問とその答え

## Ｑ．データベースの更新が怖いです。ほんとに大丈夫ですか？
Ａ．大丈夫だ。問題無い。バックアップなんぞせんｄ（ぴー）【コンプライアンス的に以後の発言がイレースされました】

## Ｑ．データベース以外での更新ポイントは無いのですが？
Ａ．無いことも無いが、実際にはほとんど無い。`db:migrate` 実施時に、「余計なもの」についてメッセージが表示されるので、その指示に応じて対応すること。

自分は `config/email.yml` というファイルが残っていた旨、レポートされたため、`config/configuration.yml` ファイル中の設定が正しいことを確認して、`config/email.yml` を削除した。

また原書には「セッション保護用の秘密鍵を生成」という指示があるが、今時のインストールでそれをやってないことは無いと思うので無視できると思う。

極めて古いバージョン（Ｒｅｄｍｉｎｅ１等）からのアップデートを維持しているのであれば、その辺りは原書の指示を読み直す必要がある。

一度今のバージョンに合わせて見直したのであれば、以後のバージョンアップは今のバージョンを前提として更新していくことになる。何が言いたいかと言えば、旧バージョンのことは忘れてよい。

## Ｑ．データベースの更新を実施しない場合どうなりますか？
Ａ．検証してないので不明だが、カラムの変更やテーブルの変更を行っていたようなので、ある程度は動くが、ある機能を使用するとエラーになる、といった現象が発生するのでは無いかと思われる。

## Ｑ．やばい！全然データベースの更新してません！
Ａ．大丈夫だ。今からでも更新して間に合わないこともない。まとめて変更を適用だ！

## Ｑ．もしかしたらアップデートする度に、`db:migrate` と `tmp:cache:clear` しても大丈夫？
Ａ．大丈夫だ。問題無い。`redmine:plugins:migrate` も合わせて実施かな。
あまり長期間に渡って運用したことが無いので、問題になるかは不明。

# 参考文献

- [RedmineUpgrade](https://www.redmine.org/projects/redmine/wiki/RedmineUpgrade)
- [日本語版RedmineUpgrade](http://guide.redmine.jp/RedmineUpgrade/)
- [プラグインディレクトリ](https://www.redmine.org/plugins)
- [Redmineのバックアップとリストア](http://guide.redmine.jp/RedmineBackupRestore/)