Manualmaton's Laboratory

Redmine 5.1からRedmine 6.1への移行では、できるだけ本番環境へ影響を出さないよう、検証環境で一つずつ作業を進めてきました。

今回は以前のように「一気にアップグレードして問題を追う」のではなく、

• 検証環境を作る
• 問題が起きたら原因を調べる
• 記録として残す
• 次の工程へ進む

という流れで進められたため、最終的にはかなり安心して6.1環境を完成させることができました。

その途中で遭遇したのが、データベースマイグレーション時の Table already exists エラーです。

最初は単純なテーブル重複かと思いましたが、原因を追っていくとRedmine 6.0で行われた「プラグイン機能の本体統合」が関係していました。

今回は、このマイグレーションエラーの内容と対処手順を記録しておきます。

実データを流し込んだ直後にマイグレーションが止まる

今回の手順では、Redmine 5.1で整理・純化しておいたデータベースをMySQLダンプから復元し、そのままRedmine 6.1側でマイグレーションを実行しました。

cd /home/www-data/redmine_v6
sudo -u www-data RAILS_ENV=production bundle exec rake db:migrate

ところが途中で処理が停止します。

最初に止まったのは、リアクション機能です。

== 20250423065135 CreateReactions: migrating ==================================
-- create_table(:reactions)

Mysql2::Error:
Table 'reactions' already exists

この時点では、

「どこかでマイグレーションを実行し忘れたかな？」

程度に考えていました。ところが、修正して再実行すると、今度はこちら。

== 20250611092155 CreateDoorkeeperTables: migrating ===========================

Mysql2::Error:
Table 'oauth_applications' already exists

また別のテーブルが既に存在すると言われます。つまり偶然ではなく、何か共通した原因がありそうでした。

原因は「昔はプラグイン、今は標準機能」

調べてみると、どちらもRedmine 6.0で本体へ取り込まれた機能でした。

今回衝突したのは、

• リアクション機能
• OAuth認証（Doorkeeper）

の二つです。どちらも以前はプラグインとして利用していましたが、Redmine 6ではコア機能になっています。つまり、

Redmine 5.1時代

プラグイン
    ↓
DBにテーブル作成

だったものが、Redmine 6.1では、

Redmine本体
    ↓
同じ名前のテーブルを作成

という流れに変わっています。そのため、旧環境からDBを持ってくると、

既に存在するテーブルを、Redmine本体がもう一度作ろうとする

という状態になっていました。

なぜDROPしてよいのか

ここで少し悩みました。

「既存テーブルを削除してしまって本当に大丈夫なのか？」

しかし今回は、本体側へ正式に統合された機能です。つまり最終的に利用するのはRedmine本体が管理するスキーマになります。古いプラグイン時代のテーブルを残していても、最終的には使われません。

そこで今回は、競合しているテーブルだけを削除し、本体マイグレーションに改めて生成してもらうことにしました。

競合しているテーブルを削除する

MySQLから競合しているテーブルを削除します。

mysql -u redmine_v6 -p redmine_v6 -e "
DROP TABLE IF EXISTS reactions;
DROP TABLE IF EXISTS oauth_access_tokens;
DROP TABLE IF EXISTS oauth_access_grants;
DROP TABLE IF EXISTS oauth_applications;
"

これで、本体側が新しくテーブルを作れる状態になります。

改めてマイグレーションを実行する

続いて再度マイグレーションを実行します。

cd /home/www-data/redmine_v6

sudo -u www-data RAILS_ENV=production bundle exec rake db:migrate

今度は問題なく進みます。

== CreateReactions: migrated
== EnsureWikiTablesortSettingIsStoredInDb: migrated
== CreateDoorkeeperTables: migrated

最後まで完走し、正常終了しました。

プラグイン側も忘れずに更新

本体が終わったら、続いてプラグイン側のマイグレーションも実行します。

sudo -u www-data RAILS_ENV=production bundle exec rake redmine:plugins:migrate

本体だけ更新して安心しがちですが、ここまで実行して初めてプラグイン側も新しい環境へ追従できます。

configuration.ymlも忘れずに引き継ぐ

今回の環境ではSMTP設定も引き継ぐ必要がありました。

既存環境から configuration.yml をコピーします。

sudo -u www-data cp -p \
/home/www-data/redmine/config/configuration.yml \
/home/www-data/redmine_v6/config/configuration.yml

その後、Passengerを再起動します。

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

最後に管理画面からテストメールを送信し、Zoho Mail経由で正常に届くことまで確認しました。

移行後の確認

今回の検証では、最終的に以下を確認できました。

• 過去のチケット・Wiki・添付ファイルを正常に閲覧できる
• ガントチャートも問題なく表示される
• kodomo テーマもRedmine 6.1環境で正常動作
• テストメールを送信し、Zoho Mailで受信できることを確認
• DMSFを利用しなくても、標準添付機能で画像を配置できることを確認

ここまで確認できれば、検証環境としては十分安心できる状態になりました。

今回の移行を振り返って

今回のRedmine 6.1移行では、「作業そのもの」よりも「途中で何が起きたか」を残しながら進められたことが大きかったように思います。

以前であれば、エラーを解消して先へ進むことを優先していた場面でも、

• なぜ起きたのか
• Redmine側の仕様変更なのか
• プラグイン由来なのか
• 次に同じ作業をするとき、何を確認すればよいのか

という視点で整理しながら進められました。

結果として、今回遭遇した Table already exists も「たまたま起きたエラー」ではなく、Redmine 6でプラグイン機能が本体へ統合されたことによる仕様変更だと理解できました。

移行作業では、どうしてもエラーそのものへ目が向きがちですが、「なぜそのエラーが起きたのか」まで追っておくと、次回以降の作業はずっと楽になります。

今回の6.1環境は、そうした記録を積み重ねながら構築できたこともあり、これまでで一番安心して仕上げられたバージョンアップだったように感じています。

はじめに

Redmine 6.1（Rails 7.2系）の検証環境構築に続き、今回は各種UI拡張やマクロ機能の土台となる Additionals および Additional Tags プラグインを導入しました。

依存関係の親玉とも言えるこの2つのプラグインですが、最新版（main ブランチ）をそのままクローンしてマイグレーションを実行したところ、複数の予期せぬエラーに遭遇しました。

今回は、遭遇した3つのトラブルと、それを解決して Redmine 6.1 上で正常認識させるまでのメモです。

今回の前提条件

• Redmine: 6.1.4.stable (Rails 7.2.3.2)
• Ruby: 3.2.x
• 対象プラグイン:
• additionals (AlphaNodes製 / 共通ライブラリ)
• additional_tags (AlphaNodes製 / タグ機能拡張)

遭遇した3つの罠と対処法

罠1: 最新版が「Redmine 7.0以上」を要求して abort

GitHubから main ブランチをそのままクローンしてマイグレーションを実行したところ、以下のエラーが発生しました。

Redmine::PluginRequirementError: additional_tags plugin requires Redmine 7.0 or higher but current is 6.1.4.stable.25001

• 原因: リポジトリ先端（main）の開発が既に次世代の Redmine 7.0 / Rails 8系 向けに進んでおり、6.1環境が弾かれていました。
  • 対処: Redmine 6.x に対応している安定版タグ（v3.4.0 など）へチェックアウトを切り替えます。

罠2: Gitの「dubious ownership」セキュリティエラー

sudo -u www-data git checkout を実行した際、Git のセキュリティ機構（所有権チェック）に阻まれました。

fatal: detected dubious ownership in repository at '/home/www-data/redmine_v6/plugins/additionals'

• 原因: 実行ユーザーとディレクトリ所有者（www-data）の不一致による安全装置の作動。
  • 対処: www-data ユーザーの Git グローバル設定にセーフディレクトリを登録して回避しました。

sudo -u www-data git config --global --add safe.directory '*'

罠3: プラグイン依存 Gem の未調合（Could not find compatible versions）

タグを切り替えて rake redmine:plugins:migrate を実行したところ、今度は Bundler が停止しました。

Because every version of additionals depends on render_async >= 0
  and render_async >= 0 could not be found in locally installed gems,
  additionals cannot be used.

• 原因: プラグインが要求する Gem（render_async 等）が、ローカルの vendor/bundle にインストールされていませんでした。
  • 対処: マイグレーション前に必ず bundle install を通す必要があります。

成功した導入手順まとめ

1. リポジトリのクローンと安全設定

• Redmine(検証用)ルートディレクトリに移動

cd /home/www-data/redmine_v6/plugins

• プラグインのgit clone

sudo -u www-data git clone https://github.com/alphanodes/additionals.git

sudo -u www-data git clone https://github.com/alphanodes/additional_tags.git

• Git 所有権警告の解除

sudo -u www-data git config --global --add safe.directory '*'

2. Redmine 6.x 対応タグへのチェックアウト

• additionalsでチェックアウト

cd /home/www-data/redmine_v6/plugins/additionals

sudo -u www-data git checkout $(sudo -u www-data git tag -l | grep -E '^v?3\.' | tail -n 1)

• additional_tagsでチェックアウト

cd /home/www-data/redmine_v6/plugins/additional_tags

```bash
sudo -u www-data git checkout $(sudo -u www-data git tag -l | grep -E '^v?3\.' | tail -n 1)

3. 依存 Gem のローカルインストール（最重要）

cd /home/www-data/redmine_v6

sudo -u www-data bundle install

4. マイグレーションと再起動

sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production

sudo -u www-data bundle exec rake assets:precompile RAILS_ENV=production

おわりに

構築中のRedmine 6.1サイトにアクセスし、管理画面（/admin/plugins）を開くと、Additional Tags (3.4.0) と Additionals (3.4.0) が無事に認識され、エラーなく設定画面を開くことができました。

プラグイン導入時は、「最新ブランチを追うのではなく適切なリリースバージョン（タグ）を選ぶこと」と「DBマイグレーションの前に bundle install で Gem 依存を揃えること」が鉄則であると再認識させられた検証でした。

Redmine 6.xへの移行を見据え、現在運用しているRedmine 5.1とは別に、同一サーバー上へRedmine 6.1の検証環境（redmine-v6）を構築しました。

「同じサーバーなら、そのまま新しいRedmineを入れればいい」と考えがちですが、不用意にシステム全体のRuby環境やWebサーバー設定を書き換えると、既存の稼働中サービスを巻き込んで停止（500エラー等）させるリスクがあります。

今回の構築では、「Redmine 6.1を動かすこと」以上に「現在動いている既存環境（5.1）に一切影響を与えないこと」を最優先に設計しました。そのための設計思想と具体的な構築手順をまとめます。

既存環境を壊さないための3つの原則

RedmineはRubyやGem、Webサーバー（Apache）など多くの基盤を利用するRailsアプリケーションです。既存環境との共存にあたり、特に以下の3点を徹底しました。

1. sudo gem install を安易に使わず、ライブラリをプロジェクト内に隔離する
   システム全体にGemをインストールすると、既存Redmineが依存するGemバージョンと競合する恐れがあります。Bundlerを利用し、依存ライブラリはすべて検証環境のディレクトリ配下（vendor/bundle）へ閉じ込めます。
2. Bundlerの設定をローカル（プロジェクト単位）に限定する
   グローバル設定（~/.bundle/config）への書き込みを避け、bundle config set --local を使用して対象ディレクトリ内でのみ設定を完結させます。
3. Apacheの既存設定には触れず、新しいVirtualHostを追加するのみにとどめる
   既存のサイト設定（000-default.conf や既存Redmine用設定）の無効化（a2dissite）は行わず、新規VirtualHostの作成と有効化（a2ensite）だけで対応します。

検証環境・前提条件

• OS: Ubuntu 24.04 LTS
• Ruby: 3.2.x系（Ubuntu標準パッケージ / 5.1系と6.1系の両方に対応）
• DB: MySQL 8.x
• Web: Apache 2.4 + Passenger
• Redmine: 6.1-stable（新規検証用）
• パッケージ管理: aptitude（※aptでも同様に実行可能です）
• 名前解決: 検証用ドメイン/サブドメインのDNS名前解決が完了していること

多分さっくりとはしていない手順

1. Redmine-v6用のDBを作成します。
2. Redmine 6.1を配置します。
3. データベース接続設定を行います。
4. Gemの初期化と設定を行います。 （※既存環境を壊さないように注意！！！）
5. Apacheのvirtualhostを設定します。
6. 設定を反映します。
7. 動作確認を行います。

1. データベースと専用ユーザーの作成

既存のデータベースと完全に分離するため、redmine_v6 専用のDBおよびユーザーを作成します。

sudo mysql -u root -p

-- データベース作成
CREATE DATABASE redmine_v6 CHARACTER SET utf8mb4;

-- 専用ユーザー作成（パスワードは任意のものに変更してください）
CREATE USER 'redmine_v6'@'localhost' IDENTIFIED BY 'your_secure_password';

-- 権限付与
GRANT ALL ON redmine_v6.* TO 'redmine_v6'@'localhost';
FLUSH PRIVILEGES;
EXIT;

作成したユーザーで接続できるか確認します。

mysql -u redmine_v6 -p -e "SHOW DATABASES;"

2. Redmine 6.1 の配置

配置ディレクトリを既存環境と分けて作成し、ソースコードを取得します。

• ディレクトリ作成

sudo mkdir -p /home/www-data/redmine-v6

※自分の環境に合わせます。

• ディレクトリの所有者変更

sudo chown -R www-data:www-data /home/www-data/redmine-v6

• Redmine 6.1-stable の取得

sudo -u www-data svn co https://svn.redmine.org/redmine/branches/6.1-stable /home/www-data/redmine-v6

3. データベース接続設定

設定ファイルのサンプルをコピーし、先ほど作成した redmine_v6 の情報を設定します。

sudo -u www-data cp -pi /home/www-data/redmine-v6/config/database.yml.example /home/www-data/redmine-v6/config/database.yml

/home/www-data/redmine-v6/config/database.yml を編集します。

production:
  adapter: mysql2
  database: redmine_v6
  host: localhost
  username: redmine_v6
  password: "your_secure_password"
  encoding: utf8mb4

4. Gemのローカルインストールと初期化

Gemの競合を防ぐため、必ずローカル設定で vendor/bundle 配下にインストールします。

• Redmine(v6)のルートディレクトリに移動

cd /home/www-data/redmine-v6 && pwd

旧環境に移動すると偉い目に遭います。（遭いました

• Bundlerの設定をローカルに限定

sudo -u www-data bundle config set --local path 'vendor/bundle'

sudo -u www-data bundle config set --local without 'development test'

• 依存関係の調整とインストール

sudo -u www-data bundle update stringio

sudo -u www-data bundle install

• シークレットトークンの生成

sudo -u www-data bundle exec rake generate_secret_token RAILS_ENV=production

• DBマイグレーション

sudo -u www-data bundle exec rake db:migrate RAILS_ENV=production

• デフォルトデータのロード（日本語）

sudo -u www-data RAILS_ENV=production REDMINE_LANG=ja bundle exec rake redmine:load_default_data

• アセットのプリコンパイル

sudo -u www-data bundle exec rake assets:precompile RAILS_ENV=production

5. Apache VirtualHost の設定

既存の稼働中サイトには一切触れず、Redmine 6.1用の設定ファイルのみを新規作成・有効化します。

cat <<- __EOF__ | sudo tee /etc/apache2/sites-available/redmine-v6.conf
<VirtualHost *:80>
    ServerName 【v6.example.com】
    DocumentRoot /home/www-data/redmine-v6/public
    <Directory /home/www-data/redmine-v6/public>
        Options -MultiViews
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
__EOF__

※ 【v6.example.com】 はご自身の検証用ドメインに書き換えてください。
※ これはあくまでもhttpd専用であり、ログもありません。適宜、セキュリティポリシーに沿って運用します。

6. 設定の反映

• 新規サイト設定のみ有効化

sudo a2ensite redmine-v6.conf

• 構文チェック（Syntax OK を確認）

sudo apache2ctl configtest

• Apacheの再読み込み

sudo systemctl restart apache2.service

7. 動作確認

ブラウザから http://設定した検証用ドメイン にアクセスし、Redmine 6.1 のトップページが表示されれば構築完了です。

重要: 初期管理者アカウント（admin / admin）で即座にログインし、パスワードを強固なものへ変更してください。

おわりに

今回の検証環境構築では、Redmine 5.1（Rails 6.1系）とRedmine 6.1（Rails 7.2系）が共にRuby 3.2系をサポートしていたため、Ruby本体を共用しながらディレクトリ・Gem・DB・VirtualHostのレベルで環境を安全に分離できました。

サーバー運用においては、「新しい環境を動かすこと」以上に「稼働中の資産を壊さない境界線を引くこと」が重要になります。