UGREN NASでDocker Composeを使う方法

UGREEN NASでは、UGOS ProのDockerアプリにある「プロジェクト」機能を使って、Docker Composeで構成された複数のコンテナをまとめて管理できます。

例えば、WordPressとMySQLのように連携して動作するサービスも、Compose設定を使えば一つのプロジェクトとしてデプロイ、停止、再起動できます。

Docker Composeの対応モデル

DockerおよびDocker Composeの「プロジェクト」機能は、DXPシリーズ、DXP GTシリーズ、DH4300 Plusで利用できます。

DH2300はDockerに対応していないため、本記事の手順は実行できません。モデル別の対応状況とDockerの基本操作は、UGREEN NASでDockerを使う方法で整理しています。

本記事の要点

• UGOS Proでは、Dockerアプリの「プロジェクト」からCompose設定をデプロイできる
• DockerはDXPシリーズ、DXP GTシリーズ、DH4300 Plusで利用でき、DH2300は対応していない
• DH4300 PlusはARM64、DXPシリーズとDXP GTシリーズはx86-64のコンテナイメージを使用する
• Composeファイルはcompose.yaml、compose.yml、docker-compose.yaml、docker-compose.ymlの各ファイル名に対応する
• 複数サービスを同じネットワークで動かす場合、通常はネットワークを個別に定義する必要はない
• データを残すには、NAS上のフォルダーまたは名前付きボリュームをコンテナへマウントする
• depends_onだけではデータベースの準備完了まで待機しないため、必要に応じてヘルスチェックを組み合わせる
• 設定変更後は「再デプロイ」を実行しなければ、新しいCompose設定は反映されない

Docker Composeで何ができるのか

Docker Composeは、複数のコンテナを一つのYAMLファイルで定義し、まとめて管理する仕組みです。

UGOS Proでは、Composeで定義されたサービスの集合を「プロジェクト」として扱います。個別にコンテナを作成する場合と異なり、Webアプリ、データベース、キャッシュなどを一括して起動・停止できます。

例えば、WordPressを動かす場合は、少なくとも次の二つのサービスが必要です。

• WordPress：Webサイト本体を動かす
• MySQL：記事、ユーザー、設定などのデータを保存する

Docker Composeを使えば、両方のサービス、接続先、ポート、保存フォルダーを一つの設定ファイルにまとめられます。

UGREEN NASでDocker Composeを使う前の準備

作業を始める前に、次の準備を行います。

1. UGOS ProのアプリセンターからDockerアプリをインストールする
2. 共有フォルダー内のdockerディレクトリに、プロジェクト用フォルダーを用意する
3. 使用するポートが、別のコンテナやアプリと重複していないことを確認する
4. 既存プロジェクトを変更する場合は、設定と保存データをバックアップする

使用するイメージのCPUアーキテクチャを確認する

UGREEN NASでは、モデルによってCPUアーキテクチャが異なります。

DH4300 PlusはRockchip RK3588Cを搭載したARM64モデルです。DH4300 PlusでDockerを使用する場合は、linux/arm64またはarm64v8に対応したコンテナイメージが必要です。

{{UGPRODUCT}}

使用中のNASに対応していないイメージを指定すると、コンテナが起動直後に停止したり、ログに次のエラーが表示されたりします。

exec format error

UGREEN NASでDocker Composeを起動する手順

1．プロジェクトフォルダーを作成する

UGOS Proのファイル管理を開き、共有フォルダー内のdockerディレクトリに、次のフォルダーを作成します。

wordpress-stack

最終的な構成は次のようになります。

docker/
└─ wordpress-stack/
   ├─ compose.yaml
   ├─ .env
   ├─ mysql/
   └─ wordpress/

mysqlにはMySQLのデータ、wordpressにはWordPress本体のファイルが保存されます。

2．compose.yamlを作成する

次の内容をcompose.yamlという名前で保存します。

services:
  db:
    image: mysql:8.4.10
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    volumes:
      - ./mysql:/var/lib/mysql
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "mysqladmin ping -h localhost -uroot -p\"$${MYSQL_ROOT_PASSWORD}\" --silent"
        ]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

  wordpress:
    image: wordpress:7.0.1-apache
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "${WORDPRESS_PORT}:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${MYSQL_DATABASE}
      WORDPRESS_DB_USER: ${MYSQL_USER}
      WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - ./wordpress:/var/www/html

3．環境変数を設定する

compose.yamlと同じフォルダーに、.envというファイルを作成します。

WORDPRESS_PORT=8080
MYSQL_DATABASE=wordpress
MYSQL_USER=wordpress_user
MYSQL_PASSWORD=replace-with-a-long-random-password
MYSQL_ROOT_PASSWORD=replace-with-another-long-random-password

MYSQL_PASSWORDとMYSQL_ROOT_PASSWORDは、そのまま使用せず、それぞれ異なる長いパスワードへ変更してください。

.envは設定値をComposeファイルから分離するために使用しますが、暗号化された保管場所ではありません。次の点に注意してください。

• .envを他人と共有しない
• 公開リポジトリへアップロードしない
• バックアップ時にアクセス権を制限する
• パスワードを記事や画面のスクリーンショットに表示しない

4．UGOS Proでプロジェクトを作成する

1. UGOS Proで「Docker」アプリを開く
2. 左側のメニューから「プロジェクト」を開く
3. 「作成」をクリックする
4. プロジェクト名にwordpress-stackと入力する
5. 保存先として、作成したdocker/wordpress-stackフォルダーを指定する
6. 「Compose設定」でcompose.yamlを読み込む
7. 表示されたYAMLの内容を確認する
8. 「今すぐデプロイ」をクリックする

デプロイを開始すると、UGOS Proが必要なイメージをダウンロードし、MySQLとWordPressのコンテナを順番に作成します。

5．プロジェクトの状態を確認する

プロジェクト作成後は、プロジェクト名をダブルクリックするか、右側の「…」から「コンソール」を開きます。

コンソールでは、次の情報を確認できます。

• コンテナ：プロジェクト内のコンテナと実行状態
• リソース監視：CPUとメモリの使用状況
• ログ：起動処理やエラーの内容
• Compose設定：現在適用されているYAML

dbとwordpressの両方が実行中になったら、同じLANに接続しているPCのブラウザから次のURLへアクセスします。

http://NASのIPアドレス:8080

WordPressの初期設定画面が表示されれば、Composeプロジェクトは正常に動作しています。

この時点ではLAN内での動作確認に留め、ルーターのポート転送を使ってWordPressを直接インターネットへ公開しないでください。外出先から利用する場合は、UGREENlink・DDNS・Tailscaleによるリモートアクセス方法を比較し、安全な接続経路を選びます。

compose.yamlの主要項目

services

servicesには、プロジェクトを構成する各サービスを定義します。

services:
  db:
  wordpress:

dbとwordpressがサービス名です。

image

imageには、コンテナの作成に使用するDockerイメージを指定します。

image: mysql:8.4.10

ports

portsは、NAS側のポートとコンテナ側のポートを対応させる設定です。

ports:
  - "${WORDPRESS_PORT}:80"

.envでWORDPRESS_PORT=8080と設定しているため、実際には次のポートマッピングになります。

NASの8080番ポート → WordPressコンテナの80番ポート

volumes

volumesは、NAS上の保存場所をコンテナ内のフォルダーへ割り当てます。

volumes:
  - ./mysql:/var/lib/mysql

./mysqlはNAS側のフォルダーです。./はComposeファイルが保存されているプロジェクトフォルダーを表します。

/var/lib/mysqlは、MySQLコンテナ内のデータ保存先です。

environment

environmentは、コンテナへ渡す設定値を定義します。

environment:
  MYSQL_DATABASE: ${MYSQL_DATABASE}
  MYSQL_USER: ${MYSQL_USER}

${MYSQL_DATABASE}などの値は、同じプロジェクトフォルダーにある.envから読み込まれます。

パスワード、APIキー、トークンなどを、公開するComposeファイルへ直接書かないでください。

depends_on

depends_onは、サービスの起動順序を制御します。

depends_on:
  db:
    condition: service_healthy

単純に次のように書いた場合、

depends_on:
  - db

MySQLコンテナが先に起動しますが、データベースが接続可能になるまで待機するわけではありません。

healthcheck

healthcheckは、コンテナ内のサービスが正常に応答できるかを確認する設定です。

healthcheck:
  test:
    [
      "CMD-SHELL",
      "mysqladmin ping -h localhost -uroot -p\"$${MYSQL_ROOT_PASSWORD}\" --silent"
    ]
  interval: 10s
  timeout: 5s
  retries: 10
  start_period: 30s

コンテナが「実行中」であっても、内部のデータベースが初期化中で接続できない場合があります。ヘルスチェックを組み合わせることで、起動直後の接続エラーを減らせます。

$${MYSQL_ROOT_PASSWORD}のようにドル記号を二つ重ねているのは、Compose側で変数を展開せず、コンテナ内の環境変数としてMySQLへ渡すためです。

restart

restartは、コンテナが停止した場合の再起動方針を指定します。

restart: unless-stopped

unless-stoppedを設定すると、ユーザーが明示的に停止した場合を除き、コンテナの異常終了時やNASの再起動後に自動起動します。

NAS上のフォルダーと名前付きボリュームの違い

Docker Composeでは、主に二つの方法でデータを永続化できます。

名前付きボリュームを使用する場合は、サービス内の指定だけでなく、ファイル末尾にトップレベルのvolumes宣言が必要です。

services:
  db:
    image: mysql:8.4.10
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

名前付きボリュームは、通常のdocker compose downでは削除されません。

一方、次のコマンドは名前付きボリュームまで削除します。

docker compose down -v

データベースの保存先に名前付きボリュームを使っている場合、-vを付けると保存データを失う可能性があります。データを残す必要があるプロジェクトでは実行しないでください。

Compose設定を変更する方法

ポート、保存先、環境変数、イメージタグなどを変更する場合は、次の手順で操作します。

1. Dockerアプリで「プロジェクト」を開く
2. 対象プロジェクトの右側にある「…」をクリックする
3. 「コンソール」を開く
4. 「Compose設定」タブへ切り替える
5. YAMLを編集する
6. 「再デプロイ」をクリックする
7. コンテナとログを確認する

YAMLを編集しただけでは、実行中のコンテナへ新しい設定は反映されません。必ず「再デプロイ」を実行してください。

再デプロイでは、設定変更の対象となるコンテナが再作成される場合があります。サービスが一時的に停止するため、利用者が少ない時間帯に実施してください。

よく使うDocker Composeコマンド

UGOS Proでは、「プロジェクト」画面から起動、停止、再起動、ログ確認を行えるため、通常はコマンド操作を必要としません。

ターミナルからComposeを管理する場合は、次のコマンドを使用します。

docker compose up -d

プロジェクトをバックグラウンドで起動します。

docker compose up -d

正しい書き方はdocker compose up -dです。docker compose -dだけでは、起動する処理が指定されていません。

-fでComposeファイルを指定する

現在のフォルダー以外にComposeファイルがある場合や、別のファイル名を使用している場合は-fで指定します。

docker compose -f compose.yaml up -d

複数のComposeファイルを重ねて使用する場合は、-fを複数指定できます。

docker compose -f compose.yaml -f compose.override.yaml up -d

後から指定したファイルの設定が、先に指定した設定へ追加または上書きされます。

-pでプロジェクト名を指定する

-pはComposeプロジェクトの名前を指定するオプションです。

docker compose -p wordpress-stack up -d

同じCompose設定を複数の環境で実行する場合や、プロジェクト名の重複を避けたい場合に使用します。

configで設定を検証する

Composeファイルを変更した後は、起動前に次のコマンドで設定を検証します。

docker compose config

YAMLのインデント、変数の展開、サービス定義に問題がある場合は、エラー内容が表示されます。

Docker Composeプロジェクトが起動しない場合

YAMLのインデントを確認する

YAMLでは、同じ階層のインデントを統一する必要があります。

ポートの重複を確認する

次のようなエラーが表示された場合、指定したNAS側のポートを別のアプリやコンテナが使用しています。

port is already allocated

.envのWORDPRESS_PORTを未使用のポートへ変更し、再デプロイしてください。

.envが読み込まれているか確認する

次のような変数が空になっている場合、.envが読み込まれていません。

MYSQL_PASSWORD: ${MYSQL_PASSWORD}

確認するポイントは次のとおりです。

• ファイル名が正確に.envになっているか
• .env.txtになっていないか
• compose.yamlと同じプロジェクトフォルダーにあるか
• 変数名の大文字と小文字が一致しているか
• 変数名の前後に不要な空白がないか

保存フォルダーの権限を確認する

コンテナに書き込み権限がない場合、データベースやアプリケーションが起動直後に停止することがあります。

特にMySQLのようにデータディレクトリへ継続的に書き込むサービスでは、NAS側フォルダーの所有者と権限が正しく設定されている必要があります。

コンソールの「ログ」で、次のエラーが表示されていないか確認してください。

Permission denied

Read-only file system

使用するイメージがPUIDとPGIDを要求する場合は、UGOS Proで利用するユーザーのユーザーIDとグループIDを指定します。

本記事で使用するDocker公式のWordPressとMySQLイメージでは、PUIDとPGIDの環境変数を追加する必要はありません。権限エラーが発生した場合は、環境変数を追加するのではなく、NAS側のマウント先フォルダーの所有者と書き込み権限を確認します。

イメージのCPUアーキテクチャを確認する

ログに次のエラーが表示される場合、指定したイメージがNASのCPUアーキテクチャに対応していない可能性があります。

exec format error

DH4300 Plusではlinux/arm64またはarm64v8、DXPシリーズとDXP GTシリーズではlinux/amd64に対応したイメージを使用します。

コンテナ間の接続先を確認する

同じComposeプロジェクト内では、通常、コンテナ名やNASのIPアドレスではなく、サービス名を接続先として使用します。

本記事では、WordPressからMySQLへ次の接続先を使用しています。

WORDPRESS_DB_HOST: db:3306

dbは、services内で定義したMySQLのサービス名です。

ログを確認する

起動失敗の原因は、プロジェクトコンソールの「ログ」で確認できます。

特に次の内容を確認してください。

• イメージのダウンロード失敗
• CPUアーキテクチャに対応していないイメージ
• ポートの重複
• パスワードや環境変数の不足
• 保存フォルダーの権限エラー
• データベースへの接続失敗
• ヘルスチェックの失敗

エラーを修正した後は、「Compose設定」から「再デプロイ」を実行します。

Composeプロジェクトのデータをバックアップする

コンテナを再作成できても、WordPressの記事やMySQLのデータが自動的に復元されるわけではありません。

バックアップ対象には、少なくとも次の二つを含めます。

• compose.yamlと.env
• WordPressとMySQLの永続データ

ただし、稼働中のMySQLデータフォルダーをそのままコピーするだけでは、整合性のあるバックアップにならない場合があります。

MySQLはmysqldumpなどを使用して論理バックアップを作成するか、プロジェクトを安全に停止してからファイル単位のバックアップを行ってください。

.envにはパスワードが含まれるため、バックアップ先のアクセス権も制限します。

Dockerイメージを更新する

UGOS Proでは、Dockerアプリの「管理」で「更新検出」を有効にすると、プロジェクトで使用しているイメージの更新を検出できます。

ただし、本記事のようにwordpress:7.0.1-apacheやmysql:8.4.10とバージョンを固定している場合、新しいバージョンが公開されても自動的に別のタグへ切り替わりません。

新しいバージョンへ更新する場合は、次の手順で操作します。

1. 現在のCompose設定とイメージタグを記録する
2. WordPressとMySQLのデータをバックアップする
3. 新しいイメージのリリース内容と互換性を確認する
4. Compose設定内のイメージタグを変更する
5. 「再デプロイ」を実行する
6. コンテナ、ログ、WordPressの動作を確認する

更新後に問題が発生した場合に戻せるよう、正常に動作していたイメージタグを記録しておくことが重要です。

UGOS Proの「一括更新」を使用する場合も、更新前にバックアップを作成してください。プロジェクトの再構築中は、一時的にサービスが停止します。

Docker Composeに関するよくある質問

docker compose -dとdocker compose up -dは何が違いますか？

プロジェクトをバックグラウンドで起動する正しいコマンドは、docker compose up -dです。

upがコンテナを作成・起動するサブコマンドで、-dはバックグラウンド実行を指定するオプションです。docker compose -dだけでは起動処理が指定されていません。

depends_onを設定すれば、データベースの準備完了まで待機しますか？

単純なdepends_onはコンテナの起動順序を制御しますが、データベースが接続可能になるまで待機するわけではありません。

データベースの準備完了を待つには、依存先サービスにhealthcheckを設定し、condition: service_healthyを組み合わせます。

docker compose downを実行してもデータは残りますか？

バインドマウントや名前付きボリュームに保存したデータは、通常のdocker compose downでは削除されません。

ただし、名前付きボリュームを使用している状態でdocker compose down -vを実行すると、そのボリュームも削除されます。データベースなどの重要なデータが保存されている場合は、-vを付けないでください。

まとめ

UGREEN NASでは、UGOS ProのDockerアプリにある「プロジェクト」を使うことで、Docker Composeの設定を画面上からデプロイできます。

Dockerを利用できるのは、DXPシリーズ、DXP GTシリーズ、DH4300 Plusです。DH2300はDockerに対応していないため、Composeプロジェクトは作成できません。