v1.1.0

terashim · May 29, 2022 · 897c0b7 · 897c0b7
1 parent 69ec269
commit 897c0b7
Show file tree

Hide file tree

Showing 14 changed files with 433 additions and 223 deletions.
diff --git a/.Renviron b/.Renviron
diff --git a/.devcontainer/.env.example b/.devcontainer/.env.example
@@ -1,49 +1,110 @@
-# PROJECT_PATH_HOST
+# ------------------------------
+# Workspace folder paths
+# ------------------------------
+
+# LOCAL_WORKSPACE_FOLDER
 #
-# the project root path in the Docker host.
+# Path of the workspace folder in the Docker host.
 #
-PROJECT_PATH_HOST=..
+# Examples:
+# default)
+#     LOCAL_WORKSPACE_FOLDER=..
+# 1)
+#     LOCAL_WORKSPACE_FOLDER=../..
+# 2)
+#     LOCAL_WORKSPACE_FOLDER=../subdir
 
-# PROJECT_PATH_CONTAINER
+# CONTAINER_WORKSPACE_FOLDER
 #
-# the project root path in the Docker contaienr.
+# The target workspace folder in the container.
 #
-PROJECT_PATH_CONTAINER="/home/rstudio/project"
+# Examples:
+# default)
+#     CONTAINER_WORKSPACE_FOLDER=/home/rstudio/project
+# 1)
+#     CONTAINER_WORKSPACE_FOLDER=/home/rstudio/your-project-name
 
-# DOTFILES_DIR_HOST
+# ------------------------------
+# renv global packge cache
+# ------------------------------
+
+# RENV_PATHS_CACHE_HOST
 #
-# the dotfiles path in the Docker host.
+# The renv global package cache directory path in the Docker host
+# Cf. https://rstudio.github.io/renv/articles/docker.html#running-docker-containers-with-renv
 #
-# Example: dotfiles within the project
-DOTFILES_DIR_HOST=./dotfiles
+# Examples:
+# default)
+#     RENV_PATHS_CACHE_HOST=./data/renv/cache
+# 1) the standard path for macOS
+#     RENV_PATHS_CACHE_HOST="~/Library/Application Support/renv/cache"
+# 2) the standard path for Linux
+#     RENV_PATHS_CACHE_HOST="~/.local/share/renv/cache"
+
+# RENV_PATHS_CACHE_CONTAINER
 #
-# Example: disable mounted dotfiles.
-# DOTFILES_DIR_HOST=/dev/null
+# The renv global package cache directory path in the contaienr
 #
-# Example: mount your own dotfiles.
-# DOTFILES_DIR_HOST=/path/to/dotfiles
+# Examples:
+# default)
+#     RENV_PATHS_CACHE_CONTAINER=/home/rstudio/.local/share/renv/cache
 
-# DOTFILES_DIR_CONTAINER
+# ------------------------------
+# dotfiles
+# ------------------------------
+
+# DOTFILES_DIR_HOST
 #
-# the dotfiles path in the contaienr.
-DOTFILES_DIR_CONTAINER="/home/rstudio/.dotfiles"
+# The source dotfiles path to mount into the container
+#
+# Examples:
+# default)
+#     DOTFILES_DIR_HOST=./dotfiles
+# 1) disable mounted dotfiles (to avoid conflict with VS Code dotfiles setting)
+#     DOTFILES_DIR_HOST=/dev/null
+# 2) mount your own dotfiles
+#     DOTFILES_DIR_HOST=/path/to/your/dotfiles
 
-# RENV_PATHS_CACHE_HOST
+# DOTFILES_DIR_CONTAINER
 #
-# renv cache path in the Docker host
-# Cf. https://rstudio.github.io/renv/articles/docker.html#running-docker-containers-with-renv
+# The target path to mount dotfiles
 #
-# Example: renv cache within the project
-RENV_PATHS_CACHE_HOST=./data/renv/cache
+# Examples:
+# default)
+#     DOTFILES_DIR_CONTAINER=/mnt/dotfiles
+# 1)
+#     DOTFILES_DIR_CONTAINER=/home/rstudio/dotfiles
+
+# DOTFILES_INSTALL_COMMAND
 #
-# Example: macOS default renv cache path
-# RENV_PATHS_CACHE_HOST="~/Library/Application Support/renv/cache"
+# Examples:
+# default)
+#     DOTFILES_INSTALL_COMMAND="bash /mnt/dotfiles/install.sh"
+# 1) disable installing
+#     DOTFILES_INSTALL_COMMAND=":"
+# 2)
+#     DOTFILES_INSTALL_COMMAND="/home/rstudio/dotfiles/install.sh"
+
+# ------------------------------
+# SSH Agent
+# ------------------------------
 
 # SSH_AUTH_SOCK_HOST
 #
-# SSH Agent socket in the Docker host.
+# The ssh-agent socket path in the Docker host.
+# You don't have to configure this variable if you use VS Code Remote - Container.
+#
+# Examples:
+# default) disabled.
+#     SSH_AUTH_SOCK_HOST=/dev/null
+# 1) Docker Desktop for macOS
+#     SSH_AUTH_SOCK_HOST=/run/host-services/ssh-auth.sock
+
+# SSH_AUTH_SOCK_CONTAINER
 #
-SSH_AUTH_SOCK_HOST=
+# The ssh-agent socket path in the container.
+# You don't have to configure this variable if you use VS Code Remote - Container.
 #
-# Example: Docker Desktop for Mac (https://docs.docker.com/desktop/mac/networking/#ssh-agent-forwarding)
-# SSH_AUTH_SOCK_HOST=/run/host-services/ssh-auth.sock
+# Examples:
+# default)
+#     SSH_AUTH_SOCK_CONTAINER=/run/host-services/ssh-auth.sock
diff --git a/.devcontainer/NEWS.md b/.devcontainer/NEWS.md
@@ -1,3 +1,10 @@
+# 2022/05/29
+
+- renv のバージョンを 0.15.5 に修正
+- README を修正
+- docker-compose.yml を compose.yml に変更
+- .env.example のコメントを修正
+- コンテナにインストール済みの renv でプロジェクトをロードするよう修正
 
 # 2022/05/03
 

diff --git a/.devcontainer/README-ja.md b/.devcontainer/README-ja.md
@@ -0,0 +1,163 @@
+R プロジェクト用の Docker 開発環境設定
+==================================================
+
+## 特長
+
+- Git と GitHub
+- Docker と Docker Compose
+- RStudio Server
+- renv
+- dotfiles
+- Visual Studio Code Remote - Containers
+
+## 使い方
+
+### プロジェクトの作成
+
+GitHub でこのテンプレートリポジトリ [`terashim/rproject`](https://github.com/terashim/rproject) から新しいリポジトリ（例: `your-org/your-rproject`）を作成する。または、単にこの `.devcontainer` フォルダを既存のプロジェクトにコピーする。
+
+### ローカルマシンのセットアップ
+
+- Docker をインストールする
+- SSH をインストールする
+- Git をインストールする
+- GitHub の SSH 鍵認証の準備を行う
+- SSH Agent を有効化し、鍵を追加する
+- VS Code と Remote - Container 拡張をインストールする
+- プロジェクトのリポジトリ（例: `your-org/your-rproject`）をローカルマシン上にクローンする（例: `~/ghq/github.com/your-org/your-rproject`）。
+
+## ワークフロー
+
+### コンテナの起動と終了
+
+ローカルマシン上で Docker デーモンが起動しているものとする。
+
+1. VS Code でローカルリポジトリを開く。
+2. ショートカットキー Ctrl/Cmd+Shift+P でコマンドパレットを開き、"Reopen folder in container" を選んで RStudio Server のコンテナを起動する。
+3. ブラウザで <http://localhost:8787> を開き、RStudio Server に接続する。
+4. RStudio Server 上で分析や開発の作業を行う。
+5. コンテナを停止するには、VS Code のウィンドウを閉じる。
+
+### Git によるバージョン管理
+
+- Git でソースコードのバージョン管理を行う。
+- Docker ホストにインストールされた Git を使っても良い。
+- コンテナにインストールされた Git を RStudio や VS Code から使っても良い。
+- GitHub でチームにコードを共有する。
+
+### renv によるパッケージ管理
+
+- 設定ファイル [`renv/settings.dcf`](../renv/settings.dcf) により、このプロジェクトでは ["explicit" なスナップショットタイプ](https://rstudio.github.io/renv/articles/renv.html#explicit-snapshots) がデフォルトになっている。
+- このプロジェクトで新しいパッケージを使うには、まずそれを [`DESCRIPTION`](../DESCRIPTION) ファイルに書き込んでから `renv::install()` と `renv::snapshot()` を実行する。
+- `renv::snapshot()` で生成された [`renv.lock`](../renv.lock) ファイルを GitHub にプッシュすることによってチームに共有し、同じパッケージのバージョンが再現されるようにする。
+
+## 設定
+
+### .env ファイルによるカスタマイズ
+
+[`.env.example`](./.env.example) を `.env` ファイルにコピーして、それを編集することにより
+[`compose.yml`](./compose.yml.) で使われる環境変数を変更する。
+この `.env` ファイルは Git で追跡されないので、他の環境に影響を与えることなくローカル環境の設定を行うことができる。
+
+### renv パッケージキャッシュ
+
+デフォルトでは、ダウンロードされたパッケージがマウントされたディレクトリ [`./data/renv/cache`](./data/renv/cache) にキャッシュされる。このキャッシュディレクトリはこのプロジェクトに固有で、他のプロジェクトとは共有されない。
+
+キャッシュされたパッケージが他のプロジェクトでも再利用できるようにするため、マシン上に１つのグローバルなパッケージキャッシュを使うことが推奨されている。
+例えば、macOS の場合は `~/Library/Application Support/renv/cache` が標準的なパスとなる。
+このグローバルキャッシュのパスを指定するには、`.env` ファイルで例えば
+
+```
+RENV_PATHS_CACHE_HOST="~/Library/Application Support/renv/cache"
+```
+
+のようにして変数 `RENV_PATHS_CACHE_HOST` を設定する。
+
+詳しくは <https://rstudio.github.io/renv/articles/renv.html#cache> を参照のこと。
+
+### RStudio と Git のグローバル設定
+
+RStudio の設定は "Tools" > "Global Options" の画面で通常通り変更できる。
+デフォルトではその変更内容が [`./dotfiles/.config/rstudio/`](./dotfiles/.config/rstudio/) フォルダにある設定ファイルに保存される。
+
+また、コンテナ内で `git config --global` コマンドを使って Git グローバル設定を行うと、デフォルトではそれが [`./dotfiles/.config/git/`](./dotfiles/.config/git/) フォルダ内の設定ファイルに保存される。
+
+これらの設定ファイルはこのプロジェクトに固有である。他のプロジェクトとも設定を同期したい場合は **dotfiles** を使う。
+
+### VS Code による dotfiles の設定
+
+VS Code のユーザー設定で、自分の dotfiles の GitHub リポジトリを指定することができる。
+詳しくは <https://code.visualstudio.com/docs/remote/containers#_personalizing-with-dotfile-repositories> を参照のこと。
+
+この設定を利用する場合は、衝突を避けるためデフォルトの dotfiles のマウントを無効化する。
+これには `.env` ファイルに以下の行を加える:
+
+```
+DOTFILES_DIR_HOST=/dev/null
+DOTFILES_INSTALL_COMMAND=":"
+```
+
+### dotfiles のマウント
+
+Docker ホスト上にある共通 dotfiles ディレクトリ（例: `~/dotfiles`）をコンテナにマウントすることもできる。
+その場合は例えば次のように `.env` ファイルを編集して、Docker ホスト上のディレクトリパスとコンテナへのマウント先パス、およびインストール用コマンドを指定する。
+
+```
+DOTFILES_DIR_HOST=~/dotfiles
+DOTFILES_DIR_CONTAINER=/home/rstudio/dotfiles
+DOTFILES_INSTALL_COMMAND="~/dotfiles/install.sh"
+```
+
+### SSH 認証
+
+コンテナ内から GitHub に SSH で接続したい場合は、以下のステップに従う。
+
+1. SSH 鍵を作成し、それを GitHub アカウントに追加する。
+2. Docker ホスト上で SSH Agent を有効化する・
+3. 鍵を SSH Agent に追加する。
+4. VS Code によって自動的に SSH Agent のソケットがコンテナにマウントされ、コンテナ内から鍵が使えるようになる。
+
+### ワークスペースのパス
+
+デフォルトでは、このフォルダの親フォルダがコンテナの `/home/rstudio/project` にマウントされる。
+`.env` ファイルを編集することにより、マウント元とマウント先をそれぞれ変数 `LOCAL_WORKSPACE_FOLDER` と変数 `CONTAINER_WORKSPACE_FOLDER` で変更できる。
+
+例
+
+```
+LOCAL_WORKSPACE_FOLDER=../sub-dir
+CONTAINER_WORKSPACE_FOLDER=/home/rstudio/your-project-name
+```
+
+## 参考資料
+
+Git  
+- [Git - Book](https://git-scm.com/book/ja/v2)
+- [GitHub に SSH で接続する - GitHub Docs](https://docs.github.com/ja/authentication/connecting-to-github-with-ssh)
+
+Docker  
+- [Docker Desktop overview | Docker Documentation](https://docs.docker.com/desktop/)
+- [Compose specification | Docker Documentation](https://docs.docker.com/compose/compose-file/)
+- [docker compose | Docker Documentation](https://docs.docker.com/engine/reference/commandline/compose/)
+- [Networking features in Docker Desktop for Mac | Docker Documentation](https://docs.docker.com/desktop/mac/networking/#ssh-agent-forwarding)
+
+dotfiles  
+- [GitHub does dotfiles - dotfiles.github.io](https://dotfiles.github.io/)
+- [RStudio のオプション設定を dotfiles で管理する - terashim.com](https://terashim.com/posts/rstudio-dotfiles/)
+
+RStudio  
+- [RStudio - RStudio](https://rstudio.com/products/rstudio/#rstudio-server)
+- [RStudio 1.3 Preview: Configuration and Settings | RStudio Blog](https://blog.rstudio.com/2020/02/18/rstudio-1-3-preview-configuration/)
+- [Customizing Keyboard Shortcuts – RStudio Support](https://support.rstudio.com/hc/en-us/articles/206382178-Customizing-Keyboard-Shortcuts)
+- [Version Control with Git and SVN – RStudio Support](https://support.rstudio.com/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN)
+- [Rocker Project](https://www.rocker-project.org/)
+
+renv  
+- [Project Environments • renv](https://rstudio.github.io/renv/index.html)
+- [Using renv with Docker • renv](https://rstudio.github.io/renv/articles/docker.html)
+- [Rのパッケージ管理のためのrenvの使い方 - Qiita](https://qiita.com/okiyuki99/items/688a00ca9a58e42e3bfa)
+- [renv と Docker の相互運用パターン - terashim.com](https://terashim.com/posts/renv-docker-patterns/)
+
+Visual Studio Code Remote - Containers  
+- [Developing inside a Container using Visual Studio Code Remote Development](https://code.visualstudio.com/docs/remote/containers)
+- [【R】Windows10のRStudio Desktop使うのをやめてVSCodeからrockerコンテナ立ち上げている話 - Qiita](https://qiita.com/eitsupi/items/ae0f89266b560b4e7096#devcontainerdevcontainerjson)