jkawamoto/roadie

---
title: プログラムの実行
description: >-
  本ドキュメントでは、Roadie がどのようにクラウドコンピューティンブ環境でユーザプログラムを
  実行しているのかについて紹介し、スクリプトファイルの記述方法を説明します。
date: 2016-08-14
lastmod: 2017-10-10
slug: execution
---
### スクリプトファイル
スクリプトファイルは、`apt`, `source`, `data`, `run`, `upload` の 5要素からなる
YAML ファイルです。
簡単なサンプルファイルは次のようになります。

```yaml
apt:
  - unrar
source: https://github.com/abcdefg/some-program.git
data:
  - http://mmnet.iis.sinica.edu.tw/dl/wowah/wowah.rar
run:
  - unrar x -r wowah.rar
  - ./analyze WoWAH
upload:
  - *.png
```

大雑把にいうと、上記のスクリプトファイルは次のことを実行します。

1. apt パッケージの `unrar` をインストールします,
2. ソースコードを Git リポジトリからクローンします,
3. ある URL からデータファイルをダウンロードします、
4. 二つのコマンド、ダウンロードしたファイルの解凍と解析プログラムの実行を行います、
5. 計算結果として、標準出力に書かれたメッセージと `*.png` にマッチするファイルを
  クラウドストレージへアップロードします。

なお、スクリプトファイルでは、不要なセクションは省略できます。


#### apt セクション
`apt` セクションはプログラムの実行に必要な apt パッケージのリストを設定します。

```yaml
apt:
  - python-numpy
  - python-scipy
  - python-matplotlib
```

上の例では、科学技術計算によく用いられる Python パッケージをインストールしています。
もし、何らかのコマンドを実行した後で apt パッケージのインストールが必要な場合は、
`run` セクションに `apt-get install` コマンドを追加してください。


#### source セクション
`source` セクションでは、プログラムで必要となるデータファイルの URL リストを指定できます。
これらの URL には次の拡張が利用できます。

- URL が `.git` で終わる場合、Git リポジトリとして扱われます。
  すなわち、ソースコードの取得に `git clone` が使われます。
- URL が `dropbox://` で始まる場合、ソースコードは
  [Dropbox](https://www.dropbox.com/) にあるとみなされます。
  この URL は、Dropbox 上で作成された公開リンクの、`https` を `dropbox` へ
  書き換えたものです。
- URL が `gs://` で始まる場合、そのリソースは Google Cloud Storage 上に
  あるとみなされます。(Google Cloud Platform 利用時のみ)
- URL が `roadie://` で始まる場合、そのリソースはRoadie が管理するファイルを指します。
  詳しくは[ファイルの管理](ja/data)を参照ください。
- それ以外では、`http` と `https` から始まる URL をサポートしています。

どの場合でも、URL が `.zip`, `.tar` または `.tar.gz` で終わる場合、
適切に解凍されます。

例えば、

```yaml
source: https://github.com/jkawamoto/roadie.git
```

は、Github からソースコードをクローンして利用します。

しかし、プログラムが開発途中の場合など、
アーカイブを作成してどこかに配置することが手間な場合もあります。
Roadie は、ローカルにあるファイルをクラウドストレージにアップロードして、
それらをソースコードとして利用する機能も提供しています。
詳細は、後の節を参照してください。

`source` セクションで指定されたソースファイルは、
仮想マシン上の `/data` にコピーされます。
また、ソースファイルが Python で記載されていて、
`requirements.txt` ファイルを含む場合、依存パッケージは自動でインストールされます。


#### data セクション
`data` セクションでは、プログラムの実行に必要なデータファイルの取得先
URL リストを指定します。
URL には、`source` セクションで説明した、
`http`、`https`、`gs` (Google Cloud Platform 利用時のみ)、
`roadie` そして `dropbox` のスキームが利用できます。
また、同様に URL が `.zip`, `.tar` または `.tar.gz` で終わっている場合、
適切に解凍されます。

デフォルトでは、指定されたファイルは `/data` ディレクトリにコピーされます。
もし他のディレクトリに保存する必要がある場合、
URL に `:` に続けて保存先パスを与えることができます。
例えば、

```yaml
data:
  - https://www.sample.com/program.zip:/data/input
```

は、`program.zip` をダウンロードし、
解凍して得られたファイルを `/data/input` にコピーします。
URL が指すファイルがアーカイブでない場合、別名保存になります。
例えば、

```yaml
data:
  - roadie://data/some_data_v2.json:some_data.json
```

は、Roadie 管理下の `some_data_v2.json` をダウンロードし、
`some_data.json` という名前で `/data` に保存します。

なお、`roadie://data/` は、`roadie data put` コマンドにてアップロードしたデータファイルの
格納先です。


#### run セクション
`run` セクションには、実行するコマンドを順に記述します。
ここには、任意のコマンドを列挙することができます。
例えば、プログラムの実行に必要な追加パッケージがある場合は、
ここでインストールを支持することができます。

例えば、[node.js](https://nodejs.org/en/) 用のアプリケーションの場合、
`run` セクション最初のコマンドは `npm install` になるでしょう。
この時、`apt` セクションで node.js をインストールするのを忘れないでください。

`source` セクションで指定したソースファイルを実行する場合、
各コマンドを `./` で始めることを忘れないでください。
`roadie` は自動で `/data` をパスへは追加しません。

`run` セクションに列挙された各コマンドには、0 から順に番号が割り当てられます。
つまり、最初のコマンドは 0 番になります。
このこ番号は、標準出力へ書き出されたメッセージの参照に利用します。
*i* 番目のコマンドの出力は `stdout{i}.txt` としてクラウドストレージに保存されます。
これらのファイルは `roadie result` コマンドで取得できます。


#### upload セクション
`upload` セクションには、
[glob](https://en.wikipedia.org/wiki/Glob_(programming))
パタンのリストを設定します.
いずれかのパタンにマッチしたファイルは、
プログラムの実行結果としてクラウドストレージで保存されます。
これらのファイルも `roadie result` コマンドで取得できます。


### プログラムの実行モデル
Roadie は、与えらえたプログラムを Docker コンテナを用いて実行します。

[![Docker](img/small_h-trans.png)](https://www.docker.com/)

このコンテナは、[Ubuntu](http://www.ubuntu.com/) を基にしたカスタムイメージを使用しており、
Ubuntu で利用可能なほとんどのパッケージが Roadie でも利用可能です。
スクリプトファイルの `apt` セクションで利用したいパッケージを登録することができます。

実行中のコンテナでは、プログラムは `/data` にコピーされます。
また、スクリプトファイルの `data` セクションで列挙されたデータファイルも、
デフォルトでは `/data` にコピーされます。

もし、ソースコードをアーカイブファイルとして用意し、
Roadie がソースコードが見つからないというエラーを出した場合、
アーカイブがディレクトリを生成しないか確認してください。
例えば、`main` という名前のプログラムをアーカイブした `archive.zip`
というファイルがある場合、解凍後は `/data/main` に `main` がコピーされる場合と、
`/data/archive/main` が作成される場合があります。
デバッグのためには、スクリプトの `run` セクションに `ls -la` などを追加すれば良いでしょう。

一般的に、プログラムは標準出力 `stdout` と標準エラー出力 `stderr` に
メッセージを書き出すことができます。
また、任意のファイルを作成することもできます。

Roadie では、標準出力 `stdout` に書き出されたメッセージは、
プログラムの実行結果として扱われ永続的なストレージに保存されます。
スクリプトファイルの `run` セクションに書かれたコマンドは、
0番から順に番号を振られます。
各コマンドが標準出力へ書き出したメッセージは `stdout{番号}.txt` という名前で保存されます。
コンテナ上では、`/tmp` に各ファイルが記録されるので、
他のコマンドから利用することもできます。

一方、標準エラー出力 `stderr` に書き出されたメッセージは、
即時性のあるログとして扱われ永続的なストレージに保存されるとは限りません。
その代わり、プログラムの実行中に `roadie log` コマンドを使って取得することができます。
標準エラー出力は通信を発生させるため、巨大なメッセージを書き出すことは避けた方が良いでしょう。

デフォルトでは、Roadie は他のファイルをプログラムの実行結果としては扱いません。
標準出力以外の出力を実行結果として永続的なストレージへ保存する場合は、
スクリプトの `upload` セクションを使ってください。


### run コマンド
`roadie run` コマンドは、新しい仮想マシンを作成しその上でプログラムを実行します。
このコマンドは、次の節で説明するスクリプトファイルを引数として受け取ります。
その他、多数のオプションが用意されていますが、
最も重要なオプションの一つに `--name` オプションがあります。
このオプションを用いることで、作成する仮想マシンに名前を付けることができ、
また実行結果の取得にもこの名前を使用します。
なお、`--name` オプションが与えれれない場合は、
スクリプトファイル名から一意の名前を生成します。

スクリプトファイルが `script.yml` で名前が `instance1`
である仮想マシンを作成するためには、

```shell
$ roadie run --name instance1 script.yml
```

を実行します。

`roadie run` コマンドに `-f` または `--follow` フラッグをセットすると、
インスタンスを作成したのち、プログラムの実行が終了するまでログを出力します。
これは、`roadie log --follow` コマンドを別途実行するのと同じです。
ただし、ログの取得が課金対象の場合や一定時間内に取得できるログの回数に制限がある場合があります。


### ローカルファイルをソースコードとして使用する
`source` セクションでは、Web 上の様々なところから
ソースコードを取得できるようになっています。
しかし、プログラムが開発途中である場合など、Web 上に配置することが手間な場合もあります。
Roadie では、ローカルにあるファイルをクラウドストレージへアップロードし、
それらをソースコードとして利用する仕組みが備わっています。

この機能を使う場合、スクリプトファイルの `source` セクションは省略できます。

ローカルディレクトリをソースコードとして使用する場合、
`roadie run` コマンドに `--local` フラッグを用いてローカルディレクトリを指定します。

例えば、

```shell
$ roadie run --local . --name instance-1 script.yml
```

では、カレントディレクトリ以下のファイルがソースコードとして扱われます。
これらのファイルはアーカイブされ、クラウドストレージにアップロードされます。
そして、そのアーカイブをソースコードとする仮想マシンを作成し実行します。

なお、指定したディレクトリに `.git` フォルダが含まれている場合、
このフォルダは無視されます。
通常、リポジトリ全体がプログラムの実行に必要なケースは稀であるため、
通信データ量を削減するために除外しています。

もし、`--local` フラッグでディレクトリではなく単一のファイルを指定した場合は、
そのファイルをソースファイルとして扱います。

この `--local` フラッグを利用してアップロードされたソースファイルは、
再利用することができます。
ソースコードの変更なしに、別のパラメータでプログラムを実行させたい場合などに便利です。
ソースコードの再利用には、`--source` と共に、再利用したい仮想マシンの名前を渡します。

例えば、`--local` フラッグを使って、次のようにプログラムを実行したとします。

```shell
$ roadie run --local . --name instance-1 script.yml
```

この時にアップロードされたソースコードを再利用する場合、

```shell
$ roadie run --source instance-1 --name instance2 script2.yml
```

のように指定します。