Overleafのコンパイル時間制限に困ってませんか？😣【Docker + Overleaf-toolkit + VSCode + Overleaf Workshop】  


## 1. はじめに

LaTeXを使って論文を執筆する上で、Overleafは非常に便利です。  
ブラウザさえあれば環境構築の手間が不要で、共同執筆も簡単であり、コメント機能を使って添削などのやり取りもしやすく、さらに文献管理ツール（Paperpileなど）の連携も非常に便利です。

ですが、論文の文量や図が増え、ファイルサイズが大きくなると、無課金版のOverleafは一定時間分しかコンパイルしてくれません😣  
そこで、本記事では、

- **高速なコンパイルが可能なOverleafのローカル環境を構築**  
  Overleaf-toolkit を導入するだけです

- **優秀なテキストエディタでもあるVisual Studio Codeで、Overleafと全く同じようにコンパイルできるようにする**  
  VSCodeの拡張機能 Overleaf Workshop を導入するだけです。  
  TeXLiveやMiKTeXといったディストリビューションをローカルにインストールする必要はありません。  
  上で導入した Overleaf-toolkit をエンジン（LaTeXの処理系）として使います。

- **無課金でもGit/GitHubで管理できるようにする**  
  ちょっと力技ですが、ローカルのOverleafで編集した内容をGitで管理できます。


- **ブラウザのOverleafとも連携する**  
  共同編集者にOverleaf課金ユーザーが一人でもいれば、
  **_ブラウザのOverleaf <-> GitHub  <-> ローカルのOverleaf_**
  の連携が（一応）実現できます！

:::note warn
ブラウザのOverleaf <-> GitHub  <-> ローカルのOverleaf 
の連携ができて、環境構築でローカルの環境を汚したくないという思いから、今回紹介する環境を構築しましたが、正直煩雑な手続きも多いです...
普通にTeXLiveを入れるか、[DockerのImage](https://hub.docker.com/r/texlive/texlive)を利用するか、大人しくOverleafに課金しても良いと思います。
:::


---

## 2. 必要なもの

本記事ではWindows環境を想定しています。

- **Docker Desktop (docker, docker compose)**  
  *導入は省略します*\
  [docker公式](https://www.docker.com/)
- **Visual Studio Code**  
  *導入は省略します*  
  [Visual Studio Code公式](https://code.visualstudio.com/)
- **Git bash (git, bash)**  
  *導入は省略します*\
  [git公式](https://gitforwindows.org/)
- **Overleaf アカウント**\
  [Overleaf](https://www.overleaf.com/)
- **GitHub アカウント**  
  学生なら[GitHub Copilot](https://docs.github.com/ja/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer)が**無料**です。VSCodeと連携することで、VSCode上での執筆が快適になります。
  

---

## 3. Overleaf-toolkitの導入

### 参考リンク
- [公式のQuick-Start Guide](https://github.com/overleaf/toolkit)
- [Overleaf環境をローカルに構築して、変更をGit連携のオンラインプロジェクトに反映する - Qiita](https://qiita.com/kompeki/items/1434161f4c46f22b727f)  
  主にこの記事を参考にして導入しました。以下の説明は僭越ながらそのまま引用したものです。

---

### 手順

#### 1. 適当なディレクトリでフォルダを作成  
`C:\User\username`直下に作成する例です。

```bash
C:\User\username> mkdir Overleaf
C:\User\username> cd Overleaf
```

#### 2. リポジトリをクローン（Quick-Start Guideの通り）

```bash
$ git clone https://github.com/overleaf/toolkit.git ./overleaf-toolkit
```

#### 3. クローンしたディレクトリに移動

```bash
$ cd ./overleaf-toolkit
```

#### 4. `config` ディレクトリに初期設定ファイルを作成

```bash
$ bin/init
```

#### 5. 初期設定ファイルを確認

```bash
$ ls config
overleaf.rc     variables.env     version
```

と出力されていればOKです。

#### 6. Dockerを起動

```bash
$ bin/up
```

**Windows環境でのエラー対処**  
（2024/12/17現在）以下のエラーが発生することがあります：

```
Error response from daemon: mount denied: the source path "/Users/username/Desktop/overleaf/overleaf-toolkit/data/overleaf:C:/Program Files/Git/var/lib/overleaf:rw"
too many colons
```

`lib/docker-compose.base.yml` の`volumes` の部分を手動で書き換えます。

```yaml
volumes:
  - "${OVERLEAF_DATA_PATH}:/var/lib/overleaf"
```

#### 7. Dockerを起動（再試行）

```bash
$ bin/up
```

自分は3分ほどかかりました。

#### 8. localhostに接続

ブラウザで以下のURLにアクセスします：

```
http://localhost/launchpad
```

アカウント作成画面が表示されれば成功です。
メールアドレスとパスワードを適当に設定しログインして、画面右下の**Start Using Our Overleaf Instance**をクリックすると、通常のOverleafホーム画面に遷移します。
これで、オフライン環境下でOverleafが使えるようになりました。

**二回目以降の起動**  

```bash
$ bin/up
```

または

```bash
$ bin/start
```

**コンテナ停止**  

```bash
$ bin/stop
```

#### 9. 日本語対応

このままでは、英語でしかoverleafを使えないので、
[こちらの記事](https://qiita.com/kompeki/items/1434161f4c46f22b727f#%E6%97%A5%E6%9C%AC%E8%AA%9E%E5%AF%BE%E5%BF%9C)を参考に設定します。


1. **コンテナに入る**
   以下のコマンドでコンテナに入ります。
   ```bash
   docker exec -it sharelatex bash
   ```

2. **TeX Liveの全パッケージをインストール**
   コンテナ内で、TeX Live Managerを使ってすべてのパッケージをインストールします。
   ```bash
   tlmgr install scheme-full
   ```

3. **シンボリックリンクを作成**
   以下の手順でシンボリックリンクを作成します。
   - TeX Liveのバージョンを確認します（`{year}`に該当）。
     ```bash
     ls /usr/local/texlive/
     ```
   - プラットフォームを確認します（`{platform}`に該当）。
     ```bash
     ls /usr/local/texlive/{year}/bin/
     ```
   - 以下のコマンドを実行し、`{year}`と`{platform}`を確認した値に置き換えます。
     ```bash
     ln -s /usr/local/texlive/{year}/bin/{platform}/uplatex /usr/local/bin/uplatex
     ln -s /usr/local/texlive/{year}/bin/{platform}/upbibtex /usr/local/bin/upbibtex
     ln -s /usr/local/texlive/{year}/bin/{platform}/platex /usr/local/bin/platex
     ln -s /usr/local/texlive/{year}/bin/{platform}/pbibtex /usr/local/bin/pbibtex
     ln -s /usr/local/texlive/{year}/bin/{platform}/mendex /usr/local/bin/mendex
     ```

4. **コンテナから退出**
   リンク作成後、以下のコマンドでコンテナから退出します。
   ```bash
   exit
   ```

---

#### 永続化の設定

インストールが完了しても、このままコンテナを停止するとデータが失われます。永続化するために以下の手順を行います。

- **Dockerイメージのコミット、タグの設定**  
  以下のようにイメージを保存します。タグには適当な名前（例: `5.2.1-with-texlive-full`）を付けます。
  ```bash
  docker commit sharelatex sharelatex/sharelatex:5.2.1-with-texlive-full
  ```

- **バージョンの指定**  
  `lib/shared-functions.sh`内の`function read_image_version()`が正しく読み込めるようにバージョン名の設定を行います。（`with-texlive-full`のタグ名だと、エラーを吐きます）  
  さらに、以下のように`config/version`に指定したバージョンを書き込みます。
  ```bash
  5.2.1-with-texlive-full
  ```

---



#### 9.1 (Optional) Overleaf Docker 環境で `biblatex` と `biber` を使用する設定

ここでは、Overleaf の Docker 環境で `biblatex` を利用する際に必要な `biber` の設定方法について説明します。特に、`biber` 実行ファイルがシステムの `PATH` に含まれておらず、利用できない問題を解決します。

`config/variables.env`の適当な行に以下を追加します。
```bash
# Add PATH
PATH=/usr/local/texlive/2024/bin/x86_64-linux:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```





#### 10. ローカルのOverleafを試す

- 再び `http://localhost/launchpad` に接続します。  
- "New Project" から適当に、Example Project or Blank Projectを作成し、編集・コンパイルができることを確認します。

---


## 4. Overleaf Workshop との連携

### 1. VSCodeにOverleaf Workshopを導入

1. **VSCodeの拡張機能をインストール**  
   `ctrl + shift + X`で拡張機能検索欄を開き、「Overleaf Workshop」を検索してインストールします。  
   - 拡張機能の詳細：[Overleaf Workshop GitHub](https://github.com/iamhyc/Overleaf-Workshop)

---

### 2. ブラウザOverleafとVSCodeを連携

ブラウザ上のOverleafとVSCodeを連携するために、**Cookie情報**を利用します。


1. Cookie情報を取得して連携  
Overleaf Workshop が導入できていると左のサイドバーに、新たなアイコンが出現し、そこからcookieによる接続ができるようになります。  
**詳細は、次の記事を参考にしてください**：  [Overleaf WorkshopのCookie連携方法 - Qiita](https://qiita.com/haradakaito/items/26ae779db23a1c862158)  
![connect.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3340883/28bff654-90ff-44cd-3fe1-ce1a4313b9da.png)


1. VSCode上でコンパイル確認  
   - **`ctrl + alt + B`**でコンパイルできます。
   - 左下の青色の`><`の隣が `www.overleaf.com` となっていることを確認します。
   - VScodeの下の`LaTeX`などのコンパイラの名前があるところからコンパイラやコンパイル対象を変更できます。 
![vscode_online.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3340883/7e61c4aa-59ed-f11d-1a6d-59565302ba38.png)

---

### 3. localhostのOverleafとVSCodeを連携

ローカル環境で立ち上げたOverleaf（localhost）とVSCodeを連携します。


1. **Overleaf Workshop設定にlocalhostを追加**  
   左サイドバーの「Overleaf Workshop」から `HOSTS` の `+` をクリックし、`http://localhost` を追加します。  
![plus.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3340883/461437f1-6015-1751-a2fc-031566a3017f.png)


2. **接続・Cookie連携**  
   ブラウザと同様に、Cookie連携を設定します。
   ![locallogin.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3340883/014e8041-eae4-fa2e-1775-befff4d37310.png)

3. **動作確認**  
   - `ctrl + alt + B`でコンパイルできます。
   - 左下の青色の`><`の隣が `localhost` になっていることを確認します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3340883/8f83e26b-e2e4-6964-1749-3a40b678134a.png)
   

---

## 5. GithubとローカルのOverleaf間のファイル共有

---

### 1. Githubでレポジトリを作成し、クローン

1.  レポジトリを作成
   - GitHubにログインし、画面右上の「+」アイコンをクリックし、「New repository」 を選択します。
   - レポジトリ名を入力します（例: test_tex）。
   - 緑色の「Code」ボタンをクリックし、https://github.com/username/test_tex.git）をコピーします。

2. レポジトリをクローン
   - 適当なディレクトリに移動します。（例: C:\User\username\git-clone）
   - 以下のコマンドを実行します
    ```bash
    git clone https://github.com/username/test_tex.git
    ```
   - ディレクトリ`C:\User\username\git-clone\test_tex`が作成されていればOKです。

---

### 2. ローカルレポジトリとOverleafをOverleaf Workshopの機能で同期

1. プロジェクトを作成
   - ローカルのOverleafから、新たにプロジェクトを作成します。ここでProject名として、`レポジトリ名+Project`などどすることをお勧めします。（例: `test_tex_project`）
2. Overleaf Workshopの機能で同期
   - VSCodeのOverleaf Workshopから、先ほどのプロジェクトを開きます。左下の青色の`><`の隣が `localhost` になっていることを確認します。
   - `ctrl + shift + P` で **「Configure Source Control」** -> **「Local Replica」** を選択します。
     このとき、レプリカの保存先を先ほどのクローンレポジトリのディレクトリを選択します。
     例: `C:\User\username\git-clone\test_tex`
   - ディレクトリ`C:\User\username\git-clone\test_tex\test_tex_project`が作成されていればOKです。

3. Gitによる管理
   - `C:\User\username\git-clone\test_tex`　をVSCodeで開きます。左下の青色の`><`の隣に何もないことを確認します。
   - `C:\User\username\git-clone\test_tex\test_tex_project`が増えた分のchangeがあるので、VSCodeのGUIのGitからcommit, sync changeできます。
   - もちろん、CUIからgit add, commit, push してもらってもよいです。

**注意！**：レポジトリのディレクトリ構造は以下のようになるようにしましょう  
レプリカ先のディレクトリと.gitのディレクトリを同じにしてしまうと、.gitをレプリカの際に上書きしてしまいまいます😣
```text
repositly_name
　├ .git
　├ project_name（レプリカ先）
　 　├ latexmkrc
　 　└ main.tex
```


---

## 6. ブラウザのOverleafとの連携（要課金）
OverleafとGithug/Gitとの連携は課金が必要です。  
ですが、Overleafの共同編集者のうちだれか一人でも課金ユーザーなら他の人もGithubとの同期が可能です。  
[公式の説明](https://www.overleaf.com/learn/how-to/GitHub_Synchronization) に倣って、課金ユーザーにOverleafとGithugの連携をしてもらいます。

1. OverleafとGitHubの連携を設定
   - OverleafのGitHub連携ページで「Connect to GitHub」から、GitHubアカウントとの連携を承認します。
   - Overleafのプロジェクトメニューから、Sync GitHub から新たなレポジトリを作成します。
2. Overleaf上でgithubと同期  
       Overleaf上で「Push/Pull Changes to GitHub」をクリックすると、プロジェクトの変更内容がGitHubリポジトリにPush/Pullされます。**これは課金ユーザーでなくてもできます！**

ここで作成したレポジトリを、[5. GithubとローカルのOverleaf間のファイル共有](##5GithubとローカルのOverleaf間のファイル共有) におけるレポジトリとして指定する事で、  
**ブラウザのOverleaf <-> GitHubのリモートレポジトリ <-> ローカルレポジトリ（レプリカ） <-> ローカルのOverleaf**  
が連携されます！

---

## まとめ

今回構築した環境により、以下のことが可能になりました：

✅ **高速なコンパイル**：Overleaf-toolkitにより、ローカルでコンパイル時間の制限なく高速に処理できます。  
✅ **VSCodeでの編集とコンパイル**：Overleaf Workshopを導入することで、VSCode上でOverleafと同じ操作が可能です。  
✅ **Git/GitHubでの管理**：無課金でもGit/GitHubを利用してOverleafが利用できます。  
✅ **ブラウザOverleafとの連携**：共同編集者にOverleaf課金ユーザーが一人でもいれば、ブラウザのOverleafとローカルのOverleafを一つのGithubレポジトリで管理できます。


---

### 注意点と課題

- **ローカルOverleafの起動時間**：Dockerコンテナを立ち上げるのに約30秒程度かかります。  
- **同期の不安定さ**：ローカルレポジトリ（レプリカ） <-> ローカルのOverleafの同期はやや不安定です。  

---


# いかがでしたか？
この記事が気に入ったなら是非、記事の上下にある**いいね**💛を押して下さいね！それでは皆さんも良きOverleaf生活を！