PostgreSQLを起動するためのdocker-compose.yml

この docker-compose.yml を書く:

version: "3.8"

services:
  db:
    image: postgres:12.3
    restart: always
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password

volumes:
  db-data:

いまさら何をという感じだが、上記の docker-compose.yml を先日書こうとして、いつもフンイキで触っている Docker だけどそろそろドキュメントを読んでおくかと思い立ち、ドキュメントを頭から（飛ばし飛ばし）読んだのでメモを残したくなりました。

環境

% docker --version
Docker version 19.03.12, build 48a66213fe
% docker-compose --version 
docker-compose version 1.26.2, build eefe0d31

Docker のアーキテクチャ

https://docs.docker.com/get-started/overview/#docker-architecture

Docker uses a client-server architecture. The Docker client talks to the Docker daemon, which does the heavy lifting of building, running, and distributing your Docker containers.

Docker はクライアント-サーバモデルで動いており、 Docker クライアントが Docker デーモンと会話する。Docker デーモンが Docker コンテナたちをビルドしたり実行したり配布したりといった何やかんや大変な仕事をやってくれる。

Docker デーモン

The Docker daemon (dockerd) listens for Docker API requests and manages Docker objects such as images, containers, networks, and volumes.

Docker デーモンは Docker API リクエストを listen して、イメージ、コンテナ、ネットワーク、ボリュームといった Docker オブジェクトたちの面倒を見る。

イメージ

An image is a read-only template with instructions for creating a Docker container.

イメージはコンテナを作るための指示が書かれた読み取り専用のテンプレート。 ubuntu イメージとか redis イメージとか。

コンテナ

A container is a runnable instance of an image.

コンテナはイメージの実行可能なインスタンス。

When a container is removed, any changes to its state that are not stored in persistent storage disappear.

コンテナが remove されると、コンテナの状態に対して成された変更のうち永続ストレージに保存されていないものは消滅する。

サービス

Services allow you to scale containers across multiple Docker daemons, which all work together as a swarm with multiple managers and workers.

サービスにより複数の Docker デーモンにわたってコンテナをスケールできるようになる。 Docker デーモンたちは複数のマネージャとワーカーからなる1つの群れとして協働する。

データの永続化について

上で引用したように

When a container is removed, any changes to its state that are not stored in persistent storage disappear.

となっているわけで、コンテナがいなくなった後でも消えてほしくないアプリケーションデータはどう保持しておけば良いのかと思うのだが、ドキュメントを読んでいくと volumes を作りなさいと書かれている（というか volumes を使うことが推奨されている。他にも bind mounts と tmpfs mounts という手段があるがここでは割愛する）。

例えば https://docs.docker.com/develop/dev-best-practices/#where-and-how-to-persist-application-data に書かれているように:

Avoid storing application data in your container’s writable layer using storage drivers. This increases the size of your container and is less efficient from an I/O perspective than using volumes or bind mounts.

Instead, store data using volumes.

詳しくは https://docs.docker.com/storage/ 以下のドキュメントを読むとよい。

Docker Compose

https://docs.docker.com/compose/

Compose is a tool for defining and running multi-container Docker applications.

Docker Compose は複数コンテナからなる Docker アプリを定義して実行するためのツールである。

docker-compose.yml の中で services: というトップレベルのキーの下に各サービスを定義する。

version について

https://docs.docker.com/compose/compose-file/compose-versioning/#versioning

docker-compose.yml の書式のバージョンを指定することができる。

There are currently three versions of the Compose file format:

Version 1, the legacy format. This is specified by omitting a version key at the root of the YAML.

Version 2.x. This is specified with a version: '2' or version: '2.1', etc., entry at the root of the YAML.

Version 3.x, the latest and recommended version, designed to be cross-compatible between Compose and the Docker Engine’s swarm mode. This is specified with a version: '3' or version: '3.1', etc., entry at the root of the YAML.

ファイルの先頭に version キーを 書かない ことでバージョン1を指定したことになる。バージョン 2.x と 3.x の指定はファイルの先頭に version: '2' や vesion: '2.1' や version: '3' や vesion: '3.1' などと書くことで指定できる。

推奨バージョンは現行の 3.x である。

また Note が書かれていて

Note: When specifying the Compose file version to use, make sure to specify both the major and minor numbers. If no minor version is given, 0 is used by default and not the latest minor version.

利用する Compose ファイルのバージョンを指定する際は、メジャー ナンバーと マイナー ナンバーの両方を忘れずに指定すること。マイナーバージョンが指定されないと、最新のマイナーバージョンではなく 0 がデフォルトで使われる。

つまり version: "3" と書くとこれは version: "3.0" と書いたのと等価である。このような仕様なので、しがらみが何もなければ常に最新のマイナーバージョンを明示的に指定するのが良いだろうと思う。

image

https://docs.docker.com/compose/compose-file/#image

Specify the image to start the container from. Can either be a repository/tag or a partial image ID.

コンテナを開始する起点となるイメージを指定する。

PostgreSQL なら image: postgres とか image: postgres:12.3 とかを指定する:

https://hub.docker.com/_/postgres

volumes

上でも書いたように volumes を作ってデータを永続化させないと DB としての役目を果たすことができない。

docker-compose.yml で volumes を定義する方法はこちらに載っている:

https://docs.docker.com/compose/compose-file/#volumes

Mount host paths or named volumes, specified as sub-options to a service.

volumes は各 service のサブオプションとして指定し、ホストの path または名前つき volumes (named volumes) をマウントする。

But, if you want to reuse a volume across multiple services, then define a named volume in the top-level volumes key.

ある volume を複数 service 間で使い回したかったら、トップレベルの volumes キーの下に名前付き volume を定義して使う。

（ドキュメントを読んでみてもこのトップレベル volumes 以外の場所で named volumes を定義できるのかどうかはよくわからなかった。）

トップレベル volumes の下の各エントリは、最初に載せた docker-compose.yml の例のように空っぽでも良いのだけど、オプションを指定することもできる（空っぽの場合はデフォルトの値が適用されるということ）。オプションについて詳しくはこちらを読むと良い:

https://docs.docker.com/compose/compose-file/#volume-configuration-reference

restart

postgres の docker image のREADME.md に載っていたのをそのまま書いたという以上の経験が無い。

ドキュメントへのリンクだけ載せておく: https://docs.docker.com/compose/compose-file/#restart

environment

https://docs.docker.com/compose/compose-file/#environment

環境変数を指定する。

ちなみに

Environment variables with only a key are resolved to their values on the machine Compose is running on, which can be helpful for secret or host-specific values.

キーだけの環境変数が書かれていると Compose が実行されたそのマシンのシェルの環境変数の値に解決される。これは秘匿情報やホストに特有の値を扱うときに便利。

この情報は Reference だけでなく Product Manuals でも紹介されている:

https://docs.docker.com/compose/environment-variables/#pass-environment-variables-to-containers